@centerforagenticai/pi-multi-account 0.1.1

package/src/subscription-plan-catalog.ts

@@ -0,0 +1,346 @@
+/**
+ * Editable, versioned subscription-plan preset catalog.
+ *
+ * The catalog ships as JSON data at `config/subscription-plans.v1.json` so an
+ * operator can inspect and edit it without reading TypeScript. This module
+ * only validates and merges that data; it never encodes provider, account
+ * type, or price information as a TypeScript constant, switch statement, or
+ * map.
+ *
+ * Every shipped preset is an operator-provided monthly-equivalent USD
+ * comparison default, not a researched provider entitlement or independently
+ * verified official price. A label containing "5x" or "20x" is display text
+ * only -- this module derives no token allowance, quota multiplier,
+ * throughput, or availability claim from it, and reads no provider quota
+ * source.
+ *
+ * Machine-global configuration (`src/config.ts`) may supply
+ * `subscriptionPlanCatalogOverrides`, keyed by preset id: a key that matches a
+ * shipped id replaces that preset; any other key adds a validated custom
+ * preset. `src/config.ts` documents "No project-local override loading." --
+ * there is no project-scoped catalog layer, and this module never reads one.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CATALOG_PROVIDERS = ["chatgpt", "anthropic"] as const;
+export type CatalogProvider = (typeof CATALOG_PROVIDERS)[number];
+
+export const CATALOG_ACCOUNT_TYPES = ["individual", "business", "team"] as const;
+export type CatalogAccountType = (typeof CATALOG_ACCOUNT_TYPES)[number];
+
+export const CATALOG_PRODUCT_BASES = ["per-account"] as const;
+export type CatalogProductBasis = (typeof CATALOG_PRODUCT_BASES)[number];
+
+export const MAX_PRESET_ID_LENGTH = 64;
+const MAX_LABEL_LENGTH = 64;
+const MAX_PROVENANCE_LENGTH = 256;
+
+/** Lowercase, hyphen-separated identifier shape shared by every preset id. */
+export const PRESET_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export interface SubscriptionPlanPreset {
+	readonly id: string;
+	readonly provider: CatalogProvider;
+	readonly accountType: CatalogAccountType;
+	readonly label: string;
+	readonly monthlyUsd: number;
+	readonly productBasis: CatalogProductBasis;
+	readonly provenance: string;
+}
+
+export interface SubscriptionPlanCatalog {
+	readonly version: number;
+	readonly presets: readonly SubscriptionPlanPreset[];
+}
+
+/** Machine-global override entry: a preset's fields, keyed externally by id. */
+export type SubscriptionPlanCatalogOverride = Omit<SubscriptionPlanPreset, "id">;
+
+export class SubscriptionPlanCatalogError extends Error {
+	constructor(message: string) {
+		super(`[subscription-plan-catalog] ${message}`);
+		this.name = "SubscriptionPlanCatalogError";
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCatalogProvider(value: unknown): value is CatalogProvider {
+	return (
+		typeof value === "string" &&
+		(CATALOG_PROVIDERS as readonly string[]).includes(value)
+	);
+}
+
+function isCatalogAccountType(value: unknown): value is CatalogAccountType {
+	return (
+		typeof value === "string" &&
+		(CATALOG_ACCOUNT_TYPES as readonly string[]).includes(value)
+	);
+}
+
+function isCatalogProductBasis(value: unknown): value is CatalogProductBasis {
+	return (
+		typeof value === "string" &&
+		(CATALOG_PRODUCT_BASES as readonly string[]).includes(value)
+	);
+}
+
+function isBoundedString(value: unknown, maxLength: number): value is string {
+	return (
+		typeof value === "string" &&
+		value.trim().length > 0 &&
+		value.length <= maxLength
+	);
+}
+
+function validateProvider(value: unknown, context: string): CatalogProvider {
+	if (!isCatalogProvider(value)) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.provider must be one of [${CATALOG_PROVIDERS.join(", ")}].`,
+		);
+	}
+	return value;
+}
+
+function validateAccountType(value: unknown, context: string): CatalogAccountType {
+	if (!isCatalogAccountType(value)) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.accountType must be one of [${CATALOG_ACCOUNT_TYPES.join(", ")}].`,
+		);
+	}
+	return value;
+}
+
+function validateLabel(value: unknown, context: string): string {
+	if (!isBoundedString(value, MAX_LABEL_LENGTH)) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.label must be a non-empty string of at most ${MAX_LABEL_LENGTH} characters.`,
+		);
+	}
+	return value;
+}
+
+function validateMonthlyUsd(value: unknown, context: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.monthlyUsd must be a finite, non-negative USD amount.`,
+		);
+	}
+	return value;
+}
+
+function validateProductBasis(value: unknown, context: string): CatalogProductBasis {
+	if (!isCatalogProductBasis(value)) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.productBasis must be one of [${CATALOG_PRODUCT_BASES.join(", ")}].`,
+		);
+	}
+	return value;
+}
+
+function validateProvenance(value: unknown, context: string): string {
+	if (!isBoundedString(value, MAX_PROVENANCE_LENGTH)) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.provenance must be a non-empty string of at most ${MAX_PROVENANCE_LENGTH} characters.`,
+		);
+	}
+	return value;
+}
+
+const PRESET_FIELDS = new Set([
+	"id",
+	"provider",
+	"accountType",
+	"label",
+	"monthlyUsd",
+	"productBasis",
+	"provenance",
+]);
+
+/**
+ * Validates one candidate preset object. Allowlists exactly the fields above
+ * and rejects any other field -- including an entitlement-, quota-, or
+ * verification-timestamp-shaped one -- before it can enter the effective
+ * catalog. An explicit `monthlyUsd: 0` is valid.
+ */
+export function parseSubscriptionPlanPreset(
+	value: unknown,
+	context: string,
+): SubscriptionPlanPreset {
+	if (!isRecord(value)) {
+		throw new SubscriptionPlanCatalogError(`${context} must be a JSON object.`);
+	}
+	const unknownKeys = Object.keys(value).filter((key) => !PRESET_FIELDS.has(key));
+	if (unknownKeys.length > 0) {
+		throw new SubscriptionPlanCatalogError(
+			`${context} has unsupported field "${unknownKeys[0]}".`,
+		);
+	}
+	const id = value["id"];
+	if (!isBoundedString(id, MAX_PRESET_ID_LENGTH) || !PRESET_ID_PATTERN.test(id)) {
+		throw new SubscriptionPlanCatalogError(
+			`${context}.id must be a lowercase, hyphen-separated identifier of at most ${MAX_PRESET_ID_LENGTH} characters.`,
+		);
+	}
+	return {
+		id,
+		provider: validateProvider(value["provider"], context),
+		accountType: validateAccountType(value["accountType"], context),
+		label: validateLabel(value["label"], context),
+		monthlyUsd: validateMonthlyUsd(value["monthlyUsd"], context),
+		productBasis: validateProductBasis(value["productBasis"], context),
+		provenance: validateProvenance(value["provenance"], context),
+	};
+}
+
+const OVERRIDE_FIELDS = new Set([
+	"provider",
+	"accountType",
+	"label",
+	"monthlyUsd",
+	"productBasis",
+	"provenance",
+]);
+
+/**
+ * Validates one machine-global override object. The preset id is the map key
+ * in `subscriptionPlanCatalogOverrides`, not a field on this object, so `id`
+ * is rejected here as an unsupported field.
+ */
+export function parseSubscriptionPlanCatalogOverride(
+	value: unknown,
+	context: string,
+): SubscriptionPlanCatalogOverride {
+	if (!isRecord(value)) {
+		throw new SubscriptionPlanCatalogError(`${context} must be a JSON object.`);
+	}
+	const unknownKeys = Object.keys(value).filter((key) => !OVERRIDE_FIELDS.has(key));
+	if (unknownKeys.length > 0) {
+		throw new SubscriptionPlanCatalogError(
+			`${context} has unsupported field "${unknownKeys[0]}".`,
+		);
+	}
+	return {
+		provider: validateProvider(value["provider"], context),
+		accountType: validateAccountType(value["accountType"], context),
+		label: validateLabel(value["label"], context),
+		monthlyUsd: validateMonthlyUsd(value["monthlyUsd"], context),
+		productBasis: validateProductBasis(value["productBasis"], context),
+		provenance: validateProvenance(value["provenance"], context),
+	};
+}
+
+/**
+ * Parses one complete catalog document: a positive integer `version` and an
+ * array of presets with distinct ids. Used for both the shipped asset and any
+ * test fixture that exercises catalog-shape validation.
+ */
+export function parseSubscriptionPlanCatalog(value: unknown): SubscriptionPlanCatalog {
+	if (!isRecord(value)) {
+		throw new SubscriptionPlanCatalogError("Catalog must be a JSON object.");
+	}
+	const unknownKeys = Object.keys(value).filter(
+		(key) => key !== "version" && key !== "presets",
+	);
+	if (unknownKeys.length > 0) {
+		throw new SubscriptionPlanCatalogError(
+			`Catalog has unsupported field "${unknownKeys[0]}".`,
+		);
+	}
+	const version = value["version"];
+	if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+		throw new SubscriptionPlanCatalogError(
+			"Catalog version must be a positive integer.",
+		);
+	}
+	const presetsValue = value["presets"];
+	if (!Array.isArray(presetsValue)) {
+		throw new SubscriptionPlanCatalogError("Catalog presets must be an array.");
+	}
+	const presets: SubscriptionPlanPreset[] = [];
+	const seenIds = new Set<string>();
+	presetsValue.forEach((candidate, index) => {
+		const preset = parseSubscriptionPlanPreset(candidate, `presets[${index}]`);
+		if (seenIds.has(preset.id)) {
+			throw new SubscriptionPlanCatalogError(
+				`Catalog contains duplicate preset id "${preset.id}".`,
+			);
+		}
+		seenIds.add(preset.id);
+		presets.push(preset);
+	});
+	return { version, presets: Object.freeze(presets) };
+}
+
+const SHIPPED_CATALOG_PATH = join(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"config",
+	"subscription-plans.v1.json",
+);
+
+/**
+ * Loads and validates the shipped catalog asset directly from disk on every
+ * call. Read-only: never copies, caches to another location, or writes
+ * anything, including on first run.
+ */
+export function loadShippedSubscriptionPlanCatalog(): SubscriptionPlanCatalog {
+	const raw = readFileSync(SHIPPED_CATALOG_PATH, "utf-8");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new SubscriptionPlanCatalogError(
+			`Shipped catalog at ${SHIPPED_CATALOG_PATH} is not valid JSON.`,
+		);
+	}
+	return parseSubscriptionPlanCatalog(parsed);
+}
+
+/**
+ * Merges machine-global overrides into a base catalog. An override id that
+ * matches an existing preset id replaces that preset in place; any other
+ * override id appends a validated custom preset. The merged catalog keeps the
+ * base catalog's `version` -- overrides change presets, not the shipped
+ * asset's data version.
+ */
+export function resolveSubscriptionPlanCatalog(
+	base: SubscriptionPlanCatalog,
+	overrides: Readonly<Record<string, SubscriptionPlanCatalogOverride>>,
+): SubscriptionPlanCatalog {
+	const byId = new Map<string, SubscriptionPlanPreset>();
+	for (const preset of base.presets) {
+		byId.set(preset.id, preset);
+	}
+	for (const [id, override] of Object.entries(overrides)) {
+		byId.set(id, { id, ...override });
+	}
+	return {
+		version: base.version,
+		presets: Object.freeze([...byId.values()]),
+	};
+}
+
+/** Loads the shipped catalog and applies machine-global overrides in one call. */
+export function loadEffectiveSubscriptionPlanCatalog(
+	overrides: Readonly<Record<string, SubscriptionPlanCatalogOverride>>,
+): SubscriptionPlanCatalog {
+	return resolveSubscriptionPlanCatalog(
+		loadShippedSubscriptionPlanCatalog(),
+		overrides,
+	);
+}
+
+/** Finds a preset by id in an already-resolved catalog, or `undefined`. */
+export function findSubscriptionPlanPreset(
+	catalog: SubscriptionPlanCatalog,
+	presetId: string,
+): SubscriptionPlanPreset | undefined {
+	return catalog.presets.find((preset) => preset.id === presetId);
+}

