@gotcos/glasses-server 6.79.2 → 6.81.0

package/server/lib/key-profile-routing.ts

@@ -0,0 +1,173 @@
+// Key lanes K1, package P6 (plan v4 sections 5.2 and 9.4): how a model preference that names a
+// key profile is routed, refused or ignored. One module so every Accept site resolves a profile
+// the same way and every refusal reads the same on the lens.
+//
+//   resolveKeyProfileTurn   `profile:<id>` to a runnable turn, or a lens line saying why not.
+//                           Never a silent subscription turn: an unknown, disabled or keyless
+//                           profile, or key lanes switched off, is a refusal.
+//   registerKeyProfileEngine The seam P3 (claude), P4 (codex) and P5 (direct) register their
+//                           keyed runner into. With no runner for an engine, the turn is refused.
+//   profileSteerProvider    What a profile-bound job looks like to the steer gate (claude-steer
+//                           returns `profile_session`; this decides which engine that means).
+//   v1KeyProfileFor         `/v1` `cos-key-<id>` to a profile offered there, or a refusal.
+//
+// HARD RULE: nothing here runs for a preference that is not a well formed `profile:<id>` or
+// `cos-key-<id>`. Every caller checks that syntax first (a pure string test, no file read), so a
+// server with no profile takes exactly the 6.79.0 path. Importing this module reads no file,
+// opens no socket and starts no timer. It imports only types from conversation.ts, so a test that
+// loads it does not load the session store.
+import type { CallOptions, StreamCallbacks } from './claude-bridge.js'
+import type { ModelImageInput } from './model-image-input.js'
+import type { KeyKind, KeyProfile, KeyProfileEngine } from './key-relay-contract.js'
+import type { QueryProvider } from './claude-steer.js'
+import { keyLanesActive } from './key-lanes.js'
+import { KEY_LANE_REFUSAL_COPY } from './key-notices.js'
+import { getProfile, listProfiles } from './key-profiles.js'
+import { getPublicKey } from './key-store.js'
+import type { KeyProfileBinding, PromptReference } from './conversation.js'
+import { normalizeModelPreference } from '../../shared/model-preference.js'
+import { isProfilePreference, profilePreference } from '../../shared/key-preference.js'
+
+/** A profile that may run now: lanes active, the profile enabled, its key saved. */
+export interface KeyProfileTurn {
+  binding: KeyProfileBinding
+  profile: KeyProfile
+  keyKind: KeyKind
+}
+
+export type KeyProfileRefusalCode = 'key_profile_off' | 'key_profile_unavailable'
+
+export type KeyProfileResolution =
+  | { ok: true; turn: KeyProfileTurn }
+  | { ok: false; code: KeyProfileRefusalCode; message: string }
+
+// ── Lens copy (plan 11.3 "Profile off", 5.2 rejects). No em dashes, no arrows, one line each. ──
+
+/** Plan 5.2 and 11.3: the one refusal for a profile that cannot run (missing, disabled, no key, lanes off). */
+export function keyProfileOffLine(label: string): string {
+  return KEY_LANE_REFUSAL_COPY.profileOff(label)
+}
+/** No runner is registered for the profile's engine on this build. */
+export function keyProfileUnavailableLine(label: string): string {
+  return KEY_LANE_REFUSAL_COPY.profileUnavailable(label)
+}
+/** Plan 9.4: a `cos-key-<id>` that is not an active profile with "Offer on /v1" on. */
+export const KEY_PROFILE_V1_NOT_OFFERED = KEY_LANE_REFUSAL_COPY.v1NotOffered
+
+function labelFor(id: string, profile: KeyProfile | undefined): string {
+  return profile?.label?.trim() || id
+}
+
+/**
+ * Resolve `profile:<id>`. Lanes off, an unknown id, a disabled profile or a profile whose key
+ * was removed all refuse with the same line (the user's fix is the same: pick a model).
+ */
+export function resolveKeyProfileTurn(id: string): KeyProfileResolution {
+  // Read only for its label when lanes are off: a stale binding still names the profile.
+  const profile = getProfile(id)
+  const off = (): KeyProfileResolution => ({ ok: false, code: 'key_profile_off', message: keyProfileOffLine(labelFor(id, profile)) })
+  if (!keyLanesActive()) return off()
+  if (!profile || !profile.enabled) return off()
+  const key = getPublicKey(profile.keyRef)
+  if (!key) return off()
+  return { ok: true, turn: { binding: profilePreference(profile.id) as KeyProfileBinding, profile, keyKind: key.kind } }
+}
+
+// ── Engine seam (P3, P4, P5 register) ────────────────────────────────────────
+
+/**
+ * A keyed runner. Same arguments as the subscription bridges, plus the resolved turn. Contract:
+ *   - call exactly one of callbacks.onDone / callbacks.onError (model-router's session run lock
+ *     releases on that terminal callback);
+ *   - stamp conversation exchanges with `turn.binding` (conversation accepts it by syntax);
+ *   - the `model` it passes to onStart / onDone is ignored for linkage and display: callers read
+ *     the binding from the `onKeyProfileTurn` callback below instead;
+ *   - honor `options.steer` when present (only a `claude` engine profile is ever offered one).
+ */
+export type KeyProfileEngineRunner = (
+  query: string,
+  sessionId: string,
+  callbacks: StreamCallbacks,
+  turn: KeyProfileTurn,
+  images?: ModelImageInput[],
+  reference?: PromptReference,
+  globalMsgNum?: number,
+  options?: CallOptions,
+) => Promise<string>
+
+const engines = new Map<KeyProfileEngine, KeyProfileEngineRunner>()
+
+/** Named by engine, so a re-registration replaces rather than stacks. */
+export function registerKeyProfileEngine(engine: KeyProfileEngine, runner: KeyProfileEngineRunner): void {
+  engines.set(engine, runner)
+}
+
+export function keyProfileEngineRunner(engine: KeyProfileEngine): KeyProfileEngineRunner | undefined {
+  return engines.get(engine)
+}
+
+/** Tests only. */
+export function __resetKeyProfileEnginesForTests(): void {
+  engines.clear()
+}
+
+/**
+ * Optional callback a caller of callModelStreaming may add. model-router calls it once, before
+ * the keyed runner starts, and never for a subscription turn. The durable runtime and the SSE
+ * route use it to report the binding (not the runner's tier) as the turn's model.
+ */
+export interface KeyProfileTurnCallbacks {
+  onKeyProfileTurn?: (turn: KeyProfileTurn) => void
+}
+
+// ── Linkage and steer ────────────────────────────────────────────────────────
+
+export type KeyProfileLinkageProvider = 'claude' | 'codex' | undefined
+
+/** The job linkage provider for an engine. Direct (Lane C) has no CLI session; it is omitted. */
+export function linkageProviderForEngine(engine: KeyProfileEngine): KeyProfileLinkageProvider {
+  if (engine === 'claude') return 'claude'
+  if (engine === 'codex') return 'codex'
+  return undefined
+}
+
+/**
+ * claude-steer's guard returned `profile_session`. Steerable (`claude`) only for an active,
+ * enabled Lane B Claude profile; anything else answers with a provider the coordinator never
+ * steers, so a Codex or direct profile, or a profile that would be refused, is `unsupported`.
+ */
+export function profileSteerProvider(id: string): QueryProvider {
+  const resolved = resolveKeyProfileTurn(id)
+  return resolved.ok && resolved.turn.profile.engine === 'claude' ? 'claude' : 'codex'
+}
+
+// ── /v1 (plan 9.4) ───────────────────────────────────────────────────────────
+
+/** Profiles `/v1` offers: lanes active, enabled, "Offer on /v1" on, key saved. Empty when inactive. */
+export function v1OfferedProfiles(): KeyProfile[] {
+  if (!keyLanesActive()) return []
+  return listProfiles().filter(p => p.enabled && p.offerOnV1 && getPublicKey(p.keyRef) !== undefined)
+}
+
+/** The offered profile for a `cos-key-<id>` id, or undefined (the route refuses it). */
+export function v1OfferedProfile(id: string): KeyProfile | undefined {
+  return v1OfferedProfiles().find(p => p.id === id)
+}
+
+// ── COS_G2_DEFAULT_MODEL (plan 5.2: closed) ──────────────────────────────────
+
+let envProfileWarned = false
+
+/** A profile id in COS_G2_DEFAULT_MODEL is ignored, with ONE warning per boot. Returns the closed default. */
+export function closedEnvDefaultModel(raw: string | undefined = process.env.COS_G2_DEFAULT_MODEL) {
+  if (!envProfileWarned && isProfilePreference(raw?.trim())) {
+    envProfileWarned = true
+    console.warn('[key-lanes] COS_G2_DEFAULT_MODEL names a key profile; ignored. Pick a profile from the picker instead.')
+  }
+  return normalizeModelPreference(raw)
+}
+
+/** Tests only. */
+export function __resetEnvProfileWarningForTests(): void {
+  envProfileWarned = false
+}

