@gotcos/glasses-server 6.79.2 → 6.81.0

package/server/lib/direct-sse.ts

@@ -0,0 +1,262 @@
+// Key lanes K1 P5 (plan v4 9.1): the OpenAI chat-completions SSE parser and tool-call accumulator
+// for Lane C1 (direct answers on the Mac).
+//
+// Why not the Ollama parser (ollama-bridge.ts parseOllamaChatDelta): Ollama streams NDJSON and
+// hands over each tool call WHOLE, with `arguments` as an object and no id. OpenAI-style SSE
+// (OpenRouter, OpenAI, any compatible endpoint) sends `data:` events, and a tool call arrives as
+// INDEXED FRAGMENTS: the first fragment for index N carries `id`, `type` and `function.name`, and
+// later fragments for the same index carry more of `function.arguments` as a STRING. The next
+// request must send the assembled calls back as `{ id, type: 'function', function: { name,
+// arguments } }` and each result as `{ role: 'tool', tool_call_id: <that id> }`. Ollama's
+// `tool_name` is meaningless here.
+//
+// Pure: no I/O, no timers, no env. Bounded: an unterminated event, a call's arguments and the
+// number of calls per response are all capped, and going past a cap is an error, never a silent cut.
+
+export const DIRECT_SSE_LIMITS = {
+  /** An event without its blank-line terminator may not grow past this. */
+  eventBufferChars: 1024 * 1024,
+  /** One tool call's assembled arguments. */
+  argumentChars: 64 * 1024,
+  /** Tool calls in one response. */
+  callsPerResponse: 16,
+  /** One tool name. */
+  nameChars: 128,
+} as const
+
+export interface DirectToolCall {
+  id: string
+  type: 'function'
+  function: { name: string; arguments: string }
+}
+
+export interface DirectSseUsage {
+  input: number
+  output: number
+  /** Provider-reported cost in USD (OpenRouter `usage.cost`), when present. */
+  costUsd?: number
+}
+
+export type DirectSseEvent =
+  | { type: 'text'; text: string }
+  | { type: 'error'; message: string; code?: string | number }
+  | { type: 'done' }
+
+function nonNegative(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0
+}
+
+interface Slot {
+  index: number
+  id: string
+  name: string
+  args: string
+}
+
+/**
+ * Assembles indexed fragments into whole calls.
+ *
+ * Index is the key. A fragment without an index (some compatible servers) joins the slot whose id
+ * it repeats, else opens a new slot when it brings a new id, else extends the last slot. The first
+ * non-empty id wins. A name that repeats the one already held is ignored (servers that resend it
+ * on every fragment); anything else is appended (servers that stream the name too). Arguments
+ * concatenate; an OBJECT (non-standard) replaces them with its JSON.
+ */
+export class DirectToolCallAccumulator {
+  private readonly slots: Slot[] = []
+  private overflow: string | null = null
+
+  constructor(private readonly idPrefix: string) {}
+
+  add(fragment: unknown): void {
+    if (this.overflow || !fragment || typeof fragment !== 'object') return
+    const f = fragment as { index?: unknown; id?: unknown; function?: { name?: unknown; arguments?: unknown } }
+    const id = typeof f.id === 'string' ? f.id.trim() : ''
+    let slot: Slot | undefined
+    if (typeof f.index === 'number' && Number.isInteger(f.index) && f.index >= 0) {
+      slot = this.slots.find(s => s.index === f.index)
+      if (!slot) slot = this.open(f.index)
+    } else if (id && this.slots.some(s => s.id === id)) {
+      slot = this.slots.find(s => s.id === id)
+    } else if (id || this.slots.length === 0) {
+      slot = this.open(this.slots.length ? Math.max(...this.slots.map(s => s.index)) + 1 : 0)
+    } else {
+      slot = this.slots[this.slots.length - 1]
+    }
+    if (!slot) return
+    if (id && !slot.id) slot.id = id
+    const name = f.function?.name
+    if (typeof name === 'string' && name) {
+      if (!slot.name) slot.name = name
+      else if (name !== slot.name) slot.name += name
+      if (slot.name.length > DIRECT_SSE_LIMITS.nameChars) this.overflow = 'tool name too long'
+    }
+    const args = f.function?.arguments
+    if (typeof args === 'string') slot.args += args
+    else if (args && typeof args === 'object') slot.args = JSON.stringify(args)
+    if (slot.args.length > DIRECT_SSE_LIMITS.argumentChars) this.overflow = 'tool arguments too long'
+  }
+
+  private open(index: number): Slot | undefined {
+    if (this.slots.length >= DIRECT_SSE_LIMITS.callsPerResponse) {
+      this.overflow = 'too many tool calls in one response'
+      return undefined
+    }
+    const slot: Slot = { index, id: '', name: '', args: '' }
+    this.slots.push(slot)
+    return slot
+  }
+
+  /** Why the calls cannot be trusted (a cap was passed), or null. */
+  error(): string | null {
+    return this.overflow
+  }
+
+  get size(): number {
+    return this.slots.length
+  }
+
+  /**
+   * The whole calls, in index order. A call the server sent without an id gets `<prefix>_<index>`
+   * so the assistant message and its tool result still pair up. A call with no name is dropped.
+   */
+  calls(): DirectToolCall[] {
+    return [...this.slots]
+      .sort((a, b) => a.index - b.index)
+      .filter(s => s.name.trim())
+      .map(s => ({
+        id: s.id || `${this.idPrefix}_${s.index}`,
+        type: 'function' as const,
+        function: { name: s.name.trim(), arguments: s.args.trim() ? s.args : '{}' },
+      }))
+  }
+}
+
+/**
+ * One chat-completions response stream. Feed it bytes with `push`, read the text, error and done
+ * events it returns, and after the stream ends read `tools`, `usage`, `finishReason` and
+ * `generationId`.
+ */
+export class DirectSseParser {
+  private readonly decoder = new TextDecoder()
+  private buffer = ''
+  private ended = false
+  readonly tools: DirectToolCallAccumulator
+  usage: DirectSseUsage | null = null
+  finishReason: string | null = null
+  generationId: string | null = null
+  /** True once `data: [DONE]` was seen. */
+  sawDone = false
+
+  constructor(idPrefix: string) {
+    this.tools = new DirectToolCallAccumulator(idPrefix)
+  }
+
+  push(chunk: Uint8Array | string): DirectSseEvent[] {
+    if (this.ended) return []
+    this.buffer += typeof chunk === 'string' ? chunk : this.decoder.decode(chunk, { stream: true })
+    const events: DirectSseEvent[] = []
+    for (;;) {
+      const m = /\r?\n\r?\n/.exec(this.buffer)
+      if (!m) break
+      const raw = this.buffer.slice(0, m.index)
+      this.buffer = this.buffer.slice(m.index + m[0].length)
+      this.onEvent(raw, events)
+      if (this.ended) return events
+    }
+    if (this.buffer.length > DIRECT_SSE_LIMITS.eventBufferChars) {
+      this.buffer = ''
+      this.ended = true
+      events.push({ type: 'error', message: 'stream event too large' })
+    }
+    return events
+  }
+
+  /** The stream closed: parse a final event that had no blank-line terminator. */
+  finish(): DirectSseEvent[] {
+    if (this.ended) return []
+    const events: DirectSseEvent[] = []
+    const tail = this.buffer + this.decoder.decode()
+    this.buffer = ''
+    if (tail.trim()) this.onEvent(tail, events)
+    this.ended = true
+    return events
+  }
+
+  private onEvent(raw: string, events: DirectSseEvent[]): void {
+    const data = raw.split(/\r?\n/)
+      .filter(line => line.startsWith('data:'))
+      .map(line => line.slice(5).replace(/^ /, ''))
+      .join('\n')
+    // Comments (`: OPENROUTER PROCESSING`), `event:` and `id:` lines carry nothing we need.
+    if (!data.trim()) return
+    if (data.trim() === '[DONE]') {
+      this.sawDone = true
+      this.ended = true
+      events.push({ type: 'done' })
+      return
+    }
+    let chunk: Record<string, unknown>
+    try {
+      chunk = JSON.parse(data) as Record<string, unknown>
+    } catch {
+      return
+    }
+    if (!this.generationId && typeof chunk.id === 'string' && chunk.id) this.generationId = chunk.id
+    const err = chunk.error as { message?: unknown; code?: unknown } | undefined
+    if (err && typeof err === 'object') {
+      const message = typeof err.message === 'string' && err.message.trim() ? err.message.trim().slice(0, 240) : 'upstream error'
+      events.push({ type: 'error', message, ...(typeof err.code === 'string' || typeof err.code === 'number' ? { code: err.code } : {}) })
+      this.ended = true
+      return
+    }
+    const usage = chunk.usage as Record<string, unknown> | undefined
+    if (usage && typeof usage === 'object') {
+      const cost = usage.cost
+      this.usage = {
+        input: nonNegative(usage.prompt_tokens),
+        output: nonNegative(usage.completion_tokens),
+        ...(typeof cost === 'number' && Number.isFinite(cost) && cost >= 0 ? { costUsd: cost } : {}),
+      }
+    }
+    const choices = Array.isArray(chunk.choices) ? chunk.choices : []
+    for (const choice of choices) {
+      if (!choice || typeof choice !== 'object') continue
+      const c = choice as { index?: unknown; delta?: { content?: unknown; tool_calls?: unknown }; finish_reason?: unknown }
+      // One answer per request: only choice 0 is read.
+      if (typeof c.index === 'number' && c.index !== 0) continue
+      const content = c.delta?.content
+      if (typeof content === 'string' && content) events.push({ type: 'text', text: content })
+      if (Array.isArray(c.delta?.tool_calls)) for (const fragment of c.delta!.tool_calls as unknown[]) this.tools.add(fragment)
+      if (typeof c.finish_reason === 'string' && c.finish_reason) {
+        this.finishReason = c.finish_reason
+        if (c.finish_reason === 'error') {
+          events.push({ type: 'error', message: 'upstream finished with an error' })
+          this.ended = true
+          return
+        }
+      }
+    }
+    const toolError = this.tools.error()
+    if (toolError) {
+      events.push({ type: 'error', message: toolError })
+      this.ended = true
+    }
+  }
+}
+
+/** A non-stream JSON body (a server that ignored `stream: true`), read into the same shape. */
+export function parseDirectJsonBody(text: string, idPrefix: string): { parser: DirectSseParser; events: DirectSseEvent[] } {
+  const parser = new DirectSseParser(idPrefix)
+  const events: DirectSseEvent[] = []
+  try {
+    const body = JSON.parse(text) as { id?: unknown; usage?: unknown; error?: unknown; choices?: Array<{ message?: { content?: unknown; tool_calls?: unknown }; finish_reason?: unknown }> }
+    const choices = (body.choices ?? []).map((c, index) => ({
+      index,
+      delta: { content: c?.message?.content, tool_calls: Array.isArray(c?.message?.tool_calls) ? (c.message!.tool_calls as unknown[]).map((t, i) => ({ index: i, ...(t as object) })) : undefined },
+      finish_reason: c?.finish_reason,
+    }))
+    events.push(...parser.push(`data: ${JSON.stringify({ id: body.id, usage: body.usage, error: body.error, choices })}\n\n`))
+  } catch { /* not JSON: an empty parser, the caller reports an empty response */ }
+  return { parser, events }
+}

