@yansigit/opencodex 2.31.0

package/src/providers/replit/setup.ts

@@ -0,0 +1,350 @@
+import {
+  ConfigMutationLockError,
+  adoptPersistedProviderIntoLiveConfig,
+  mutatePersistedConfig,
+  readConfigAdmissionSnapshot,
+  type PersistedConfigMutationOutcome,
+} from "../../config";
+import { codexAccountNamespaceProviderCollisionError } from "../../codex/account-namespace-match";
+import { providerDestinationConfigError, providerDestinationResolvedError } from "../../lib/destination-policy";
+import { providerManagementConfigError } from "../../server/auth-cors";
+import { apiKeyPoolEntryId, sanitizeApiKeyValue } from "../api-keys";
+import type { OcxConfig, OcxProviderConfig } from "../../types";
+import {
+  MAX_REPLIT_GATEWAY_KEY_LENGTH,
+  MIN_REPLIT_GATEWAY_KEY_LENGTH,
+  REPLIT_ANTHROPIC_PROVIDER_ID,
+  REPLIT_DERIVED_PROVIDER_FIELDS,
+  REPLIT_GATEWAY_KEY_PATTERN,
+  REPLIT_OPENAI_PROVIDER_ID,
+  REPLIT_PROVIDER_PAIR_IDS,
+} from "./constants";
+import { deriveReplitProviderPair } from "./derive";
+import type { ValidatedReplitOrigin } from "./origin";
+import { validateReplitOrigin } from "./origin";
+import { probeReplitGateway, type ReplitGatewayProbeSuccess } from "./probe";
+import { preserveReplitCustomHeaders } from "./headers";
+
+export type { ReplitDerivedProvider, ReplitProviderPair } from "./derive";
+export { deriveReplitProviderPair, setReplitRegistrySeedTestHooks } from "./derive";
+export {
+  buildReplitGatewayProbeRequests,
+  probeReplitGateway,
+  type ReplitGatewayProbeFailure,
+  type ReplitGatewayProbeResult,
+} from "./probe";
+export {
+  isReplitCredentialHeader,
+  preserveReplitCustomHeaders,
+  REPLIT_CREDENTIAL_HEADER_NAMES,
+} from "./headers";
+
+export interface ReplitProviderCollision {
+  providerId: typeof REPLIT_PROVIDER_PAIR_IDS[number];
+}
+
+export interface ReplitProviderPairInput {
+  origin: string;
+  gatewayKey: string;
+  allowCustomDomain?: boolean;
+  replace?: boolean;
+  setDefault?: boolean;
+}
+
+export type MutatePersistedConfigFn = typeof mutatePersistedConfig;
+
+export interface InstallReplitProviderPairDeps {
+  probe?: typeof probeReplitGateway;
+  mutatePersistedConfig?: MutatePersistedConfigFn;
+  /** Test-only fetch injection for gateway probes. Production uses pinned outbound transport. */
+  probeFetch?: typeof globalThis.fetch;
+}
+
+export type InstallReplitProviderPairResult =
+  | { ok: true; providers: string[]; probe: ReplitGatewayProbeSuccess }
+  | {
+      ok: false;
+      code:
+        | "invalid_origin"
+        | "invalid_gateway_key"
+        | "provider_collision"
+        | "namespace_collision"
+        | "destination_rejected"
+        | "probe_failed"
+        | "config_busy"
+        | "persist_failed"
+        | "config_unavailable";
+      error: string;
+      collisions?: ReplitProviderCollision[];
+      probe?: import("./probe").ReplitGatewayProbeResult;
+    };
+
+const DERIVED_FIELD_SET = new Set<string>(REPLIT_DERIVED_PROVIDER_FIELDS);
+const PERSIST_FAILED_MESSAGE = "failed to persist replit provider pair";
+
+export function validateReplitGatewayKey(raw: unknown): { ok: true; key: string } | { ok: false; error: string } {
+  const key = sanitizeApiKeyValue(raw);
+  if (!key || key.length < MIN_REPLIT_GATEWAY_KEY_LENGTH) {
+    return {
+      ok: false,
+      error: `gateway key must be at least ${MIN_REPLIT_GATEWAY_KEY_LENGTH} characters`,
+    };
+  }
+  if (key.length > MAX_REPLIT_GATEWAY_KEY_LENGTH) {
+    return {
+      ok: false,
+      error: `gateway key must be at most ${MAX_REPLIT_GATEWAY_KEY_LENGTH} characters`,
+    };
+  }
+  if (!REPLIT_GATEWAY_KEY_PATTERN.test(key)) {
+    return { ok: false, error: "gateway key must contain only printable ASCII characters" };
+  }
+  return { ok: true, key };
+}
+
+export function detectReplitPairCollisions(config: OcxConfig): ReplitProviderCollision[] {
+  const collisions: ReplitProviderCollision[] = [];
+  for (const providerId of REPLIT_PROVIDER_PAIR_IDS) {
+    if (config.providers[providerId]) collisions.push({ providerId });
+  }
+  return collisions;
+}
+
+function collisionError(collisions: ReplitProviderCollision[]): string {
+  const names = collisions.map(row => row.providerId).join(", ");
+  return `replit provider pair already exists (${names}); set replace to true to overwrite`;
+}
+
+function namespaceCollisionError(config: OcxConfig): string | undefined {
+  for (const providerId of REPLIT_PROVIDER_PAIR_IDS) {
+    const error = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, providerId);
+    if (error) return error;
+  }
+  return undefined;
+}
+
+function activeGatewayKeyPool(gatewayKey: string): NonNullable<OcxProviderConfig["apiKeyPool"]> {
+  return [{ id: apiKeyPoolEntryId(gatewayKey), key: gatewayKey }];
+}
+
+export function preserveReplitProviderOverlays(
+  existing: OcxProviderConfig | undefined,
+  derived: OcxProviderConfig,
+  gatewayKey: string,
+): OcxProviderConfig {
+  const next: OcxProviderConfig = { ...derived, apiKey: gatewayKey, apiKeyPool: activeGatewayKeyPool(gatewayKey) };
+  if (!existing) return next;
+  for (const [key, value] of Object.entries(existing) as [keyof OcxProviderConfig, unknown][]) {
+    if (DERIVED_FIELD_SET.has(key) || value === undefined) continue;
+    if (key === "headers") {
+      const preservedHeaders = preserveReplitCustomHeaders(value as Record<string, string>);
+      if (preservedHeaders) next.headers = preservedHeaders;
+      continue;
+    }
+    (next as unknown as Record<string, unknown>)[key] = structuredClone(value);
+  }
+  return next;
+}
+
+function applyPairMutation(
+  persisted: OcxConfig,
+  origin: ValidatedReplitOrigin,
+  gatewayKey: string,
+  input: ReplitProviderPairInput,
+):
+  | ReplitProviderCollision[]
+  | { kind: "namespace_collision"; error: string }
+  | { kind: "destination_rejected"; error: string }
+  | "invalid_provider"
+  | null {
+  const collisions = detectReplitPairCollisions(persisted);
+  if (collisions.length > 0 && input.replace !== true) return collisions;
+
+  const namespaceError = namespaceCollisionError(persisted);
+  if (namespaceError) return { kind: "namespace_collision", error: namespaceError };
+
+  const pair = deriveReplitProviderPair(origin);
+  for (const entry of [pair.openai, pair.anthropic]) {
+    const destinationError = providerDestinationConfigError(entry.name, entry.provider);
+    if (destinationError) return { kind: "destination_rejected", error: destinationError };
+    const providerError = providerManagementConfigError(entry.name, {
+      ...preserveReplitProviderOverlays(persisted.providers[entry.name], {
+        ...entry.provider,
+        apiKey: gatewayKey,
+      }, gatewayKey),
+    });
+    if (providerError) return "invalid_provider";
+  }
+
+  persisted.providers[REPLIT_OPENAI_PROVIDER_ID] = preserveReplitProviderOverlays(
+    persisted.providers[REPLIT_OPENAI_PROVIDER_ID],
+    { ...pair.openai.provider, apiKey: gatewayKey },
+    gatewayKey,
+  );
+  persisted.providers[REPLIT_ANTHROPIC_PROVIDER_ID] = preserveReplitProviderOverlays(
+    persisted.providers[REPLIT_ANTHROPIC_PROVIDER_ID],
+    { ...pair.anthropic.provider, apiKey: gatewayKey },
+    gatewayKey,
+  );
+
+  if (input.setDefault === true) {
+    if (persisted.providers[REPLIT_OPENAI_PROVIDER_ID]?.disabled) {
+      return "invalid_provider";
+    }
+    persisted.defaultProvider = REPLIT_OPENAI_PROVIDER_ID;
+  }
+
+  return null;
+}
+
+function adoptCommittedPair(liveConfig: OcxConfig): boolean {
+  const admitted = readConfigAdmissionSnapshot();
+  if (admitted.kind !== "read" || admitted.diagnostics.error !== null) return false;
+  const persisted = admitted.diagnostics.config;
+  for (const providerId of REPLIT_PROVIDER_PAIR_IDS) {
+    const provider = persisted.providers[providerId];
+    if (!provider) return false;
+    adoptPersistedProviderIntoLiveConfig(liveConfig, providerId, provider, persisted);
+  }
+  if (persisted.defaultProvider) liveConfig.defaultProvider = persisted.defaultProvider;
+  return true;
+}
+
+function mapMutationUnavailable<T>(
+  outcome: Extract<PersistedConfigMutationOutcome<T>, { status: "unavailable" }>,
+): InstallReplitProviderPairResult {
+  if (outcome.reason === "conflict") {
+    return {
+      ok: false,
+      code: "config_busy",
+      error: "Configuration is busy; retry shortly",
+    };
+  }
+  return {
+    ok: false,
+    code: "config_unavailable",
+    error: outcome.reason === "missing"
+      ? "configuration file is unavailable"
+      : "configuration file is invalid",
+  };
+}
+
+export async function installReplitProviderPair(
+  liveConfig: OcxConfig,
+  input: ReplitProviderPairInput,
+  deps: InstallReplitProviderPairDeps = {},
+): Promise<InstallReplitProviderPairResult> {
+  const originResult = validateReplitOrigin(input.origin, {
+    allowCustomDomain: input.allowCustomDomain === true,
+  });
+  if (!originResult.ok) {
+    return { ok: false, code: "invalid_origin", error: originResult.error };
+  }
+
+  const gatewayKeyResult = validateReplitGatewayKey(input.gatewayKey);
+  if (!gatewayKeyResult.ok) {
+    return { ok: false, code: "invalid_gateway_key", error: gatewayKeyResult.error };
+  }
+  const gatewayKey = gatewayKeyResult.key;
+
+  const pair = deriveReplitProviderPair(originResult.origin);
+  for (const entry of [pair.openai, pair.anthropic]) {
+    const destinationError = await providerDestinationResolvedError(entry.name, entry.provider);
+    if (destinationError) {
+      return { ok: false, code: "destination_rejected", error: destinationError };
+    }
+  }
+
+  const probeFn = deps.probe ?? probeReplitGateway;
+  const probe = await probeFn(
+    originResult.origin,
+    gatewayKey,
+    deps.probeFetch ? { fetch: deps.probeFetch } : {},
+  );
+  if (!probe.ok) {
+    return {
+      ok: false,
+      code: "probe_failed",
+      error: probe.error,
+      probe,
+    };
+  }
+
+  const mutateFn = deps.mutatePersistedConfig ?? mutatePersistedConfig;
+  type MutationFailure = Extract<InstallReplitProviderPairResult, { ok: false }>;
+  const mutationState: {
+    failure: Pick<MutationFailure, "code" | "error" | "collisions"> | null;
+  } = { failure: null };
+
+  try {
+    const outcome = mutateFn(persisted => {
+      const failure = applyPairMutation(persisted, originResult.origin, gatewayKey, input);
+      if (Array.isArray(failure)) {
+        mutationState.failure = {
+          code: "provider_collision",
+          error: collisionError(failure),
+          collisions: failure,
+        };
+        return { changed: false, value: null };
+      }
+      if (failure && typeof failure === "object" && failure.kind === "namespace_collision") {
+        mutationState.failure = { code: "namespace_collision", error: failure.error };
+        return { changed: false, value: null };
+      }
+      if (failure && typeof failure === "object" && failure.kind === "destination_rejected") {
+        mutationState.failure = { code: "destination_rejected", error: failure.error };
+        return { changed: false, value: null };
+      }
+      if (failure === "invalid_provider") {
+        mutationState.failure = { code: "persist_failed", error: PERSIST_FAILED_MESSAGE };
+        return { changed: false, value: null };
+      }
+      return { changed: true, value: null };
+    });
+
+    if (mutationState.failure) {
+      const failure = mutationState.failure;
+      return {
+        ok: false,
+        code: failure.code,
+        error: failure.error,
+        ...(failure.collisions ? { collisions: failure.collisions } : {}),
+        probe,
+      };
+    }
+
+    if (outcome.status === "unavailable") {
+      return { ...mapMutationUnavailable(outcome), probe };
+    }
+    if (outcome.status !== "committed") {
+      return { ok: false, code: "persist_failed", error: PERSIST_FAILED_MESSAGE, probe };
+    }
+
+    if (!deps.mutatePersistedConfig) {
+      if (!adoptCommittedPair(liveConfig)) {
+        return { ok: false, code: "persist_failed", error: PERSIST_FAILED_MESSAGE, probe };
+      }
+    }
+
+    return {
+      ok: true,
+      providers: [...REPLIT_PROVIDER_PAIR_IDS],
+      probe,
+    };
+  } catch (error) {
+    if (error instanceof ConfigMutationLockError) {
+      return {
+        ok: false,
+        code: "config_busy",
+        error: "Configuration is busy; retry shortly",
+        probe,
+      };
+    }
+    return {
+      ok: false,
+      code: "persist_failed",
+      error: PERSIST_FAILED_MESSAGE,
+      probe,
+    };
+  }
+}