package/server/lib/key-profiles.ts

@@ -0,0 +1,182 @@
+// Key lanes (K1, plan v4 sections 3.1, 4.4, 5, 12): saved key profiles, `data/provider-profiles.json`.
+//
+// A profile binds one saved key to one engine and one model. No secret lives here, only the key's
+// ref. `keyLanesActive()` is true only while this file parses with at least one enabled profile.
+// Reading never creates: a missing or corrupt file is "no profiles" and is left untouched.
+import { existsSync, statSync, unlinkSync } from 'node:fs'
+import { isKeyProfileId } from '../../shared/key-preference.js'
+import { dataPath } from './data-dir.js'
+import type { KeyKind, KeyProfile, KeyProfileEngine, KeyProfileTimeoutTier } from './key-relay-contract.js'
+import { KEY_REF_RE } from './key-relay-contract.js'
+import { readPrivateJsonFile, writePrivateJsonFile } from './key-store.js'
+
+export const KEY_PROFILES_FILE = 'provider-profiles.json'
+export const KEY_PROFILE_ENGINES: readonly KeyProfileEngine[] = ['claude', 'codex', 'direct']
+export const KEY_PROFILE_TIMEOUT_TIERS: readonly KeyProfileTimeoutTier[] = ['opus', 'fable', 'sonnet', 'haiku']
+export const MAX_KEY_PROFILES = 20
+const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/
+const LABEL_MAX = 40
+
+interface ProfilesFile {
+  v: 1
+  profiles: KeyProfile[]
+}
+
+export function keyProfilesPath(): string {
+  return dataPath(KEY_PROFILES_FILE)
+}
+
+function isProfile(v: unknown): v is KeyProfile {
+  if (!v || typeof v !== 'object') return false
+  const p = v as Partial<KeyProfile>
+  return isKeyProfileId(p.id)
+    && typeof p.label === 'string'
+    && typeof p.keyRef === 'string' && KEY_REF_RE.test(p.keyRef)
+    && typeof p.engine === 'string' && (KEY_PROFILE_ENGINES as readonly string[]).includes(p.engine)
+    && typeof p.model === 'string' && MODEL_ID_RE.test(p.model)
+    && typeof p.enabled === 'boolean'
+    && typeof p.timeoutTier === 'string' && (KEY_PROFILE_TIMEOUT_TIERS as readonly string[]).includes(p.timeoutTier)
+}
+
+let cache: { stamp: string; profiles: KeyProfile[] } | null = null
+
+export function listProfiles(): KeyProfile[] {
+  const file = keyProfilesPath()
+  let stamp: string
+  try {
+    const st = statSync(file)
+    stamp = `${st.ino}:${st.size}:${st.mtimeMs}`
+  } catch {
+    cache = null
+    return []
+  }
+  if (cache?.stamp === stamp) return cache.profiles
+  const parsed = readPrivateJsonFile(file) as Partial<ProfilesFile> | undefined
+  const profiles = parsed && Array.isArray(parsed.profiles)
+    ? parsed.profiles.filter(isProfile).map(p => ({ ...p, offerOnV1: p.offerOnV1 === true, directTools: p.directTools === true }))
+    : []
+  cache = { stamp, profiles }
+  return profiles
+}
+
+export function enabledProfileCount(): number {
+  return listProfiles().filter(p => p.enabled).length
+}
+
+export function getProfile(id: string): KeyProfile | undefined {
+  return listProfiles().find(p => p.id === id)
+}
+
+function writeProfiles(profiles: KeyProfile[]): void {
+  const body: ProfilesFile = { v: 1, profiles }
+  writePrivateJsonFile(keyProfilesPath(), body)
+  cache = null
+}
+
+export interface ProfileInput {
+  id?: unknown
+  label?: unknown
+  keyRef?: unknown
+  engine?: unknown
+  model?: unknown
+  enabled?: unknown
+  timeoutTier?: unknown
+  offerOnV1?: unknown
+  directTools?: unknown
+}
+
+/**
+ * Plan 4.4 model policy at save time: Lane B Claude takes OpenRouter `anthropic/*` slugs or an
+ * Anthropic key's own `claude-*` ids; Lane B Codex takes `openai/*` slugs or an OpenAI key's ids;
+ * anything else is Lane C (direct) only, which cannot run on an Anthropic key.
+ */
+export function engineModelProblem(engine: KeyProfileEngine, model: string, keyKind: KeyKind): string | null {
+  if (engine === 'claude') {
+    if (keyKind === 'openrouter' && model.startsWith('anthropic/')) return null
+    if (keyKind === 'anthropic' && model.startsWith('claude-')) return null
+    return 'Claude profiles take an anthropic/ model on OpenRouter or a claude- model on an Anthropic key.'
+  }
+  if (engine === 'codex') {
+    if (keyKind === 'openrouter' && model.startsWith('openai/')) return null
+    if (keyKind === 'openai' && !model.includes('/')) return null
+    return 'Codex profiles take an openai/ model on OpenRouter or a model on an OpenAI key.'
+  }
+  if (keyKind === 'anthropic') return 'Direct profiles need an OpenRouter, OpenAI or custom key.'
+  return null
+}
+
+export type ProfileValidation = { ok: true; profile: KeyProfile } | { ok: false; error: string; message: string }
+
+/** Validate an upsert against the saved keys. `keyKindOf` returns undefined for an unknown ref. */
+export function validateProfileInput(
+  input: ProfileInput,
+  keyKindOf: (ref: string) => KeyKind | undefined,
+  now: () => Date = () => new Date(),
+): ProfileValidation {
+  const bad = (message: string): ProfileValidation => ({ ok: false, error: 'invalid_profile', message })
+  if (!isKeyProfileId(input.id)) return bad('Profile id is 1 to 32 lowercase letters, digits or dashes.')
+  if (typeof input.label !== 'string' || !input.label.trim() || input.label.trim().length > LABEL_MAX || /[\u0000-\u001f\u007f]/.test(input.label)) {
+    return bad(`Give the profile a name of up to ${LABEL_MAX} characters.`)
+  }
+  if (typeof input.keyRef !== 'string' || !KEY_REF_RE.test(input.keyRef)) return bad('Pick a saved key.')
+  const keyKind = keyKindOf(input.keyRef)
+  if (!keyKind) return { ok: false, error: 'unknown_key', message: 'That key is not saved on this Mac.' }
+  if (typeof input.engine !== 'string' || !(KEY_PROFILE_ENGINES as readonly string[]).includes(input.engine)) return bad('Pick Claude, Codex or Direct.')
+  if (typeof input.model !== 'string' || !MODEL_ID_RE.test(input.model)) return bad('Pick a model.')
+  const engine = input.engine as KeyProfileEngine
+  const modelProblem = engineModelProblem(engine, input.model, keyKind)
+  if (modelProblem) return { ok: false, error: 'model_not_allowed', message: modelProblem }
+  const tier = input.timeoutTier === undefined ? 'sonnet' : input.timeoutTier
+  if (typeof tier !== 'string' || !(KEY_PROFILE_TIMEOUT_TIERS as readonly string[]).includes(tier)) return bad('Unknown timeout tier.')
+  for (const [name, v] of [['enabled', input.enabled], ['offerOnV1', input.offerOnV1], ['directTools', input.directTools]] as const) {
+    if (v !== undefined && typeof v !== 'boolean') return bad(`${name} is true or false.`)
+  }
+  const at = now().toISOString()
+  const prior = getProfile(input.id)
+  return {
+    ok: true,
+    profile: {
+      id: input.id,
+      label: input.label.trim(),
+      keyRef: input.keyRef,
+      engine,
+      model: input.model,
+      enabled: input.enabled === undefined ? true : input.enabled === true,
+      timeoutTier: tier as KeyProfileTimeoutTier,
+      offerOnV1: input.offerOnV1 === true,
+      // D7: tools stay off unless the caller turns them on for this profile.
+      directTools: input.directTools === true,
+      createdAt: prior?.createdAt ?? at,
+      updatedAt: at,
+    },
+  }
+}
+
+/** Insert or replace by id. Refuses past MAX_KEY_PROFILES. */
+export function upsertProfile(profile: KeyProfile): { ok: true } | { ok: false; error: 'too_many_profiles' } {
+  const profiles = [...listProfiles()]
+  const i = profiles.findIndex(p => p.id === profile.id)
+  if (i < 0 && profiles.length >= MAX_KEY_PROFILES) return { ok: false, error: 'too_many_profiles' }
+  if (i >= 0) profiles[i] = profile
+  else profiles.push(profile)
+  writeProfiles(profiles)
+  return { ok: true }
+}
+
+/** True when a profile was removed. */
+export function deleteProfile(id: string): boolean {
+  const profiles = listProfiles()
+  const next = profiles.filter(p => p.id !== id)
+  if (next.length === profiles.length) return false
+  writeProfiles(next)
+  return true
+}
+
+/** Remove all keys (plan 12). True when a file was deleted. */
+export function deleteProfilesFile(): boolean {
+  cache = null
+  const file = keyProfilesPath()
+  if (!existsSync(file)) return false
+  unlinkSync(file)
+  return true
+}

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