package/server/lib/fork-thread.ts

@@ -87,6 +87,8 @@ import {
 import { findBannedPermissionArg } from './banned-permission-args.js'
 import { PROVIDER_AUTH_RE, PROVIDER_OVERFLOW_RE, PROVIDER_QUOTA_RE } from './provider-failure-text.js'
 import { cursorIsolationUnavailableError, cursorSpawnEnv, isCursorIsolationUnavailable, releaseCursorSpawnOnExit } from './cursor-spawn-env.js'
+import { anyKeyedSessions, isKeyedSession } from './keyed-sessions.js'
+import { claudeKeySecretsGuardArgs } from './key-secrets-guard.js'
 
 /**
  * Providers that can be forked.
@@ -134,6 +136,8 @@ export type ForkFailure =
   /** The source thread changed while we forked it. The one unforgivable outcome. */
   | 'source_thread_mutated'
   | 'fork_internal_error'
+  /** Key lanes K1 (plan v4 7.3): the source thread ran on a key. Refused before any child. */
+  | 'keyed_session'
 
 /**
  * How much of a new thread may exist on the user's Mac as a result of this call.
@@ -314,6 +318,7 @@ export function buildClaudeForkArgs(nativeThreadId: string): string[] {
     '--fork-session',
     '--permission-mode', 'plan',
     '--allowedTools', '',
+    ...claudeKeySecretsGuardArgs(),
   ]
 }
 
@@ -647,6 +652,12 @@ async function run(request: ForkRequest, deps: ForkDeps, startedAt: number): Pro
   }
   const sourceNativeThreadId: string = request.nativeThreadId
 
+  // Key lanes K1 (plan v4 7.3): a thread that ran on a key is not forked onto the subscription.
+  // One failed stat when no keyed session was ever recorded.
+  if (anyKeyedSessions() && isKeyedSession(sourceNativeThreadId)) {
+    return fail('keyed_session', 'none', { provider, sourceNativeThreadId, durationMs: duration() })
+  }
+
   const base = { provider, sourceNativeThreadId }
 
   if (!isForkPermissionPolicy(request.policy)) {

package/server/lib/key-answer-fields.ts

@@ -0,0 +1,49 @@
+// Key lanes K1, P11 (plan v4 3.1): the additive fields a keyed answer carries, at the top level
+// where the app reads them: `lane`, `credential` (kind, ref, profile id, never a secret),
+// `profile`, and `usd`. On the live `done` event (keyAnswerDoneFields) and on the durable job
+// record (keyAnswerJobFields), so a recovered answer shows its cost too. A subscription answer has
+// no `keyLane` in its metadata, so both return {} and the payload and the record stay byte-identical.
+import type { AnswerKeyFields, KeyKind, KeyLane } from './key-relay-contract.js'
+import { KEY_KINDS, KEY_REF_RE } from './key-relay-contract.js'
+import { isKeyProfileId } from '../../shared/key-preference.js'
+
+export function keyAnswerDoneFields(metadata: { keyLane?: AnswerKeyFields } | undefined): Record<string, unknown> {
+  const keyLane = metadata?.keyLane
+  if (!keyLane) return {}
+  return { lane: keyLane.lane, credential: keyLane.credential, profile: keyLane.credential.profileId }
+}
+
+/** What a durable job record keeps for a keyed answer. */
+export interface QueryJobKeyAnswerFields {
+  lane?: KeyLane
+  credential?: { kind: KeyKind; ref: string; profileId: string }
+  profile?: string
+  usd?: number
+}
+
+/**
+ * The validated key fields of a completion or a replayed journal patch, or {} when any part is
+ * missing or malformed. Built only from the bridge's metadata on a keyed run.
+ */
+export function keyAnswerJobFields(input: unknown): QueryJobKeyAnswerFields {
+  if (!input || typeof input !== 'object') return {}
+  const x = input as { lane?: unknown; credential?: unknown; profile?: unknown; usd?: unknown }
+  if (x.lane !== 'key' && x.lane !== 'direct') return {}
+  const c = x.credential as { kind?: unknown; ref?: unknown; profileId?: unknown } | undefined
+  if (!c || typeof c !== 'object') return {}
+  if (!KEY_KINDS.includes(c.kind as KeyKind) || typeof c.ref !== 'string' || !KEY_REF_RE.test(c.ref) || !isKeyProfileId(c.profileId)) return {}
+  if (x.profile !== c.profileId) return {}
+  const usd = typeof x.usd === 'number' && Number.isFinite(x.usd) && x.usd >= 0 ? Math.round(x.usd * 1e6) / 1e6 : undefined
+  return {
+    lane: x.lane,
+    credential: { kind: c.kind as KeyKind, ref: c.ref, profileId: c.profileId },
+    profile: c.profileId,
+    ...(usd !== undefined ? { usd } : {}),
+  }
+}
+
+/** The completion fields a durable runtime passes for a keyed run: done fields plus usd. */
+export function keyAnswerCompletionFields(metadata: { keyLane?: AnswerKeyFields; usd?: number } | undefined): QueryJobKeyAnswerFields {
+  if (!metadata?.keyLane) return {}
+  return keyAnswerJobFields({ ...keyAnswerDoneFields(metadata), usd: metadata.usd })
+}

package/server/lib/key-catalog.ts

@@ -0,0 +1,301 @@
+// Key lanes K1 P5 (plan v4 10.4, D10): the model catalog for key profiles.
+//
+// Source: OpenRouter's PUBLIC `GET /api/v1/models` (no key, never a key header), cached in
+// memory for 24 hours. Nothing is written to disk and nothing is fetched at import: the first
+// fetch happens only when a caller asks (the catalog route, or a direct turn refreshing prices in
+// the background). With key lanes off nobody asks, so this module does nothing.
+//
+// Curated list (D10): Claude Sonnet 5.5 via OpenRouter is the default, Claude Haiku 5.5 is the
+// one cheaper option. Their built-in prices are the plan's; a live catalog row replaces them.
+// "Downselect" turns the full catalog into at most 20 picker rows of at most 64 characters (the
+// lens list budget), curated first, every row carrying the lanes it can run on (plan 4.4: Lane B
+// takes only `anthropic/` and `openai/` slugs; everything else is direct only).
+//
+// Tests never touch the network: the URL and fetch are injectable and the suite points them at a
+// loopback mock server.
+
+export const KEY_CATALOG_URL = 'https://openrouter.ai/api/v1/models'
+export const KEY_CATALOG_TTL_MS = 24 * 60 * 60 * 1000
+export const KEY_CATALOG_TIMEOUT_MS = 8_000
+/** A catalog body bigger than this is refused rather than parsed (today's is about 1 MB). */
+export const KEY_CATALOG_MAX_BYTES = 16 * 1024 * 1024
+/** Lens list budget (plan 10.4): 20 rows of 64 characters. */
+export const KEY_CATALOG_MAX_ROWS = 20
+export const KEY_CATALOG_ROW_CHARS = 64
+
+export const DEFAULT_KEY_MODEL = 'anthropic/claude-sonnet-5.5'
+export const CHEAPER_KEY_MODEL = 'anthropic/claude-haiku-5.5'
+
+export interface KeyCatalogModel {
+  id: string
+  name: string
+  inUsdPerM: number
+  outUsdPerM: number
+  contextLength?: number
+  /** From `supported_parameters`; undefined when the catalog does not say. */
+  supportsTools?: boolean
+}
+
+export type CuratedRole = 'default' | 'cheaper'
+export interface CuratedKeyModel extends KeyCatalogModel {
+  role: CuratedRole
+}
+
+/** D10. Prices are plan 10.4's and are replaced by the live catalog row when one is cached. */
+export const KEY_CATALOG_CURATED: readonly CuratedKeyModel[] = [
+  { id: DEFAULT_KEY_MODEL, name: 'Claude Sonnet 5.5', inUsdPerM: 2, outUsdPerM: 10, supportsTools: true, role: 'default' },
+  { id: CHEAPER_KEY_MODEL, name: 'Claude Haiku 5.5', inUsdPerM: 0.1, outUsdPerM: 0.5, supportsTools: true, role: 'cheaper' },
+]
+
+export type KeyCatalogLane = 'key' | 'direct'
+
+/** Plan 4.4: which lanes a slug can run on. */
+export function catalogLanesFor(id: string): KeyCatalogLane[] {
+  return id.startsWith('anthropic/') || id.startsWith('openai/') ? ['key', 'direct'] : ['direct']
+}
+
+function perMillion(raw: unknown): number | null {
+  const n = typeof raw === 'number' ? raw : typeof raw === 'string' && raw.trim() ? Number(raw) : NaN
+  if (!Number.isFinite(n) || n < 0) return null
+  return Math.round(n * 1e6 * 1e6) / 1e6
+}
+
+/**
+ * Parse an OpenRouter `/models` body. Rows without an id or a usable price are dropped, as are
+ * rows that do not output text (image-only models cannot answer on the lens).
+ */
+export function parseKeyCatalog(body: unknown): KeyCatalogModel[] {
+  const rows = body && typeof body === 'object' && Array.isArray((body as { data?: unknown }).data)
+    ? (body as { data: unknown[] }).data
+    : []
+  const out: KeyCatalogModel[] = []
+  const seen = new Set<string>()
+  for (const raw of rows) {
+    if (!raw || typeof raw !== 'object') continue
+    const m = raw as {
+      id?: unknown; name?: unknown; context_length?: unknown
+      pricing?: { prompt?: unknown; completion?: unknown }
+      architecture?: { output_modalities?: unknown }
+      supported_parameters?: unknown
+    }
+    if (typeof m.id !== 'string' || !m.id.trim() || m.id.length > 200 || seen.has(m.id)) continue
+    const inUsdPerM = perMillion(m.pricing?.prompt)
+    const outUsdPerM = perMillion(m.pricing?.completion)
+    if (inUsdPerM === null || outUsdPerM === null) continue
+    const outputs = m.architecture?.output_modalities
+    if (Array.isArray(outputs) && !outputs.includes('text')) continue
+    seen.add(m.id)
+    out.push({
+      id: m.id,
+      name: typeof m.name === 'string' && m.name.trim() ? m.name.trim() : m.id,
+      inUsdPerM,
+      outUsdPerM,
+      ...(typeof m.context_length === 'number' && Number.isFinite(m.context_length) ? { contextLength: m.context_length } : {}),
+      ...(Array.isArray(m.supported_parameters) ? { supportsTools: m.supported_parameters.includes('tools') } : {}),
+    })
+  }
+  return out
+}
+
+export interface KeyCatalogOptions {
+  url?: string
+  fetchImpl?: typeof fetch
+  now?: () => number
+  ttlMs?: number
+  timeoutMs?: number
+}
+
+export interface KeyCatalogSnapshot {
+  models: KeyCatalogModel[]
+  /** `openrouter` when a live catalog is cached, `built-in` when only the curated list is known. */
+  from: 'openrouter' | 'built-in'
+  fetchedAt?: number
+}
+
+/** A 24-hour in-memory cache of the public catalog. One fetch in flight at a time. */
+export class KeyCatalog {
+  private readonly url: string
+  private readonly fetchImpl: typeof fetch
+  private readonly now: () => number
+  private readonly ttlMs: number
+  private readonly timeoutMs: number
+  private cached: { at: number; models: KeyCatalogModel[] } | null = null
+  private inflight: Promise<KeyCatalogModel[]> | null = null
+
+  constructor(options: KeyCatalogOptions = {}) {
+    this.url = options.url ?? KEY_CATALOG_URL
+    this.fetchImpl = options.fetchImpl ?? ((...args) => fetch(...args))
+    this.now = options.now ?? Date.now
+    this.ttlMs = options.ttlMs ?? KEY_CATALOG_TTL_MS
+    this.timeoutMs = options.timeoutMs ?? KEY_CATALOG_TIMEOUT_MS
+  }
+
+  /** The cached models while fresh, else null. Never fetches. */
+  peek(): KeyCatalogModel[] | null {
+    if (!this.cached || this.now() - this.cached.at >= this.ttlMs) return null
+    return this.cached.models
+  }
+
+  /** Fresh cache, or one fetch. A failed fetch keeps any stale copy and reports built-in when none. */
+  async get(): Promise<KeyCatalogSnapshot> {
+    const fresh = this.peek()
+    if (fresh) return { models: fresh, from: 'openrouter', fetchedAt: this.cached!.at }
+    try {
+      const models = await this.fetchOnce()
+      return { models, from: 'openrouter', fetchedAt: this.cached!.at }
+    } catch {
+      if (this.cached) return { models: this.cached.models, from: 'openrouter', fetchedAt: this.cached.at }
+      return { models: [], from: 'built-in' }
+    }
+  }
+
+  /** Start a refresh when stale and do not wait for it. Errors are swallowed (prices fall back). */
+  refreshInBackground(): void {
+    if (this.peek() || this.inflight) return
+    void this.fetchOnce().catch(() => undefined)
+  }
+
+  private fetchOnce(): Promise<KeyCatalogModel[]> {
+    if (this.inflight) return this.inflight
+    this.inflight = (async () => {
+      try {
+        // Public endpoint: no Authorization header, ever. Redirects are refused so the request
+        // cannot be bounced somewhere else.
+        const response = await this.fetchImpl(this.url, {
+          method: 'GET',
+          headers: { accept: 'application/json' },
+          redirect: 'error',
+          signal: AbortSignal.timeout(this.timeoutMs),
+        })
+        if (!response.ok) throw new Error(`catalog HTTP ${response.status}`)
+        const length = Number(response.headers.get('content-length') ?? '0')
+        if (length > KEY_CATALOG_MAX_BYTES) throw new Error('catalog too large')
+        const text = await response.text()
+        if (text.length > KEY_CATALOG_MAX_BYTES) throw new Error('catalog too large')
+        const models = parseKeyCatalog(JSON.parse(text))
+        if (models.length === 0) throw new Error('catalog empty')
+        this.cached = { at: this.now(), models }
+        return models
+      } finally {
+        this.inflight = null
+      }
+    })()
+    return this.inflight
+  }
+}
+
+let shared: KeyCatalog | null = null
+
+/** The process catalog, created on first use (never at import). */
+export function getKeyCatalog(): KeyCatalog {
+  if (!shared) shared = new KeyCatalog()
+  return shared
+}
+
+/** Tests only. */
+export function __setKeyCatalogForTests(catalog: KeyCatalog | null): void {
+  shared = catalog
+}
+
+/** The curated two with live prices (and tool support) when the catalog has them. */
+export function curatedKeyModels(models: readonly KeyCatalogModel[] | null): CuratedKeyModel[] {
+  const live = new Map((models ?? []).map(m => [m.id, m]))
+  return KEY_CATALOG_CURATED.map(c => {
+    const m = live.get(c.id)
+    return m
+      ? { ...c, inUsdPerM: m.inUsdPerM, outUsdPerM: m.outUsdPerM, ...(m.supportsTools !== undefined ? { supportsTools: m.supportsTools } : {}), ...(m.contextLength ? { contextLength: m.contextLength } : {}) }
+      : { ...c }
+  })
+}
+
+export interface ModelPriceInfo {
+  inUsdPerM: number
+  outUsdPerM: number
+  from: 'openrouter' | 'built-in' | 'unknown'
+}
+
+/** Price for one slug: live row, else curated, else unknown (the caller decides the fallback). */
+export function keyModelPrice(id: string, models: readonly KeyCatalogModel[] | null): ModelPriceInfo {
+  const live = models?.find(m => m.id === id)
+  if (live) return { inUsdPerM: live.inUsdPerM, outUsdPerM: live.outUsdPerM, from: 'openrouter' }
+  const curated = KEY_CATALOG_CURATED.find(m => m.id === id)
+  if (curated) return { inUsdPerM: curated.inUsdPerM, outUsdPerM: curated.outUsdPerM, from: 'built-in' }
+  return { inUsdPerM: 0, outUsdPerM: 0, from: 'unknown' }
+}
+
+/** True or false when the catalog (or the curated list) says; undefined when nobody knows. */
+export function keyModelSupportsTools(id: string, models: readonly KeyCatalogModel[] | null): boolean | undefined {
+  const live = models?.find(m => m.id === id)
+  if (live && live.supportsTools !== undefined) return live.supportsTools
+  return KEY_CATALOG_CURATED.find(m => m.id === id)?.supportsTools
+}
+
+export interface KeyCatalogRow {
+  id: string
+  /** One lens row: name and price per million, at most KEY_CATALOG_ROW_CHARS characters. */
+  label: string
+  inUsdPerM: number
+  outUsdPerM: number
+  lanes: KeyCatalogLane[]
+  role?: CuratedRole
+}
+
+/** Glyphs the lens font lacks (brief rule 8), em and en dash, and control characters. */
+const LENS_UNSAFE = /[\u0000-\u001f\u007f-\u009f–—←-⇿♦✓⚠↻↺⌛⋯░▓⬡`]/gu
+
+function lensRow(text: string, max = KEY_CATALOG_ROW_CHARS): string {
+  const clean = text.replace(LENS_UNSAFE, ' ').replace(/\s+/g, ' ').trim()
+  const glyphs = [...clean]
+  if (glyphs.length <= max) return clean
+  return `${glyphs.slice(0, max - 1).join('').trimEnd()}…`
+}
+
+function money(n: number): string {
+  if (n === 0) return '$0'
+  if (n < 0.01) return `$${n.toFixed(4).replace(/0+$/, '')}`
+  return `$${n < 1 ? n.toFixed(2) : Number(n.toFixed(2)).toString()}`
+}
+
+/** `Claude Sonnet 5.5 | $2/$10 per M`, cut to one lens row. The price suffix is kept whole. */
+export function catalogRowLabel(m: Pick<KeyCatalogModel, 'name' | 'inUsdPerM' | 'outUsdPerM'>): string {
+  const price = ` | ${money(m.inUsdPerM)}/${money(m.outUsdPerM)} per M`
+  const room = KEY_CATALOG_ROW_CHARS - [...price].length
+  return lensRow(`${lensRow(m.name, Math.max(8, room))}${price}`)
+}
+
+export interface DownselectOptions {
+  query?: string
+  /** Only models that can run on this lane. */
+  lane?: KeyCatalogLane
+  /** Only models the catalog says can call tools. */
+  toolsOnly?: boolean
+  limit?: number
+}
+
+/**
+ * The picker list: curated first (with live prices), then catalog matches for `query` in the
+ * catalog's own order, de-duplicated, at most `limit` (20) rows of at most 64 characters.
+ * Without a query only the curated rows come back (plan 10.4: "More models" is a search).
+ */
+export function downselectKeyCatalog(models: readonly KeyCatalogModel[] | null, options: DownselectOptions = {}): KeyCatalogRow[] {
+  const limit = Math.max(0, Math.min(KEY_CATALOG_MAX_ROWS, Math.floor(options.limit ?? KEY_CATALOG_MAX_ROWS)))
+  const q = (options.query ?? '').trim().toLowerCase().slice(0, 40)
+  const keep = (m: KeyCatalogModel) =>
+    (!options.lane || catalogLanesFor(m.id).includes(options.lane))
+    && (!options.toolsOnly || m.supportsTools === true)
+  const rows: KeyCatalogRow[] = []
+  const seen = new Set<string>()
+  const push = (m: KeyCatalogModel, role?: CuratedRole) => {
+    if (rows.length >= limit || seen.has(m.id) || !keep(m)) return
+    seen.add(m.id)
+    rows.push({ id: m.id, label: catalogRowLabel(m), inUsdPerM: m.inUsdPerM, outUsdPerM: m.outUsdPerM, lanes: catalogLanesFor(m.id), ...(role ? { role } : {}) })
+  }
+  for (const c of curatedKeyModels(models)) push(c, c.role)
+  if (q && models) {
+    for (const m of models) {
+      if (rows.length >= limit) break
+      if (m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q)) push(m)
+    }
+  }
+  return rows
+}

package/server/lib/key-lanes-pricing.ts

@@ -0,0 +1,12 @@
+// Key lanes K1, P11: the one price function the relay meter and the direct lane share. Live
+// OpenRouter catalog prices when P5's 24 h cache has them (never fetched from here), else the
+// curated price, else P2's fallback (the most expensive Claude tier, so an unknown price can only
+// make the cap stricter). Pure apart from reading the in-memory catalog cache.
+import { getKeyCatalog, keyModelPrice } from './key-catalog.js'
+import { FALLBACK_PRICE, type ModelPrice } from './key-relay-meter.js'
+
+export function keyCatalogPeekPrice(model: string): ModelPrice {
+  const info = keyModelPrice(model, getKeyCatalog().peek())
+  if (info.from === 'unknown') return FALLBACK_PRICE
+  return { inUsdPerM: info.inUsdPerM, outUsdPerM: info.outUsdPerM }
+}