package/src/providers/request-pacing.ts

@@ -0,0 +1,310 @@
+import type { OcxProviderConfig, RequestPacingRule } from "../types";
+import type { GenerationContext } from "../lib/state-store-sweeper";
+
+export const REQUEST_PACING_MAX_QUEUE_DEPTH = 256;
+export const REQUEST_PACING_MAX_QUEUE_AGE_MS = 60_000;
+
+let maxQueueDepth = REQUEST_PACING_MAX_QUEUE_DEPTH;
+let maxQueueAgeMs = REQUEST_PACING_MAX_QUEUE_AGE_MS;
+
+export type RequestPacingQueueOverloadReason = "queue_full" | "queue_expired";
+
+export class RequestPacingQueueOverloadError extends Error {
+  constructor(
+    public readonly providerName: string,
+    public readonly reason: RequestPacingQueueOverloadReason,
+    public readonly retryAfterSeconds: number,
+  ) {
+    super(reason === "queue_full"
+      ? `request pacing queue for provider '${providerName}' is full`
+      : `request pacing queue for provider '${providerName}' exceeded the maximum queued age`);
+    this.name = "RequestPacingQueueOverloadError";
+  }
+}
+
+export class RequestPacingProviderRemovedError extends Error {
+  constructor(public readonly providerName: string) {
+    super(`request pacing provider '${providerName}' was removed`);
+    this.name = "RequestPacingProviderRemovedError";
+  }
+}
+
+interface Waiter {
+  modelId?: string;
+  providerIntervalMs: number;
+  modelIntervalMs: number;
+  queuedAt: number;
+  signal?: AbortSignal;
+  resolve: () => void;
+  reject: (reason: unknown) => void;
+  abort?: () => void;
+}
+
+interface ProviderPacer {
+  queue: Waiter[];
+  providerNextStartAt: number;
+  modelNextStartAt: Map<string, number>;
+  timer?: unknown;
+  lastStartedAt?: number;
+  lastModelId?: string;
+}
+
+export interface RequestPacingRuntime {
+  now: () => number;
+  setTimer: (callback: () => void, delayMs: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  enqueueMicrotask: (callback: () => void) => void;
+}
+
+export interface ProviderRequestPacingStatus {
+  provider: string;
+  enabled: boolean;
+  queued: number;
+  nextSlotInMs: number;
+  lastStartedAt?: number;
+  lastModelId?: string;
+}
+
+const pacers = new Map<string, ProviderPacer>();
+const defaultRuntime: RequestPacingRuntime = {
+  now: Date.now,
+  setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimer: handle => clearTimeout(handle as ReturnType<typeof setTimeout>),
+  enqueueMicrotask: queueMicrotask,
+};
+let runtime = defaultRuntime;
+let lastReconciledGeneration = 0;
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function normalizedInterval(rule: RequestPacingRule | undefined): number {
+  if (!rule) return 0;
+  const rpmInterval = typeof rule.requestsPerMinute === "number" && rule.requestsPerMinute > 0
+    ? 60_000 / rule.requestsPerMinute
+    : 0;
+  const fixedInterval = typeof rule.minIntervalMs === "number" && rule.minIntervalMs > 0
+    ? rule.minIntervalMs
+    : 0;
+  return Math.max(rpmInterval, fixedInterval);
+}
+
+export function requestPacingIntervalMs(provider: OcxProviderConfig, modelId?: string): number {
+  const policy = provider.requestPacing;
+  if (!policy?.enabled) return 0;
+  const override = modelId ? policy.models?.[modelId] : undefined;
+  return Math.max(normalizedInterval(policy), normalizedInterval(override));
+}
+
+function requestPacingIntervals(provider: OcxProviderConfig, modelId?: string): {
+  providerIntervalMs: number;
+  modelIntervalMs: number;
+} {
+  const policy = provider.requestPacing;
+  if (!policy?.enabled) return { providerIntervalMs: 0, modelIntervalMs: 0 };
+  return {
+    providerIntervalMs: normalizedInterval(policy),
+    modelIntervalMs: modelId ? normalizedInterval(policy.models?.[modelId]) : 0,
+  };
+}
+
+function waiterReadyAt(state: ProviderPacer, modelId: string | undefined): number {
+  return Math.max(
+    state.providerNextStartAt,
+    modelId ? (state.modelNextStartAt.get(modelId) ?? 0) : 0,
+  );
+}
+
+function pacingRetryAfterSeconds(state: ProviderPacer, modelId: string | undefined, now: number): number {
+  return Math.max(1, Math.ceil(Math.max(0, waiterReadyAt(state, modelId) - now) / 1000));
+}
+
+function rejectExpiredWaiters(providerName: string, state: ProviderPacer, now: number): void {
+  for (let index = state.queue.length - 1; index >= 0; index -= 1) {
+    const waiter = state.queue[index]!;
+    if (now - waiter.queuedAt < maxQueueAgeMs) continue;
+    state.queue.splice(index, 1);
+    if (waiter.abort) waiter.signal?.removeEventListener("abort", waiter.abort);
+    waiter.reject(new RequestPacingQueueOverloadError(
+      providerName,
+      "queue_expired",
+      pacingRetryAfterSeconds(state, waiter.modelId, now),
+    ));
+  }
+}
+
+function removeProviderPacer(providerName: string, state: ProviderPacer): void {
+  if (state.timer) runtime.clearTimer(state.timer);
+  state.timer = undefined;
+  pacers.delete(providerName);
+  const waiters = state.queue.splice(0);
+  const error = new RequestPacingProviderRemovedError(providerName);
+  for (const waiter of waiters) {
+    if (waiter.abort) waiter.signal?.removeEventListener("abort", waiter.abort);
+    waiter.reject(error);
+  }
+}
+
+function runQueue(providerName: string, state: ProviderPacer): void {
+  if (state.queue.length === 0) {
+    if (state.timer) runtime.clearTimer(state.timer);
+    state.timer = undefined;
+    return;
+  }
+  if (state.timer) return;
+  const now = runtime.now();
+  for (const [modelId, readyAt] of state.modelNextStartAt) {
+    if (readyAt <= now) state.modelNextStartAt.delete(modelId);
+  }
+  rejectExpiredWaiters(providerName, state, now);
+  if (state.queue.length === 0) return;
+
+  const providerReadyAt = Math.max(now, state.providerNextStartAt);
+  const waiterIndex = state.queue.findIndex(waiter => {
+    const modelReadyAt = waiter.modelId ? (state.modelNextStartAt.get(waiter.modelId) ?? 0) : 0;
+    return Math.max(providerReadyAt, modelReadyAt) <= now;
+  });
+  if (waiterIndex < 0) {
+    let earliestAt = Number.POSITIVE_INFINITY;
+    for (const waiter of state.queue) {
+      const modelReadyAt = waiter.modelId ? (state.modelNextStartAt.get(waiter.modelId) ?? 0) : 0;
+      const readyAt = Math.max(providerReadyAt, modelReadyAt);
+      const expiresAt = waiter.queuedAt + maxQueueAgeMs;
+      earliestAt = Math.min(earliestAt, readyAt, expiresAt);
+    }
+    const delayMs = Math.max(0, earliestAt - now);
+    state.timer = runtime.setTimer(() => {
+      state.timer = undefined;
+      runQueue(providerName, state);
+    }, delayMs);
+    return;
+  }
+  const waiter = state.queue[waiterIndex]!;
+  state.queue.splice(waiterIndex, 1);
+  if (waiter.abort) waiter.signal?.removeEventListener("abort", waiter.abort);
+  const startedAt = runtime.now();
+  state.lastStartedAt = startedAt;
+  state.lastModelId = waiter.modelId;
+  state.providerNextStartAt = startedAt + waiter.providerIntervalMs;
+  if (waiter.modelId && waiter.modelIntervalMs > 0) {
+    state.modelNextStartAt.set(waiter.modelId, startedAt + waiter.modelIntervalMs);
+  }
+  waiter.resolve();
+  runtime.enqueueMicrotask(() => runQueue(providerName, state));
+}
+
+export async function waitForProviderRequestSlot(
+  providerName: string,
+  provider: OcxProviderConfig,
+  modelId?: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const intervals = requestPacingIntervals(provider, modelId);
+  if (Math.max(intervals.providerIntervalMs, intervals.modelIntervalMs) <= 0) return;
+  if (signal?.aborted) throw abortReason(signal);
+
+  const state = pacers.get(providerName) ?? {
+    queue: [], providerNextStartAt: 0, modelNextStartAt: new Map<string, number>(),
+  };
+  pacers.set(providerName, state);
+
+  // Give already-eligible or expired waiters a chance to leave before applying the
+  // admission bound to the newest request. This preserves FIFO-ish fairness while
+  // keeping the retained queue strictly bounded under burst load.
+  if (state.timer) {
+    runtime.clearTimer(state.timer);
+    state.timer = undefined;
+  }
+  runQueue(providerName, state);
+  if (state.queue.length >= maxQueueDepth) {
+    throw new RequestPacingQueueOverloadError(
+      providerName,
+      "queue_full",
+      pacingRetryAfterSeconds(state, modelId, runtime.now()),
+    );
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const waiter: Waiter = { modelId, ...intervals, queuedAt: runtime.now(), signal, resolve, reject };
+    waiter.abort = () => {
+      const index = state.queue.indexOf(waiter);
+      if (index >= 0) state.queue.splice(index, 1);
+      if (state.timer) {
+        runtime.clearTimer(state.timer);
+        state.timer = undefined;
+      }
+      reject(abortReason(signal!));
+      runQueue(providerName, state);
+    };
+    signal?.addEventListener("abort", waiter.abort, { once: true });
+    state.queue.push(waiter);
+    // Abort may race between the eager check above and listener registration.
+    if (signal?.aborted) {
+      waiter.abort();
+      return;
+    }
+    if (state.timer) {
+      runtime.clearTimer(state.timer);
+      state.timer = undefined;
+    }
+    runQueue(providerName, state);
+  });
+}
+
+export function providerRequestPacingStatus(
+  providerName: string,
+  provider: OcxProviderConfig,
+  now = runtime.now(),
+): ProviderRequestPacingStatus {
+  const state = pacers.get(providerName);
+  let nextSlotAt = state?.providerNextStartAt ?? 0;
+  if (state && state.queue.length > 0) {
+    let earliestQueuedSlotAt = Number.POSITIVE_INFINITY;
+    for (const waiter of state.queue) {
+      earliestQueuedSlotAt = Math.min(earliestQueuedSlotAt, waiterReadyAt(state, waiter.modelId));
+    }
+    if (Number.isFinite(earliestQueuedSlotAt)) nextSlotAt = earliestQueuedSlotAt;
+  }
+  return {
+    provider: providerName,
+    enabled: provider.requestPacing?.enabled === true,
+    queued: state?.queue.length ?? 0,
+    nextSlotInMs: Math.max(0, Math.ceil(nextSlotAt - now)),
+    ...(state?.lastStartedAt !== undefined ? { lastStartedAt: state.lastStartedAt } : {}),
+    ...(state?.lastModelId ? { lastModelId: state.lastModelId } : {}),
+  };
+}
+
+export function setProviderRequestPacingLimitsForTest(limits: {
+  maxQueueDepth?: number;
+  maxQueueAgeMs?: number;
+}): void {
+  if (limits.maxQueueDepth !== undefined) maxQueueDepth = limits.maxQueueDepth;
+  if (limits.maxQueueAgeMs !== undefined) maxQueueAgeMs = limits.maxQueueAgeMs;
+}
+
+export function setProviderRequestPacingRuntimeForTest(nextRuntime: RequestPacingRuntime): void {
+  runtime = nextRuntime;
+}
+
+export function reconcileProviderRequestPacing(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  let removed = 0;
+  for (const [providerName, state] of pacers) {
+    if (context.providerNames.has(providerName)) continue;
+    removeProviderPacer(providerName, state);
+    removed += 1;
+  }
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+export function resetProviderRequestPacingForTest(): void {
+  for (const state of pacers.values()) if (state.timer) runtime.clearTimer(state.timer);
+  pacers.clear();
+  maxQueueDepth = REQUEST_PACING_MAX_QUEUE_DEPTH;
+  maxQueueAgeMs = REQUEST_PACING_MAX_QUEUE_AGE_MS;
+  runtime = defaultRuntime;
+  lastReconciledGeneration = 0;
+}