@@ -0,0 +1,262 @@
+// Key lanes (K1, plan v4 sections 4, 8, 12): the FROZEN contract between P1 (foundation), P2 (the
+// loopback metering relay), P3 (Lane B Claude), P4 (Lane B Codex), P5 (Lane C direct) and P11.
+//
+// Types and inert constants only. Nothing here reads a file, opens a socket, starts a timer or
+// touches process.env, so importing it changes nothing for a server with key lanes off.
+// Changing a name or a shape here after P1 lands needs every consumer package to agree.
+
+// ── Credentials ──────────────────────────────────────────────────────────────
+
+/** What a saved key is (plan D2). `openai-compatible` is a custom URL, Mac only. */
+export type KeyKind = 'openrouter' | 'anthropic' | 'openai' | 'openai-compatible'
+export const KEY_KINDS: readonly KeyKind[] = ['openrouter', 'anthropic', 'openai', 'openai-compatible']
+
+/** A key's stable handle: `key_` plus 12 lowercase hex. Never derived from the secret. */
+export type KeyRef = string
+export const KEY_REF_RE = /^key_[0-9a-f]{12}$/
+
+/**
+ * What any route, log, health field, diagnostic or ledger may say about a key. The secret never
+ * leaves `key-store.ts` except through `readKeySecretForRelay`, which only P2 and P5 call.
+ */
+export interface PublicKeyRecord {
+  ref: KeyRef
+  kind: KeyKind
+  /** Last four characters of the secret, for "the key ending 1a2b". */
+  last4: string
+  /** Daily cap in USD for this key (plan 4.5, D11 default 1.00). */
+  capUsd: number
+  savedAt: string
+  validatedAt?: string
+  /** `openai-compatible` only: the base URL the key was saved for. */
+  baseUrl?: string
+}
+
+// ── Lanes and answers ────────────────────────────────────────────────────────
+
+/** Lane A is the user's subscription CLI; B runs the CLI harness on a key; C calls the key direct. */
+export type AnswerLane = 'subscription' | 'key' | 'direct'
+/** The lanes that spend a key. Token-audit `lane` takes only these. */
+export type KeyLane = Exclude<AnswerLane, 'subscription'>
+
+/** Additive answer fields (plan 3.1). Present only on keyed answers, omitted (never null) otherwise. */
+export interface AnswerKeyFields {
+  lane: KeyLane
+  credential: { kind: KeyKind; ref: KeyRef; profileId: string }
+}
+
+/**
+ * Token-audit fields (plan 3.1, 6.3). Record keys are exactly `profile`, `lane`, `credentialKind`
+ * and `usd`; each is written only when set, so a Lane A row is byte-identical to 6.79.0.
+ */
+export interface TokenAuditKeyFields {
+  profile?: string
+  lane?: KeyLane
+  credentialKind?: KeyKind
+  usd?: number
+}
+
+// ── Profiles ─────────────────────────────────────────────────────────────────
+
+/** Which harness a profile runs. `claude` and `codex` are Lane B (through the relay); `direct` is Lane C. */
+export type KeyProfileEngine = 'claude' | 'codex' | 'direct'
+/** Timeout tier for a Lane B Claude profile (plan 7.1): the subscription tier whose budgets it borrows. */
+export type KeyProfileTimeoutTier = 'opus' | 'fable' | 'sonnet' | 'haiku'
+
+export interface KeyProfile {
+  /** `^[a-z0-9][a-z0-9-]{0,31}$` (shared/key-preference.ts KEY_PROFILE_ID_RE). */
+  id: string
+  label: string
+  keyRef: KeyRef
+  engine: KeyProfileEngine
+  /** The provider model id or OpenRouter slug, e.g. `anthropic/claude-sonnet-5.5`. */
+  model: string
+  enabled: boolean
+  timeoutTier: KeyProfileTimeoutTier
+  /** Plan 9.4: offer this profile on `/v1` as `cos-key-<id>`. Default false. */
+  offerOnV1: boolean
+  /** Plan D7: Lane C tools for this profile. Default false; never on by default for a remote endpoint. */
+  directTools: boolean
+  createdAt: string
+  updatedAt: string
+}
+
+/** What `/api/models` publishes as `keyProfiles` while lanes are active (enabled profiles only). */
+export interface PublicKeyProfileOption {
+  id: string
+  label: string
+  engine: KeyProfileEngine
+  model: string
+  keyKind: KeyKind
+  timeoutTier: KeyProfileTimeoutTier
+}
+
+// ── Relay (P2 implements; P3, P4 consume) ────────────────────────────────────
+
+export type RelayEngine = 'claude' | 'codex'
+
+/** Plan 4.2. The relay listens on `127.0.0.1:<ephemeral>` only; never 3141, 3143 or 0.0.0.0. */
+export const RELAY_PATHS = {
+  anthropicMessages: '/relay/a/v1/messages',
+  anthropicCountTokens: '/relay/a/v1/messages/count_tokens',
+  openaiResponses: '/relay/o/v1/responses',
+  health: '/relay/health',
+} as const
+/** Base path a child is pointed at: Claude `ANTHROPIC_BASE_URL=<origin>/relay/a`, Codex `<origin>/relay/o/v1`. */
+export const RELAY_BASE_PATHS = { claude: '/relay/a', codex: '/relay/o/v1' } as const
+
+/** Plan 4.2 upstreams, by key kind. */
+export const RELAY_UPSTREAMS = {
+  openrouterMessages: 'https://openrouter.ai/api/v1/messages',
+  anthropicMessages: 'https://api.anthropic.com/v1/messages',
+  openrouterResponses: 'https://openrouter.ai/api/v1/responses',
+  openaiResponses: 'https://api.openai.com/v1/responses',
+} as const
+
+/** Plan 4.3 nonce limits. */
+export const RELAY_LIMITS = {
+  nonceBytes: 32,
+  /** Canary QA (2026-10-19): 12 parallel Task subagents were measured; 16 leaves headroom, and the relay queues past it. */
+  inFlightPerNonce: 16,
+  bodyCapBytes: 20 * 1024 * 1024,
+  /** Nonce lives until child close plus this. */
+  childCloseGraceMs: 5_000,
+  /** ...or the tier's wall max plus this, whichever comes first. */
+  wallMaxGraceMs: 60_000,
+  /** Logs show at most this many leading characters of a nonce. */
+  nonceLogChars: 4,
+} as const
+
+/** Plan 4.3 binding. One nonce per turn, memory only. */
+export interface RelayNonceBinding {
+  keyRef: KeyRef
+  profileId: string
+  turnId: string
+  sessionId: string
+  engine: RelayEngine
+  /** The profile slug. Plan 4.4: equal forwards, a Claude id or alias is rewritten to it, anything else is 400. */
+  allowedModel: string
+}
+
+export type RelayRevokeReason =
+  | 'child_close'
+  | 'cancel'
+  | 'steer_abort'
+  | 'breaker_open'
+  | 'remove_all'
+  | 'lanes_inactive'
+  | 'expired'
+
+export interface RelayTurnHandle {
+  /** The secret the child presents. Never logged beyond RELAY_LIMITS.nonceLogChars. */
+  nonce: string
+  /** `http://127.0.0.1:<port>` for this boot. */
+  origin: string
+  /** Called by the bridge on child close; the relay keeps the nonce for childCloseGraceMs. */
+  childClosed(): void
+  revoke(reason: RelayRevokeReason): void
+}
+
+export interface RelayIssueOptions {
+  /** The tier's wall max for this turn (plan 4.3 lifetime). */
+  wallMaxMs: number
+}
+
+/** P2's relay. Started lazily by the first keyed turn; closed when keyLanesActive() turns false. */
+export interface KeyRelay {
+  issueTurn(binding: RelayNonceBinding, options: RelayIssueOptions): Promise<RelayTurnHandle>
+  revokeTurn(turnId: string, reason: RelayRevokeReason): void
+  revokeAll(reason: RelayRevokeReason): void
+  /** The listener's port, or null when no listener is open. */
+  port(): number | null
+  close(): Promise<void>
+}
+
+/** Plan 4.4 model policy outcome. */
+export type RelayModelAction = 'forward' | 'rewrite' | 'reject'
+
+/** Plan 4.6 mapping, one value per row. */
+export type RelayFailureKind =
+  | 'cap_refused'
+  | 'key_rejected'
+  | 'out_of_credit'
+  | 'model_gone'
+  | 'rate_limited'
+  | 'upstream_error'
+  | 'network_error'
+  | 'model_not_allowed'
+
+/** Only these count toward the breaker (plan 4.6). */
+export type BreakerCountedFailure = Extract<RelayFailureKind, 'key_rejected' | 'out_of_credit' | 'model_gone'>
+export type BreakerScope = 'key' | 'profile'
+export interface BreakerState {
+  open: boolean
+  failures: number
+  openedAt?: string
+  reopensAt?: string
+}
+export const BREAKER_LIMITS = { failures: 3, openMs: 60 * 60 * 1000 } as const
+
+// ── Meter and ledger (P2) ────────────────────────────────────────────────────
+
+export type KeyLedgerKind = 'reserve' | 'settle' | 'reconcile'
+
+/** One row of `data/key-ledger.jsonl` (0600, atomic append). Never a secret, never a nonce. */
+export interface KeyLedgerRow {
+  ts: string
+  keyRef: KeyRef
+  profile: string
+  lane: KeyLane
+  turnId: string
+  generationId?: string
+  tokens: { input: number; output: number }
+  usd: number
+  kind: KeyLedgerKind
+}
+
+export interface KeyMeter {
+  /** Reserve before forwarding; false means refuse with the cap line. */
+  reserve(input: { keyRef: KeyRef; turnId: string; estimateUsd: number }): { ok: true; reservationId: string } | { ok: false; spentTodayUsd: number; capUsd: number }
+  settle(input: { reservationId: string; usd: number; tokens: { input: number; output: number }; generationId?: string }): void
+  spentTodayUsd(keyRef: KeyRef): number
+}
+
+// ── Child environment names (P3, P4) ─────────────────────────────────────────
+
+export const KEY_LANE_CHILD_ENV = {
+  /** Claude: the nonce, as a Bearer. */
+  claudeToken: 'ANTHROPIC_AUTH_TOKEN',
+  claudeBaseUrl: 'ANTHROPIC_BASE_URL',
+  /** Codex: the nonce, named by `env_key` in the generated config. */
+  codexToken: 'COS_RELAY_TOKEN',
+  /** Marks a keyed child for hooks and the MU child_env() scrub (plan 6.2, 7.3). */
+  profileMarker: 'COS_KEY_PROFILE',
+} as const
+
+// ── Status and lifecycle seams (P1 calls; P2, P3, P6 register) ───────────────
+
+/** P2 and P3 answer these for `GET /api/key-lanes/status`. P1 defaults: 0, closed, []. */
+export interface KeyLanesStatusProvider {
+  spentTodayUsd?(keyRef: KeyRef): number
+  breaker?(keyRef: KeyRef): BreakerState
+  keyedSessionIds?(): string[]
+}
+
+/** Why key lanes stopped being active. Hooks revoke nonces, close the relay, clear bindings. */
+export type KeyLanesInactiveReason = 'disabled' | 'remove_all' | 'no_enabled_profile'
+export type KeyLanesInactiveHook = (reason: KeyLanesInactiveReason) => void | Promise<void>
+
+/** `GET /api/key-lanes/status` body. */
+export interface KeyLanesStatusBody {
+  enabled: boolean
+  active: boolean
+  keys: Array<{ ref: KeyRef; kind: KeyKind; last4: string; capUsd: number; spentTodayUsd: number; breaker: BreakerState }>
+  profiles: KeyProfile[]
+  keyedSessionIds: string[]
+}
+
+/** `details.keyLanes` on `/api/health` (public), present only while enabled. Booleans only. */
+export interface KeyLanesHealthDetail {
+  enabled: true
+  active: boolean
+}