package/src/tier-model-resolver.ts

@@ -0,0 +1,46 @@
+export type TierModelDestination = "anthropic" | "openai" | "openrouter";
+
+export type TierModelMap = Readonly<
+	Partial<Record<TierModelDestination, Readonly<Record<string, string>>>>
+>;
+
+export const MAX_TIER_MODEL_ID_LENGTH = 256;
+
+const TIER_MODEL_DESTINATIONS: readonly TierModelDestination[] = [
+	"anthropic",
+	"openai",
+	"openrouter",
+];
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/u;
+
+function isTierModelDestination(
+	value: unknown,
+): value is TierModelDestination {
+	return TIER_MODEL_DESTINATIONS.includes(value as TierModelDestination);
+}
+
+function isValidRequestedModel(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value !== "*" &&
+		value.length > 0 &&
+		value.length <= MAX_TIER_MODEL_ID_LENGTH &&
+		value.trim().length > 0 &&
+		!CONTROL_CHARACTER.test(value)
+	);
+}
+
+export function resolveTierModel(
+	requested: string,
+	destination: TierModelDestination,
+	catalog: readonly string[],
+	map: TierModelMap,
+): string | undefined {
+	if (!isValidRequestedModel(requested) || !isTierModelDestination(destination)) {
+		return undefined;
+	}
+	if (catalog.includes(requested)) return requested;
+
+	const mapped = map[destination]?.[requested];
+	return mapped !== undefined && catalog.includes(mapped) ? mapped : undefined;
+}

