@gotcos/glasses-server 6.79.2 → 6.81.0

package/server/lib/key-relay-errors.ts

@@ -0,0 +1,211 @@
+// Key lanes K1 P2 (plan v4 4.6): how the loopback relay maps upstream and relay events to what the
+// child sees, which failures count toward the breaker, and the breaker itself.
+//
+// Pure functions and one small class. Nothing here reads a file, opens a socket or starts a timer,
+// so importing it changes nothing for a server with key lanes off.
+//
+// The relay never retries itself (no double billing). Children retry 429, 5xx and network errors
+// on their own budget (CLAUDE_CODE_MAX_RETRIES=2, Codex request_max_retries=2). Only a rejected
+// key, an empty credit balance or a model that is gone counts toward the breaker, because those
+// are the failures a retry cannot fix.
+import type {
+  BreakerCountedFailure,
+  BreakerScope,
+  BreakerState,
+  RelayEngine,
+  RelayFailureKind,
+} from './key-relay-contract.js'
+import { BREAKER_LIMITS } from './key-relay-contract.js'
+
+// ── Classification (plan 4.6 table) ──────────────────────────────────────────
+
+const MODEL_GONE_RE = /model[^\n]{0,80}(not found|does not exist|not available|no longer|is not a valid|invalid model)|no endpoints found|unknown model|not a valid model/i
+
+/**
+ * The 4.6 row an upstream status lands in, or null when it is passed through with no special
+ * action (a 2xx, or a 4xx such as 403 moderation that is neither the key nor the model).
+ */
+export function classifyUpstreamStatus(status: number, bodyText = ''): RelayFailureKind | null {
+  if (status >= 200 && status < 300) return null
+  if (status === 401) return 'key_rejected'
+  if (status === 402) return 'out_of_credit'
+  if (status === 404) return 'model_gone'
+  if (status === 400 && MODEL_GONE_RE.test(bodyText)) return 'model_gone'
+  if (status === 429) return 'rate_limited'
+  if (status >= 500) return 'upstream_error'
+  return null
+}
+
+/** Plan 4.6: only 401, 402 and model-gone count. 429, 5xx, network and cap refusals never do. */
+export function countsTowardBreaker(kind: RelayFailureKind | null): kind is BreakerCountedFailure {
+  return kind === 'key_rejected' || kind === 'out_of_credit' || kind === 'model_gone'
+}
+
+/** A rejected key or empty credit opens the KEY breaker; a gone model opens the PROFILE breaker. */
+export function breakerScopeFor(kind: BreakerCountedFailure): BreakerScope {
+  return kind === 'model_gone' ? 'profile' : 'key'
+}
+
+/** The 4.6 rows whose server action is "ends the turn". */
+export function endsTurn(kind: RelayFailureKind): boolean {
+  return kind === 'cap_refused' || kind === 'key_rejected' || kind === 'out_of_credit' || kind === 'model_gone'
+}
+
+// ── Error bodies in the caller's own shape ───────────────────────────────────
+
+/** Relay-made failures (the ones not passed through from upstream). */
+export type RelayLocalError =
+  | 'nonce_invalid'
+  | 'cap_refused'
+  | 'model_not_allowed'
+  | 'network_error'
+  | 'not_found'
+  | 'bad_request'
+  | 'too_large'
+  | 'too_many_in_flight'
+  | 'browser_refused'
+
+interface LocalErrorSpec {
+  status: number
+  anthropicType: string
+  openaiType: string
+  message: string
+}
+
+/** User-facing copy. Plain sentences, no em dashes, no arrows, never a key or a nonce. */
+export const RELAY_ERROR_SPECS: Record<RelayLocalError, LocalErrorSpec> = {
+  nonce_invalid: { status: 401, anthropicType: 'authentication_error', openaiType: 'invalid_api_key', message: 'This relay token is unknown or has expired.' },
+  cap_refused: { status: 402, anthropicType: 'billing_error', openaiType: 'insufficient_quota', message: 'Daily cap reached for this key.' },
+  model_not_allowed: { status: 400, anthropicType: 'invalid_request_error', openaiType: 'invalid_request_error', message: 'Model not allowed on this key profile' },
+  network_error: { status: 502, anthropicType: 'overloaded_error', openaiType: 'server_error', message: 'The provider could not be reached. Try again.' },
+  not_found: { status: 404, anthropicType: 'not_found_error', openaiType: 'invalid_request_error', message: 'Not found.' },
+  bad_request: { status: 400, anthropicType: 'invalid_request_error', openaiType: 'invalid_request_error', message: 'The request body is not valid JSON.' },
+  too_large: { status: 413, anthropicType: 'request_too_large', openaiType: 'invalid_request_error', message: 'The request is too large.' },
+  too_many_in_flight: { status: 429, anthropicType: 'rate_limit_error', openaiType: 'rate_limit_exceeded', message: 'Too many requests at once on this turn.' },
+  browser_refused: { status: 403, anthropicType: 'permission_error', openaiType: 'invalid_request_error', message: 'The relay does not answer browsers.' },
+}
+
+/** The JSON body for a relay-made failure: Anthropic shape for Claude, OpenAI shape for Codex. */
+export function relayErrorBody(engine: RelayEngine | 'unknown', error: RelayLocalError): { status: number; body: string } {
+  const spec = RELAY_ERROR_SPECS[error]
+  const body = engine === 'codex'
+    ? { error: { message: spec.message, type: spec.openaiType, code: error } }
+    : { type: 'error', error: { type: spec.anthropicType, message: spec.message } }
+  return { status: spec.status, body: JSON.stringify(body) }
+}
+
+// ── Redaction ────────────────────────────────────────────────────────────────
+
+export const REDACTED = '[redacted]'
+
+/**
+ * Remove every occurrence of each secret from text bound for a child, a log or a ledger. Upstream
+ * error bodies are passed through, and a provider or proxy that echoes the Authorization header
+ * would otherwise hand the real key to the child.
+ */
+export function redactSecrets(text: string, secrets: ReadonlyArray<string | null | undefined>): string {
+  let out = text
+  for (const s of secrets) {
+    if (!s || s.length < 8) continue
+    // QA N3: the plain form, the JSON-escaped form (a body quoting it), and the URL-encoded form.
+    const forms = new Set([s, JSON.stringify(s).slice(1, -1), encodeURIComponent(s)])
+    for (const f of [...forms].sort((a, b) => b.length - a.length)) out = out.split(f).join(REDACTED)
+  }
+  return out
+}
+
+// ── Retry-After ──────────────────────────────────────────────────────────────
+
+/** Seconds from a Retry-After header (delta seconds or an HTTP date), or null. Passed to the child as is. */
+export function parseRetryAfterSeconds(value: string | null | undefined, now: () => number = Date.now): number | null {
+  if (!value) return null
+  const trimmed = value.trim()
+  if (/^\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed)
+  const at = Date.parse(trimmed)
+  if (!Number.isFinite(at)) return null
+  return Math.max(0, Math.ceil((at - now()) / 1000))
+}
+
+// ── Breaker (plan 4.6) ───────────────────────────────────────────────────────
+
+interface BreakerEntry {
+  failures: number
+  openedAtMs?: number
+}
+
+export type BreakerOpenListener = (scope: BreakerScope, id: string) => void
+
+/**
+ * 3 consecutive counted failures open a breaker for 1 h. A success resets the count. A failure
+ * that does not count (429, 5xx, network, cap) neither counts nor resets. Reset on key change,
+ * successful validation or the Control "Reset" button (the relay calls reset()).
+ */
+export class RelayBreakers {
+  private readonly entries = new Map<string, BreakerEntry>()
+
+  constructor(
+    private readonly now: () => number = Date.now,
+    private readonly onOpen: BreakerOpenListener = () => {},
+  ) {}
+
+  private key(scope: BreakerScope, id: string): string {
+    return `${scope}:${id}`
+  }
+
+  private live(scope: BreakerScope, id: string): BreakerEntry | undefined {
+    const k = this.key(scope, id)
+    const e = this.entries.get(k)
+    if (e?.openedAtMs !== undefined && this.now() - e.openedAtMs >= BREAKER_LIMITS.openMs) {
+      // Closed again after an hour, with a clean count.
+      this.entries.delete(k)
+      return undefined
+    }
+    return e
+  }
+
+  /** Record one upstream outcome. Returns true when this call opened the breaker. */
+  record(scope: BreakerScope, id: string, kind: RelayFailureKind | null, ok: boolean): boolean {
+    const k = this.key(scope, id)
+    if (ok) {
+      const e = this.live(scope, id)
+      if (e && e.openedAtMs === undefined) this.entries.delete(k)
+      return false
+    }
+    if (!countsTowardBreaker(kind)) return false
+    const e = this.live(scope, id) ?? { failures: 0 }
+    if (e.openedAtMs !== undefined) return false
+    e.failures += 1
+    if (e.failures >= BREAKER_LIMITS.failures) {
+      e.openedAtMs = this.now()
+      this.entries.set(k, e)
+      this.onOpen(scope, id)
+      return true
+    }
+    this.entries.set(k, e)
+    return false
+  }
+
+  isOpen(scope: BreakerScope, id: string): boolean {
+    return this.live(scope, id)?.openedAtMs !== undefined
+  }
+
+  state(scope: BreakerScope, id: string): BreakerState {
+    const e = this.live(scope, id)
+    if (!e) return { open: false, failures: 0 }
+    if (e.openedAtMs === undefined) return { open: false, failures: e.failures }
+    return {
+      open: true,
+      failures: e.failures,
+      openedAt: new Date(e.openedAtMs).toISOString(),
+      reopensAt: new Date(e.openedAtMs + BREAKER_LIMITS.openMs).toISOString(),
+    }
+  }
+
+  reset(scope: BreakerScope, id: string): void {
+    this.entries.delete(this.key(scope, id))
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}

package/server/lib/key-relay-meter.ts

@@ -0,0 +1,303 @@
+// Key lanes K1 P2 (plan v4 4.5): the per-key spend counter and its reservations.
+//
+// ONE counter per key ref, shared by every profile on that key, every parallel turn, hooks, the
+// in-process direct lane (P5) and K3. reserve() is synchronous, so two parallel requests can never
+// both pass a check that only one of them fits under: JavaScript runs one reserve at a time.
+//
+//   spent today = max(local settled, OpenRouter usage_daily) + open reservations
+//   reserve     = body bytes / 4 at the input price + min(max_tokens, 4096) at the output price
+//   refuse      when spent today + reserve > cap
+//   settle      replaces the reservation with the measured cost (stream usage times price, or the
+//               provider's own `usage.cost` when it sends one)
+//
+// The day is the UTC day, matching OpenRouter usage_daily. Overshoot is bounded by responses
+// already streaming when the cap is reached; the OpenRouter key's own credit limit is the hard
+// backstop. Nothing here starts a timer or opens a socket, and nothing is written until the first
+// reservation.
+import { randomBytes } from 'node:crypto'
+import { getPublicKey } from './key-store.js'
+import type { KeyLane, KeyMeter, KeyRef } from './key-relay-contract.js'
+import { appendKeyLedgerRow, ledgerSpentUsd, utcDay } from './key-ledger.js'
+import { KEY_CATALOG_CURATED } from './key-catalog.js'
+
+export interface ModelPrice {
+  inUsdPerM: number
+  outUsdPerM: number
+}
+
+/**
+ * A model COS has no price for is metered as if it were the most expensive Claude tier, so an
+ * unknown price can only make the cap stricter, never looser.
+ */
+export const FALLBACK_PRICE: ModelPrice = { inUsdPerM: 15, outUsdPerM: 75 }
+export const RESERVE_MAX_OUTPUT_TOKENS = 4096
+export const BYTES_PER_TOKEN_ESTIMATE = 4
+/** Turns whose settled spend the meter remembers (oldest dropped first). */
+export const TURN_SPEND_MAX = 512
+
+/** Curated prices (plan D10), then the fallback. P5's live catalog can be passed in instead. */
+export function defaultPriceFor(model: string): ModelPrice {
+  const curated = KEY_CATALOG_CURATED.find(m => m.id === model)
+  return curated ? { inUsdPerM: curated.inUsdPerM, outUsdPerM: curated.outUsdPerM } : FALLBACK_PRICE
+}
+
+export function tokensToUsd(tokens: { input: number; output: number }, price: ModelPrice): number {
+  return (Math.max(0, tokens.input) * price.inUsdPerM + Math.max(0, tokens.output) * price.outUsdPerM) / 1e6
+}
+
+/** Plan 4.5 reserve: input estimate plus min(max_tokens, 4096) output. A missing max_tokens reserves 4096. */
+export function estimateReserveUsd(input: { bodyBytes: number; maxTokens?: number | null; price: ModelPrice }): number {
+  const inTokens = Math.ceil(Math.max(0, input.bodyBytes) / BYTES_PER_TOKEN_ESTIMATE)
+  const mt = typeof input.maxTokens === 'number' && Number.isFinite(input.maxTokens) && input.maxTokens > 0 ? input.maxTokens : RESERVE_MAX_OUTPUT_TOKENS
+  const outTokens = Math.min(mt, RESERVE_MAX_OUTPUT_TOKENS)
+  return tokensToUsd({ input: inTokens, output: outTokens }, input.price)
+}
+
+/** QA W2: the smallest reply worth starting; less headroom than this refuses the request. */
+export const MIN_RESERVE_OUTPUT_TOKENS = 256
+
+/**
+ * QA W2: reserve the request's own max_tokens (no 4096 clamp), but never more than the key has
+ * left today. Null when even the input plus a short reply does not fit: refuse before sending.
+ * A reply longer than what was reserved is cut by the relay when the spend reaches the cap.
+ */
+export function reserveWithinHeadroomUsd(input: { bodyBytes: number; maxTokens?: number | null; price: ModelPrice; headroomUsd: number }): number | null {
+  const inTokens = Math.ceil(Math.max(0, input.bodyBytes) / BYTES_PER_TOKEN_ESTIMATE)
+  const mt = typeof input.maxTokens === 'number' && Number.isFinite(input.maxTokens) && input.maxTokens > 0 ? input.maxTokens : RESERVE_MAX_OUTPUT_TOKENS
+  const inputUsd = tokensToUsd({ input: inTokens, output: 0 }, input.price)
+  const fullUsd = inputUsd + tokensToUsd({ input: 0, output: mt }, input.price)
+  const floorUsd = inputUsd + tokensToUsd({ input: 0, output: Math.min(mt, MIN_RESERVE_OUTPUT_TOKENS) }, input.price)
+  const headroom = Number.isFinite(input.headroomUsd) ? input.headroomUsd : 0
+  if (headroom < floorUsd) return null
+  return Math.min(fullUsd, headroom)
+}
+
+interface Reservation {
+  keyRef: KeyRef
+  turnId: string
+  profile: string
+  lane: KeyLane
+  usd: number
+}
+
+interface DaySpend {
+  day: string
+  settledUsd: number
+  usageDailyUsd?: number
+}
+
+export interface ReserveInput {
+  keyRef: KeyRef
+  turnId: string
+  estimateUsd: number
+  /** Ledger detail; the contract's KeyMeter.reserve leaves them out. */
+  profile?: string
+  lane?: KeyLane
+  tokens?: { input: number; output: number }
+}
+
+export type ReserveResult = { ok: true; reservationId: string } | { ok: false; spentTodayUsd: number; capUsd: number }
+
+export interface KeyRelayMeterOptions {
+  now?: () => number
+  /** The key's daily cap, or null when the key is gone (refuse). Default: the key store. */
+  capUsd?: (keyRef: KeyRef) => number | null
+  /** Ledger writer. Default: data/key-ledger.jsonl. */
+  appendRow?: typeof appendKeyLedgerRow
+  /** Settled spend already on disk for a key and UTC day. Default: the ledger file. */
+  loadSettled?: (keyRef: KeyRef, day: string) => number
+  log?: (line: string) => void
+}
+
+export class KeyRelayMeter implements KeyMeter {
+  private readonly now: () => number
+  private readonly capOf: (keyRef: KeyRef) => number | null
+  private readonly append: typeof appendKeyLedgerRow
+  private readonly loadSettled: (keyRef: KeyRef, day: string) => number
+  private readonly log: (line: string) => void
+  private readonly days = new Map<KeyRef, DaySpend>()
+  private readonly reservations = new Map<string, Reservation>()
+  /** P11: settled spend per turn id (newest TURN_SPEND_MAX), so a keyed answer can carry its cost. */
+  private readonly turnSpend = new Map<string, number>()
+  /** P11 (plan 4.5 "Cap value"): the cap Control last saved per key, this boot. */
+  private readonly savedCaps = new Map<KeyRef, number>()
+  private readonly capMismatchLogged = new Set<KeyRef>()
+
+  constructor(options: KeyRelayMeterOptions = {}) {
+    this.now = options.now ?? Date.now
+    this.capOf = options.capUsd ?? (ref => getPublicKey(ref)?.capUsd ?? null)
+    this.append = options.appendRow ?? appendKeyLedgerRow
+    this.loadSettled = options.loadSettled ?? ((ref, day) => ledgerSpentUsd(ref, day))
+    this.log = options.log ?? (line => console.warn(line))
+  }
+
+  private today(keyRef: KeyRef): DaySpend {
+    const day = utcDay(this.now())
+    let d = this.days.get(keyRef)
+    if (!d || d.day !== day) {
+      let settledUsd = 0
+      try { settledUsd = this.loadSettled(keyRef, day) } catch { settledUsd = 0 }
+      d = { day, settledUsd }
+      this.days.set(keyRef, d)
+    }
+    return d
+  }
+
+  private write(row: Parameters<typeof appendKeyLedgerRow>[0]): void {
+    try { this.append(row) } catch (err) {
+      // The in-memory counter still holds the spend; only the audit row is lost.
+      this.log(`[key-relay] ledger write skipped: ${(err as Error)?.name ?? 'error'}`)
+    }
+  }
+
+  capUsd(keyRef: KeyRef): number | null {
+    const raw = this.capOf(keyRef)
+    const cap = typeof raw === 'number' && Number.isFinite(raw) ? raw : null
+    // A key that is gone always refuses, whatever was saved before.
+    if (cap === null) return null
+    // Plan 4.5: the server keeps Control's last saved value. A cap that changed in the file by any
+    // other path (a Lane A turn editing provider-keys.json) is ignored and logged once. The first
+    // value seen this boot is the baseline until Control saves one.
+    const saved = this.savedCaps.get(keyRef)
+    if (saved === undefined) {
+      this.savedCaps.set(keyRef, cap)
+      return cap
+    }
+    if (saved !== cap && !this.capMismatchLogged.has(keyRef)) {
+      this.capMismatchLogged.add(keyRef)
+      this.log(`[key-relay] cap for ${keyRef} changed outside COS Control; keeping the saved cap`)
+    }
+    return saved
+  }
+
+  /** P11: the key-lanes routes call this when COS Control saves a key or changes its cap. */
+  noteSavedCap(keyRef: KeyRef, capUsd: number): void {
+    if (typeof capUsd !== 'number' || !Number.isFinite(capUsd) || capUsd <= 0) return
+    this.savedCaps.set(keyRef, capUsd)
+    this.capMismatchLogged.delete(keyRef)
+  }
+
+  /** P11: what this turn has settled so far on any key (0 when nothing settled). */
+  turnSettledUsd(turnId: string): number {
+    return this.turnSpend.get(turnId) ?? 0
+  }
+
+  private addTurnSpend(turnId: string, usd: number): void {
+    if (!turnId) return
+    const prior = this.turnSpend.get(turnId) ?? 0
+    this.turnSpend.delete(turnId)
+    this.turnSpend.set(turnId, prior + usd)
+    while (this.turnSpend.size > TURN_SPEND_MAX) {
+      const oldest = this.turnSpend.keys().next().value
+      if (oldest === undefined) break
+      this.turnSpend.delete(oldest)
+    }
+  }
+
+  openReservationsUsd(keyRef: KeyRef): number {
+    let sum = 0
+    for (const r of this.reservations.values()) if (r.keyRef === keyRef) sum += r.usd
+    return sum
+  }
+
+  /** Plan 4.5: max(local ledger, usage_daily) plus open reservations. */
+  spentTodayUsd(keyRef: KeyRef): number {
+    const d = this.today(keyRef)
+    return Math.max(d.settledUsd, d.usageDailyUsd ?? 0) + this.openReservationsUsd(keyRef)
+  }
+
+  /** OpenRouter's usage_daily for this key (read at turn start and while a turn runs). */
+  observeUsageDaily(keyRef: KeyRef, usd: number): void {
+    if (typeof usd !== 'number' || !Number.isFinite(usd) || usd < 0) return
+    const d = this.today(keyRef)
+    d.usageDailyUsd = Math.max(d.usageDailyUsd ?? 0, usd)
+  }
+
+  /** QA W2: what the key may still spend today (cap minus spent, open reservations included). */
+  headroomUsd(keyRef: KeyRef): number {
+    const cap = this.capUsd(keyRef)
+    return cap === null ? 0 : cap - this.spentTodayUsd(keyRef)
+  }
+
+  /** True when the key has nothing left under its cap today (refuse a turn before spawn). */
+  atCap(keyRef: KeyRef): boolean {
+    const cap = this.capUsd(keyRef)
+    return cap === null || this.spentTodayUsd(keyRef) >= cap
+  }
+
+  reserve(input: ReserveInput): ReserveResult {
+    const cap = this.capUsd(input.keyRef)
+    const spent = this.spentTodayUsd(input.keyRef)
+    const estimate = Number.isFinite(input.estimateUsd) && input.estimateUsd > 0 ? input.estimateUsd : 0
+    if (cap === null || spent + estimate > cap) {
+      return { ok: false, spentTodayUsd: spent, capUsd: cap ?? 0 }
+    }
+    const reservationId = `res_${randomBytes(9).toString('base64url')}`
+    const r: Reservation = { keyRef: input.keyRef, turnId: input.turnId, profile: input.profile ?? '', lane: input.lane ?? 'key', usd: estimate }
+    this.reservations.set(reservationId, r)
+    this.write({
+      ts: new Date(this.now()).toISOString(), keyRef: r.keyRef, profile: r.profile, lane: r.lane, turnId: r.turnId,
+      tokens: input.tokens ?? { input: 0, output: 0 }, usd: estimate, kind: 'reserve',
+    })
+    return { ok: true, reservationId }
+  }
+
+  settle(input: { reservationId: string; usd: number; tokens: { input: number; output: number }; generationId?: string }): void {
+    const r = this.reservations.get(input.reservationId)
+    if (!r) return
+    this.reservations.delete(input.reservationId)
+    const usd = Number.isFinite(input.usd) && input.usd > 0 ? input.usd : 0
+    this.today(r.keyRef).settledUsd += usd
+    this.addTurnSpend(r.turnId, usd)
+    this.write({
+      ts: new Date(this.now()).toISOString(), keyRef: r.keyRef, profile: r.profile, lane: r.lane, turnId: r.turnId,
+      ...(input.generationId ? { generationId: input.generationId } : {}),
+      tokens: input.tokens, usd, kind: 'settle',
+    })
+  }
+
+  /** Settle at the full reserved amount (no usage arrived). */
+  settleReserved(reservationId: string, tokens: { input: number; output: number } = { input: 0, output: 0 }, generationId?: string): void {
+    const r = this.reservations.get(reservationId)
+    if (!r) return
+    this.settle({ reservationId, usd: r.usd, tokens, ...(generationId ? { generationId } : {}) })
+  }
+
+  /** The reserved amount of an open reservation, or null. */
+  reservedUsd(reservationId: string): number | null {
+    return this.reservations.get(reservationId)?.usd ?? null
+  }
+
+  /** Later correction from the provider's own generation cost (plan 4.5 reconcile). */
+  reconcile(input: { keyRef: KeyRef; turnId: string; profile: string; lane: KeyLane; generationId: string; deltaUsd: number; tokens: { input: number; output: number } }): void {
+    if (!Number.isFinite(input.deltaUsd) || input.deltaUsd === 0) return
+    const d = this.today(input.keyRef)
+    d.settledUsd = Math.max(0, d.settledUsd + input.deltaUsd)
+    this.write({
+      ts: new Date(this.now()).toISOString(), keyRef: input.keyRef, profile: input.profile, lane: input.lane, turnId: input.turnId,
+      generationId: input.generationId, tokens: input.tokens, usd: input.deltaUsd, kind: 'reconcile',
+    })
+  }
+
+  /** Drop every in-memory number (Remove all keys). The ledger file is the route's to delete. */
+  clear(): void {
+    this.days.clear()
+    this.reservations.clear()
+    this.turnSpend.clear()
+    this.savedCaps.clear()
+    this.capMismatchLogged.clear()
+  }
+}
+
+let shared: KeyRelayMeter | null = null
+
+/** The one meter the relay, the direct lane (P5) and K3 share. Created on first use. */
+export function getSharedKeyMeter(): KeyRelayMeter {
+  if (!shared) shared = new KeyRelayMeter()
+  return shared
+}
+
+/** Tests only. */
+export function __resetSharedKeyMeterForTests(): void {
+  shared = null
+}