package/src/upstream-anthropic.ts

@@ -0,0 +1,315 @@
+import type {
+  ExtensionAPI,
+  ProviderConfig,
+  ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
+import { registerApiProvider } from "@earendil-works/pi-ai/compat";
+import {
+  ANTHROPIC_ALIAS_API,
+  createAnthropicAliasStream,
+  type AnthropicUpstreamStream,
+} from "./anthropic-alias-stream.js";
+import { streamAnthropicAdaptive } from "./anthropic-adaptive-stream.js";
+import { toPinnedAnthropicContext } from "./anthropic-context-compat.js";
+
+export type UpstreamAnthropicExtension = (pi: ExtensionAPI) => void;
+
+/**
+ * Identifies this package's entries in pi-ai's process-global API registry, so
+ * ownership is explicit and removal is precise. The registry is keyed by API id
+ * with no ownership check, so the tag is the only ownership record there is.
+ */
+export const ALIAS_API_SOURCE_ID = "hyphagroup-pi-multi-account";
+
+/**
+ * The registration seam, injected only so a test can prove the fail-closed
+ * contract. Production always uses pi-ai compat's real registrar.
+ */
+export type AliasApiRegistrar = (
+  aliasStream: AnthropicUpstreamStream,
+) => void;
+
+const UPSTREAM_ENTRYPOINT = "../packages/pi-anthropic-oauth/src/index.ts";
+
+const isRecord = (value: unknown): value is Record<PropertyKey, unknown> =>
+  typeof value === "object" && value !== null;
+
+/** Loads the package entrypoint by variable specifier so TypeScript does not
+ * compile third-party source under this repository's stricter compiler flags.
+ * Pi's extension loader (jiti) resolves the exact installed TypeScript module.
+ */
+export async function loadUpstreamAnthropicExtension(): Promise<UpstreamAnthropicExtension> {
+  const loaded: unknown = await import(UPSTREAM_ENTRYPOINT);
+  if (!isRecord(loaded) || typeof loaded.default !== "function") {
+    throw new UpstreamAnthropicContractError(
+      "package entrypoint did not export a default extension function",
+    );
+  }
+  return loaded.default as UpstreamAnthropicExtension;
+}
+
+type CompleteAnthropicProviderConfig = ProviderConfig & {
+  oauth: NonNullable<ProviderConfig["oauth"]>;
+  streamSimple: NonNullable<ProviderConfig["streamSimple"]>;
+};
+
+export interface CapturedAnthropicProvider {
+  readonly name: "anthropic";
+  readonly config: CompleteAnthropicProviderConfig;
+}
+
+export class UpstreamAnthropicContractError extends Error {
+  constructor(message: string) {
+    super(
+      `[pi-anthropic-oauth contract] ${message} Run npm run upstream:check and review UPSTREAM.md before release.`,
+    );
+    this.name = "UpstreamAnthropicContractError";
+  }
+}
+
+function assertCompleteConfig(
+  config: ProviderConfig,
+): asserts config is CompleteAnthropicProviderConfig {
+  if (config.api !== "anthropic-messages") {
+    throw new UpstreamAnthropicContractError(
+      `expected provider api anthropic-messages, received ${String(config.api)}`,
+    );
+  }
+  // pi-anthropic-oauth 0.2.0 registers the base provider WITHOUT a `models`
+  // field — Pi host-resolves the anthropic catalog from its built-in provider
+  // layer. A captured `models` array is therefore optional; alias catalogs are
+  // sourced from the live model registry (see index.ts), not the captured
+  // config. If a `models` field is present it must still be a non-empty array.
+  if (config.models !== undefined) {
+    if (!Array.isArray(config.models) || config.models.length === 0) {
+      throw new UpstreamAnthropicContractError(
+        "captured provider supplied a models field that is not a non-empty array",
+      );
+    }
+  }
+  if (!config.oauth) {
+    throw new UpstreamAnthropicContractError(
+      "captured provider did not supply OAuth callbacks",
+    );
+  }
+  if (typeof config.oauth.login !== "function") {
+    throw new UpstreamAnthropicContractError("captured OAuth login is missing");
+  }
+  if (typeof config.oauth.refreshToken !== "function") {
+    throw new UpstreamAnthropicContractError(
+      "captured OAuth refreshToken is missing",
+    );
+  }
+  if (typeof config.oauth.getApiKey !== "function") {
+    throw new UpstreamAnthropicContractError(
+      "captured OAuth getApiKey is missing",
+    );
+  }
+  if (typeof config.streamSimple !== "function") {
+    throw new UpstreamAnthropicContractError(
+      "captured provider did not supply streamSimple",
+    );
+  }
+}
+
+function createCaptureProxy(
+  pi: ExtensionAPI,
+  registrations: Array<{ name: string; config: ProviderConfig }>,
+): ExtensionAPI {
+  return new Proxy(pi, {
+    get(target, property, receiver) {
+      if (property === "registerProvider") {
+        return (name: string, config: ProviderConfig): void => {
+          registrations.push({ name, config });
+        };
+      }
+
+      const value = Reflect.get(target, property, receiver) as unknown;
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+/**
+ * Invokes the exact-pinned upstream entrypoint against a delegating proxy and
+ * returns its one Anthropic registration. Provider configuration is held only
+ * by reference; this path never serializes, inspects, or logs OAuth material.
+ */
+export function captureUpstreamAnthropicProvider(
+  pi: ExtensionAPI,
+  upstream: UpstreamAnthropicExtension,
+): CapturedAnthropicProvider {
+  const registrations: Array<{ name: string; config: ProviderConfig }> = [];
+  upstream(createCaptureProxy(pi, registrations));
+
+  if (registrations.length !== 1) {
+    throw new UpstreamAnthropicContractError(
+      `expected exactly one registerProvider call, received ${registrations.length}`,
+    );
+  }
+
+  const registration = registrations[0];
+  if (!registration || registration.name !== "anthropic") {
+    throw new UpstreamAnthropicContractError(
+      `expected registerProvider(\"anthropic\", config), received ${registration?.name ?? "no registration"}`,
+    );
+  }
+
+  assertCompleteConfig(registration.config);
+  return { name: "anthropic", config: registration.config };
+}
+
+/**
+ * Chooses the extension-owned exact-provenance adapter only for adaptive
+ * thinking requests. Every other request stays on the exact-pinned OAuth
+ * stream. Both receive the Pi 0.84 context shape they consume, reconstructed
+ * from Pi 0.87 transcript declarations when needed. Errors are not retried
+ * through the other implementation.
+ */
+export function createAnthropicStreamSelector(
+  adaptiveStream: AnthropicUpstreamStream,
+  pinnedStream: AnthropicUpstreamStream,
+): AnthropicUpstreamStream {
+  return (model, context, options) => {
+    const useAdaptiveStream =
+      (model.compat as { forceAdaptiveThinking?: boolean } | undefined)
+        ?.forceAdaptiveThinking === true && options?.reasoning !== undefined;
+    const selected = useAdaptiveStream ? adaptiveStream : pinnedStream;
+    return selected(model, toPinnedAnthropicContext(context), options);
+  };
+}
+
+/**
+ * Publishes the extension-owned alias API id into pi-ai's process-global API
+ * registry.
+ *
+ * Pi's own provider path never needs this: `provider-composer` short-circuits to
+ * the extension's `streamSimple` when `model.api` matches the extension's `api`.
+ * But any caller that dispatches by `model.api` through pi-ai compat resolves
+ * through this registry instead, and threw `No API provider registered for api:
+ * hypha-anthropic-oauth` without it (issue #11).
+ *
+ * Both registry slots share the one alias handler that wraps the derived
+ * selector, so the registry entry and every alias provider config dispatch
+ * identically by construction. The registry stores function references and the
+ * source id only; Pi resolves the alias credential per request and compat
+ * forwards it in `options.apiKey`.
+ */
+const registerAliasApiWithCompat: AliasApiRegistrar = (aliasStream) => {
+  // Deliberately uncast. `SimpleStreamOptions` extends `StreamOptions` with
+  // optional fields, so the one alias handler satisfies both slots today. If a
+  // pi-ai upgrade changes either handler signature, this must fail typecheck
+  // rather than be silently bridged by a cast.
+  registerApiProvider(
+    {
+      api: ANTHROPIC_ALIAS_API,
+      stream: aliasStream,
+      streamSimple: aliasStream,
+    },
+    ALIAS_API_SOURCE_ID,
+  );
+};
+
+/**
+ * Captures the exact-pinned registration, then derives a distinct base config
+ * that replaces only its stream handler with the stateless adaptive selector.
+ * OAuth callbacks and every other captured field remain reference-identical.
+ *
+ * Also registers the alias API id, because this is the one place that holds the
+ * derived selector every alias wraps, and it runs once per extension factory
+ * generation — which is exactly the registration's lifetime. Pi's `reload()`
+ * calls `resetApiProviders()` before rerunning factories, so the following
+ * generation restores the entry structurally.
+ *
+ * The registration is deliberately NOT wrapped in try/catch. A registrar failure
+ * must reject out of the extension factory so Pi omits the extension entirely,
+ * rather than publishing alias providers whose API id cannot resolve — which is
+ * the very defect this function fixes.
+ */
+export async function registerUpstreamAnthropicProvider(
+  pi: ExtensionAPI,
+  upstream?: UpstreamAnthropicExtension,
+  adaptiveStream: AnthropicUpstreamStream = streamAnthropicAdaptive,
+  registerAliasApi: AliasApiRegistrar = registerAliasApiWithCompat,
+): Promise<CapturedAnthropicProvider> {
+  const extension = upstream ?? (await loadUpstreamAnthropicExtension());
+  const captured = captureUpstreamAnthropicProvider(pi, extension);
+  const streamSimple = createAnthropicStreamSelector(
+    adaptiveStream,
+    captured.config.streamSimple,
+  );
+  const adapted: CompleteAnthropicProviderConfig = {
+    ...captured.config,
+    streamSimple: streamSimple as CompleteAnthropicProviderConfig["streamSimple"],
+  };
+  const derived: CapturedAnthropicProvider = {
+    name: captured.name,
+    config: adapted,
+  };
+  registerAliasApi(createAnthropicAliasStream(streamSimple));
+  pi.registerProvider(derived.name, derived.config);
+  return derived;
+}
+
+/**
+ * Re-asserts the derived base registration once every extension factory has run.
+ *
+ * A coexisting standalone `pi-anthropic-oauth` extension registers `anthropic`
+ * from its own factory. Pi merges a later registration's defined fields over an
+ * earlier one, so an extension-first load order would otherwise restore the
+ * pinned legacy handler on the base provider and adaptive base requests would
+ * fall back to budget thinking. Registering the same derived configuration
+ * object again leaves an equivalent effective configuration and handler.
+ *
+ * This is the one bounded base-provider exception recorded in AGENTS.md. It adds
+ * no shared state, lock, timer, or credential path, and it must not be repeated
+ * on a schedule. A later `session_start` handler, a post-load dynamic
+ * registration, or `unregisterProvider` remains out of scope.
+ */
+export function reassertAnthropicBaseRegistration(
+  pi: ExtensionAPI,
+  captured: CapturedAnthropicProvider,
+): void {
+  pi.registerProvider(captured.name, captured.config);
+}
+
+/**
+ * Builds an alias registration from captured upstream behavior. OAuth callback
+ * identities are preserved; only the API dispatch identity is rebound to the
+ * extension-owned adapter. The `models` catalog is REQUIRED and supplied by the
+ * caller from the live model registry — pi-anthropic-oauth 0.2.0 no longer
+ * carries a `models` field on the captured base config, and alias provider ids
+ * have no built-in base provider for Pi to inherit a catalog from.
+ */
+export function createAnthropicAliasProviderConfig(
+  captured: CapturedAnthropicProvider,
+  models: readonly ProviderModelConfig[],
+): ProviderConfig {
+  if (models.length === 0) {
+    throw new UpstreamAnthropicContractError(
+      "cannot register an Anthropic alias with an empty model catalog",
+    );
+  }
+  if (captured.config.api === ANTHROPIC_ALIAS_API) {
+    throw new UpstreamAnthropicContractError(
+      "extension-owned alias API must remain distinct from the base handler",
+    );
+  }
+
+  const upstreamStream = captured.config.streamSimple as unknown as AnthropicUpstreamStream;
+
+  const aliasStream = createAnthropicAliasStream(upstreamStream) as unknown as NonNullable<
+    ProviderConfig["streamSimple"]
+  >;
+
+  return {
+    ...captured.config,
+    api: ANTHROPIC_ALIAS_API,
+    models: models.map((model) => ({
+      ...model,
+      api: ANTHROPIC_ALIAS_API,
+    })),
+    oauth: captured.config.oauth,
+    streamSimple: aliasStream,
+  };
+}