dsh-oauth-login 0.2.4

package/src/openrouter-catalog.ts

@@ -0,0 +1,245 @@
+/** One Host-owned cache/refresh loop. It never receives an OAuth token. */
+import { readFile, stat } from 'node:fs/promises'
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { normalizeOpenRouterModels, objectValue, validModelId } from './openrouter-models.ts'
+import { OPENROUTER_COOLDOWN_MS, OPENROUTER_REFRESH_MS } from './openrouter-types.ts'
+import type { OpenRouterCatalogSnapshot, OpenRouterModel } from './openrouter-types.ts'
+
+export const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models'
+export const OPENROUTER_CACHE_FILENAME = '.dsh-oauth-openrouter-models.json'
+const MAX_BYTES = 12 * 1024 * 1024
+const FETCH_TIMEOUT_MS = 15_000
+
+export interface OpenRouterCatalogOptions {
+  filename: string
+  isAuthenticated: () => Promise<boolean>
+  beforeFetch?: () => Promise<unknown>
+  fetch?: typeof globalThis.fetch
+  now?: () => number
+  /** Protect zero-cost legacy selections too, without labelling them free. */
+  initiallyProtectedIds?: readonly string[]
+}
+
+export class OpenRouterCatalog {
+  private entries: OpenRouterModel[] | undefined
+  private protectedIds: Set<string>
+  private connected = false
+  private disposed = false
+  private source: OpenRouterCatalogSnapshot['source'] = 'builtin'
+  private lastUpdatedAt: number | null = null
+  private lastAttemptAt: number | null = null
+  private nextRefreshAt: number | null = null
+  private error: OpenRouterCatalogSnapshot['error'] = null
+  private hydration: Promise<void> | undefined
+  private pending: Promise<void> | undefined
+  private controller: AbortController | undefined
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private generation = 0
+  private readonly listeners = new Set<() => void>()
+  private readonly now: () => number
+
+  constructor(private readonly options: OpenRouterCatalogOptions) {
+    this.now = options.now ?? Date.now
+    this.protectedIds = new Set(options.initiallyProtectedIds ?? [])
+  }
+
+  models(): readonly OpenRouterModel[] | undefined { return this.entries }
+  model(id: string): OpenRouterModel | undefined { return this.entries?.find(model => model.id === id) }
+  protects(id: string): boolean {
+    return id.endsWith(':free') || id === 'openrouter/free' || this.protectedIds.has(id)
+  }
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+  private changed(): void {
+    for (const listener of this.listeners) {
+      // An observer cannot invalidate a successfully loaded catalog.
+      try { listener() } catch { /* Host notification is advisory. */ }
+    }
+  }
+  snapshot(): OpenRouterCatalogSnapshot {
+    return {
+      version: 1,
+      connected: this.connected,
+      refreshing: this.pending !== undefined,
+      source: this.source,
+      lastUpdatedAt: this.lastUpdatedAt,
+      lastAttemptAt: this.lastAttemptAt,
+      nextRefreshAt: this.nextRefreshAt,
+      retryAt: this.lastAttemptAt === null ? null : this.lastAttemptAt + OPENROUTER_COOLDOWN_MS,
+      stale: this.error !== null || this.lastUpdatedAt === null
+        || this.now() - this.lastUpdatedAt >= OPENROUTER_REFRESH_MS,
+      error: this.error,
+      models: this.connected ? (this.entries ?? []).map(model => ({ ...model, freeOnly: this.protects(model.id) })) : [],
+    }
+  }
+  private hydrate(): Promise<void> {
+    this.hydration ??= this.readCache()
+    return this.hydration
+  }
+  private async readCache(): Promise<void> {
+    try {
+      if ((await stat(this.options.filename)).size > MAX_BYTES) throw new Error('cache too large')
+      const raw = objectValue(JSON.parse(await readFile(this.options.filename, 'utf8')))
+      if (raw?.version !== 1 || typeof raw.lastUpdatedAt !== 'number'
+        || !Number.isFinite(raw.lastUpdatedAt) || raw.lastUpdatedAt <= 0
+        || raw.lastUpdatedAt > this.now() + OPENROUTER_COOLDOWN_MS) throw new Error('invalid cache')
+      const entries = normalizeOpenRouterModels(raw.data)
+      if (this.disposed) return
+      this.entries = entries
+      this.lastUpdatedAt = raw.lastUpdatedAt
+      this.source = 'cache'
+      if (Array.isArray(raw.protectedIds)) {
+        for (const id of raw.protectedIds) if (validModelId(id)) this.protectedIds.add(id)
+      }
+      this.rememberFree(entries)
+      this.changed()
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') this.error = 'cache'
+    }
+  }
+  private rememberFree(entries: readonly OpenRouterModel[]): void {
+    for (const model of entries) if (model.priceStatus === 'free') this.protectedIds.add(model.id)
+  }
+
+  /** Startup reads disk first; only a newly completed login forces a refresh. */
+  async syncAuthentication(reason: 'check' | 'login' = 'check'): Promise<void> {
+    await this.hydrate()
+    const generation = this.generation
+    const authenticated = await this.options.isAuthenticated()
+    if (this.disposed || generation !== this.generation) return
+    if (!authenticated) {
+      this.disconnect()
+      return
+    }
+    this.connected = true
+    if (reason === 'login' || this.snapshot().stale) {
+      void this.refresh(reason === 'login')
+    } else if (this.timer === undefined && this.pending === undefined) {
+      this.schedule(Math.max(1, OPENROUTER_REFRESH_MS - (this.now() - this.lastUpdatedAt!)))
+    }
+  }
+
+  /** Coalesced across routes/windows; even forced refreshes honor 60s cooldown. */
+  refresh(force = false): Promise<void> {
+    if (this.pending !== undefined) return this.pending
+    if (!this.connected || this.disposed) return Promise.resolve()
+    if (!force && !this.snapshot().stale) return Promise.resolve()
+    if (this.lastAttemptAt !== null && this.now() - this.lastAttemptAt < OPENROUTER_COOLDOWN_MS) {
+      return Promise.resolve()
+    }
+    const generation = this.generation
+    this.lastAttemptAt = this.now()
+    this.controller = new AbortController()
+    const signal = AbortSignal.any([this.controller.signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
+    const pending = this.fetchCatalog(signal, generation).finally(() => {
+      if (this.pending !== pending) return
+      this.pending = undefined
+      this.controller = undefined
+      if (this.connected && !this.disposed) this.schedule(OPENROUTER_REFRESH_MS)
+    })
+    this.pending = pending
+    return pending
+  }
+
+  private async fetchCatalog(signal: AbortSignal, generation: number): Promise<void> {
+    try {
+      if (!await this.options.isAuthenticated()) {
+        this.disconnect()
+        return
+      }
+      await this.options.beforeFetch?.()
+      signal.throwIfAborted()
+      const response = await (this.options.fetch ?? globalThis.fetch)(OPENROUTER_MODELS_URL, {
+        method: 'GET', headers: { accept: 'application/json' }, signal,
+        redirect: 'error', credentials: 'omit',
+      })
+      if (!response.ok || response.body === null) throw new Error('catalog unavailable')
+      const reader = response.body.getReader()
+      const chunks: Uint8Array[] = []
+      let size = 0
+      try {
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          size += value.byteLength
+          if (size > MAX_BYTES) throw new Error('catalog too large')
+          chunks.push(value)
+        }
+      } finally {
+        await reader.cancel().catch(() => undefined)
+        reader.releaseLock()
+      }
+      const raw = objectValue(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      const links = objectValue(raw?.links)
+      // The official non-paginated request must be complete before replacing.
+      if (raw === undefined || links?.next != null || !Array.isArray(raw.data)
+        || (typeof raw.total_count === 'number' && raw.total_count > raw.data.length)) {
+        throw new Error('partial catalog')
+      }
+      const entries = normalizeOpenRouterModels(raw.data)
+      if (this.disposed || !this.connected || generation !== this.generation || signal.aborted) return
+      const fetchedAt = this.now()
+      const protectedIds = new Set(this.protectedIds)
+      for (const model of entries) if (model.priceStatus === 'free') protectedIds.add(model.id)
+      try {
+        await withFileLock(this.options.filename, async () => {
+          // Preserve free-intent history even if another Host shares this DSH home.
+          try {
+            const cached = objectValue(JSON.parse(await readFile(this.options.filename, 'utf8')))
+            if (Array.isArray(cached?.protectedIds)) {
+              for (const id of cached.protectedIds) if (validModelId(id)) protectedIds.add(id)
+            }
+          } catch { /* Missing/invalid cache is replaced by the validated catalog. */ }
+          await writeFileAtomic(this.options.filename, JSON.stringify({
+            version: 1, lastUpdatedAt: fetchedAt,
+            protectedIds: [...protectedIds], data: raw.data,
+          }) + '\n', { mode: 0o600, dirMode: 0o700 })
+        })
+      } catch {
+        this.error = 'save'
+        return
+      }
+      if (this.disposed || !this.connected || generation !== this.generation || signal.aborted) return
+      // Publish only after free-intent history is durable, so a restart cannot
+      // turn a newly selected, suffix-less promotion into a paid request.
+      this.entries = entries
+      this.protectedIds = protectedIds
+      this.lastUpdatedAt = fetchedAt
+      this.source = 'live'
+      this.error = null
+      this.changed()
+    } catch {
+      if (!this.disposed && this.connected && generation === this.generation) this.error = 'fetch'
+    }
+  }
+
+  private schedule(delay: number): void {
+    clearTimeout(this.timer)
+    this.nextRefreshAt = this.now() + delay
+    this.timer = setTimeout(() => {
+      this.timer = undefined
+      this.nextRefreshAt = null
+      void this.syncAuthentication().then(() => this.refresh()).catch(() => {
+        if (this.connected && !this.disposed) this.schedule(OPENROUTER_REFRESH_MS)
+      })
+    }, delay)
+    this.timer.unref?.()
+  }
+  disconnect(): void {
+    this.generation += 1
+    this.connected = false
+    clearTimeout(this.timer)
+    this.timer = undefined
+    this.nextRefreshAt = null
+    this.controller?.abort()
+    this.controller = undefined
+    this.pending = undefined
+  }
+  dispose(): void {
+    this.disposed = true
+    this.disconnect()
+    this.listeners.clear()
+  }
+}

package/src/openrouter-free.ts

@@ -0,0 +1,76 @@
+/** The zero-cost policy is applied LAST, at the actual provider payload seam. */
+import type { Api, Model, StreamOptions } from '@earendil-works/pi-ai'
+import { LlmError } from '@deepseek-ai/dsh-llm'
+import type { OpenRouterCatalog } from './openrouter-catalog.ts'
+import { objectValue, openRouterDefaultEffort } from './openrouter-models.ts'
+
+const FREE_ONLY_MESSAGE = 'OpenRouter 免费保护：该模型已下线、价格变化或价格未确认，已阻止付费调用。请刷新模型列表并重新选择免费模型。'
+
+export function protectOpenRouterPayload(payload: unknown, modelId: string): Record<string, unknown> {
+  const source = objectValue(payload)
+  if (source === undefined) throw new LlmError(FREE_ONLY_MESSAGE, 'OPENROUTER_FREE_ONLY')
+  const result = { ...source }
+  for (const key of ['models', 'route', 'router', 'preset', 'web_search_options', 'image_config', 'audio']) delete result[key]
+  // No paid hosted search/file parsers/image generation, including defaults.
+  result.model = modelId
+  const pluginIds = new Set(['web', 'file-parser', 'response-healing', 'fusion', 'pareto-router', 'context-compression'])
+  if (Array.isArray(source.plugins)) {
+    for (const plugin of source.plugins) {
+      const id = objectValue(plugin)?.id
+      if (typeof id === 'string') pluginIds.add(id)
+    }
+  }
+  result.plugins = [...pluginIds].map(id => ({ id, enabled: false }))
+  result.modalities = ['text']
+  result.provider = {
+    ...objectValue(source.provider),
+    allow_fallbacks: false,
+    require_parameters: true,
+    max_price: { prompt: 0, completion: 0, request: 0, image: 0, audio: 0 },
+  }
+  if (Array.isArray(result.tools) && result.tools.some(tool => objectValue(tool)?.type !== 'function')) {
+    throw new LlmError('OpenRouter 免费保护：免费调用不启用收费的服务端工具；请选择支持工具调用的免费模型。', 'OPENROUTER_FREE_ONLY')
+  }
+  if (Array.isArray(result.messages)) {
+    for (const message of result.messages) {
+      const content = objectValue(message)?.content
+      if (Array.isArray(content) && content.some(part => !['text', 'image_url'].includes(String(objectValue(part)?.type)))) {
+        throw new LlmError('OpenRouter 免费保护：仅支持文本和图片输入，不启用收费文件解析或音视频处理。', 'OPENROUTER_FREE_ONLY')
+      }
+    }
+  }
+  return result
+}
+
+export function prepareOpenRouterOptions<T extends StreamOptions>(
+  model: Model<Api>,
+  options: T,
+  catalog?: OpenRouterCatalog,
+): T & StreamOptions {
+  // Also protect cached descriptors captured before a subsequent price change.
+  const metadata = catalog?.model(model.id)
+  const protectedAtStart = catalog?.protects(model.id) === true
+    || model.id.endsWith(':free') || model.id === 'openrouter/free'
+    || (metadata === undefined && model.cost.input === 0 && model.cost.output === 0)
+  const defaultEffort = openRouterDefaultEffort(metadata)
+  const existing = options.onPayload
+  return {
+    ...options,
+    onPayload: async (payload: unknown, currentModel: Model<Api>) => {
+      const result = await existing?.(payload, currentModel) ?? payload
+      const data = objectValue(result)
+      if (data !== undefined && metadata?.reasoningMandatory) {
+        const reasoning = objectValue(data.reasoning)
+        if (reasoning?.effort === undefined || reasoning.effort === 'none') {
+          data.reasoning = { ...reasoning, effort: defaultEffort ?? 'high' }
+        }
+      }
+      if (!protectedAtStart && catalog?.protects(model.id) !== true) return result
+      const latest = catalog?.model(model.id)
+      if (catalog?.models() !== undefined && latest?.priceStatus !== 'free') {
+        throw new LlmError(FREE_ONLY_MESSAGE, 'OPENROUTER_FREE_ONLY')
+      }
+      return protectOpenRouterPayload(result, model.id)
+    },
+  }
+}

package/src/openrouter-models.ts

@@ -0,0 +1,155 @@
+import type { Api, Model, ThinkingLevelMap } from '@earendil-works/pi-ai'
+import type { OpenRouterModel } from './openrouter-types.ts'
+
+export function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+export function validModelId(value: unknown): value is string {
+  return typeof value === 'string' && /^~?[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,255}$/.test(value)
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value)
+    ? [...new Set(value.filter((item): item is string => typeof item === 'string' && item.length < 256))]
+    : []
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined
+}
+
+/**
+ * Conservative, all-cost classification. Missing/invalid prices, unknown
+ * structures and conditional overrides never become a free badge. In
+ * particular, a tiny positive decimal must not underflow into a free price.
+ */
+export function classifyOpenRouterPricing(value: unknown): {
+  pricing: Record<string, string>
+  priceStatus: OpenRouterModel['priceStatus']
+} {
+  const source = objectValue(value)
+  const pricing: Record<string, string> = {}
+  let unknown = source === undefined || source.prompt === undefined || source.completion === undefined
+  let paid = false
+  for (const [key, raw] of Object.entries(source ?? {})) {
+    if (key === 'overrides') {
+      // A scheduled/long-context exception is not an unconditional free offer.
+      if (!Array.isArray(raw) || raw.length > 0) unknown = true
+      continue
+    }
+    if (typeof raw !== 'string' || raw.length > 128 || !/^\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i.test(raw)) {
+      unknown = true
+      continue
+    }
+    const numeric = Number(raw)
+    if (!Number.isFinite(numeric) || numeric < 0) {
+      unknown = true
+      continue
+    }
+    pricing[key] = raw
+    if (!/^0+(?:\.0+)?(?:e[+-]?\d+)?$/i.test(raw)) paid = true
+  }
+  return { pricing, priceStatus: paid ? 'paid' : unknown ? 'unknown' : 'free' }
+}
+
+export function normalizeOpenRouterModels(raw: unknown): OpenRouterModel[] {
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > 10_000) {
+    throw new Error('OpenRouter returned an empty or invalid model catalog')
+  }
+  const seen = new Set<string>()
+  const out: OpenRouterModel[] = []
+  for (const entry of raw) {
+    const row = objectValue(entry)
+    if (row === undefined || !validModelId(row.id)) throw new Error('Invalid OpenRouter model ID')
+    // Batch-only endpoints and non-text generators cannot use DSH's chat stream.
+    if (row.id.endsWith(':batch')) continue
+    const architecture = objectValue(row.architecture)
+    const inputModalities = strings(architecture?.input_modalities)
+    const outputModalities = strings(architecture?.output_modalities)
+    if (!inputModalities.includes('text') || !outputModalities.includes('text')) continue
+    if (seen.has(row.id)) throw new Error('Duplicate OpenRouter model ID')
+    const top = objectValue(row.top_provider)
+    const contextWindow = positiveInteger(row.context_length) ?? positiveInteger(top?.context_length)
+    if (contextWindow === undefined) throw new Error('Invalid OpenRouter context limit')
+    const supportedParameters = strings(row.supported_parameters)
+    const reason = objectValue(row.reasoning)
+    const reasoning = supportedParameters.some(key => key === 'reasoning' || key === 'include_reasoning')
+    const supportedEfforts = strings(reason?.supported_efforts)
+    const defaultEffort = typeof reason?.default_effort === 'string' ? reason.default_effort : undefined
+    const maxTokens = Math.min(contextWindow, positiveInteger(top?.max_completion_tokens) ?? Math.min(contextWindow, 8192))
+    out.push({
+      id: row.id,
+      name: typeof row.name === 'string' && row.name.trim() !== '' ? row.name.slice(0, 256) : row.id,
+      contextWindow,
+      maxTokens,
+      inputModalities,
+      outputModalities,
+      supportedParameters,
+      tools: supportedParameters.includes('tools'),
+      reasoning,
+      reasoningMandatory: reasoning && reason?.mandatory === true,
+      ...supportedEfforts.length === 0 ? {} : { supportedEfforts },
+      ...defaultEffort === undefined ? {} : { defaultEffort },
+      ...classifyOpenRouterPricing(row.pricing),
+      ...typeof row.expiration_date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(row.expiration_date)
+        ? { deprecatesAt: row.expiration_date } : {},
+    })
+    seen.add(row.id)
+  }
+  if (out.length === 0) throw new Error('OpenRouter returned no usable text models')
+  return out
+}
+
+const LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
+
+export function openRouterThinkingMap(info: OpenRouterModel, base?: Model<Api>): ThinkingLevelMap | undefined {
+  if (!info.reasoning) return undefined
+  if (info.supportedEfforts === undefined) {
+    return {
+      ...base?.thinkingLevelMap,
+      ...info.reasoningMandatory ? { off: null } : {},
+    }
+  }
+  const map: ThinkingLevelMap = {}
+  for (const level of LEVELS) {
+    const wire = level === 'off' ? 'none' : level
+    map[level] = info.supportedEfforts.includes(wire) && !(level === 'off' && info.reasoningMandatory)
+      ? wire : null
+  }
+  return map
+}
+
+export function openRouterDefaultEffort(info: OpenRouterModel | undefined): string | undefined {
+  if (info?.reasoning !== true) return undefined
+  if (info.defaultEffort !== undefined && info.defaultEffort !== 'none') return info.defaultEffort
+  if (!info.reasoningMandatory) return undefined
+  return info.supportedEfforts?.find(level => level === 'high')
+    ?? info.supportedEfforts?.find(level => level !== 'none')
+    ?? 'high'
+}
+
+export function openRouterPiModel(info: OpenRouterModel, base?: Model<Api>): Model<Api> {
+  const rate = (key: string): number => {
+    const value = Number(info.pricing[key] ?? 0) * 1_000_000
+    return Number.isFinite(value) ? value : 0
+  }
+  const thinkingLevelMap = openRouterThinkingMap(info, base)
+  return {
+    ...base,
+    id: info.id,
+    name: info.name,
+    api: 'openai-completions',
+    provider: 'openrouter',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    input: info.inputModalities.includes('image') ? ['text', 'image'] : ['text'],
+    contextWindow: info.contextWindow,
+    maxTokens: info.maxTokens,
+    reasoning: info.reasoning,
+    ...thinkingLevelMap === undefined ? {} : { thinkingLevelMap },
+    cost: { input: rate('prompt'), output: rate('completion'), cacheRead: rate('input_cache_read'), cacheWrite: rate('input_cache_write') },
+    compat: { ...base?.compat, supportsDeveloperRole: false, thinkingFormat: 'openrouter' },
+  }
+}

package/src/openrouter-types.ts

@@ -0,0 +1,40 @@
+/** Browser-safe contract. No credentials, provider URLs or server imports. */
+export const OPENROUTER_CATALOG_PATH = '/plugins/dsh-oauth-login/openrouter/models'
+export const OPENROUTER_REFRESH_PATH = OPENROUTER_CATALOG_PATH + '/refresh'
+export const OPENROUTER_ROUTE = 'pi-openrouter'
+export const OPENROUTER_REFRESH_MS = 15 * 60_000
+export const OPENROUTER_COOLDOWN_MS = 60_000
+
+export interface OpenRouterModel {
+  id: string
+  name: string
+  contextWindow: number
+  maxTokens: number
+  inputModalities: string[]
+  outputModalities: string[]
+  supportedParameters: string[]
+  tools: boolean
+  reasoning: boolean
+  reasoningMandatory: boolean
+  supportedEfforts?: string[]
+  defaultEffort?: string
+  /** USD per token/unit as supplied by the official catalog, not pi-ai costs. */
+  pricing: Record<string, string>
+  priceStatus: 'free' | 'paid' | 'unknown'
+  /** Endpoint deprecation, NEVER interpreted as a promotion deadline. */
+  deprecatesAt?: string
+}
+
+export interface OpenRouterCatalogSnapshot {
+  version: 1
+  connected: boolean
+  refreshing: boolean
+  source: 'builtin' | 'cache' | 'live'
+  lastUpdatedAt: number | null
+  lastAttemptAt: number | null
+  nextRefreshAt: number | null
+  retryAt: number | null
+  stale: boolean
+  error: 'fetch' | 'cache' | 'save' | null
+  models: Array<OpenRouterModel & { freeOnly: boolean }>
+}

package/src/plugin-config.ts

@@ -0,0 +1,30 @@
+/** Provider-owned knobs published on the `llm-oauth-login` row. */
+
+import z from '@deepseek-ai/schemastery'
+import type { RetryPolicyConfig } from '@deepseek-ai/dsh-llm'
+import { RetryPolicySchema } from '@deepseek-ai/dsh-llm'
+import { PI_LOGIN_STREAM_IDLE_TIMEOUT_MS } from './ids.ts'
+
+/**
+ * `retryPolicy` is executed by shipped `dsh-llm-retry`, not by this plugin.
+ * Omission keeps the RC8 official normal default (5 retries for TIMEOUT /
+ * TRANSPORT / SERVER / RATE_LIMIT / EMPTY_RESPONSE).
+ */
+export interface Config {
+  streamIdleTimeoutMs?: number
+  retryPolicy?: RetryPolicyConfig
+  /**
+   * Hide DSH web_search / web_fetch on OAuth routes that already have hosted
+   * search, and attach those hosted tools to the provider request.
+   */
+  nativeTools?: boolean
+  /** Also attach hosted image generation on Grok and Codex. */
+  nativeImage?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  streamIdleTimeoutMs: z.number().min(1).default(PI_LOGIN_STREAM_IDLE_TIMEOUT_MS),
+  retryPolicy: RetryPolicySchema,
+  nativeTools: z.boolean().default(true),
+  nativeImage: z.boolean().default(true),
+})

package/src/provider.ts

@@ -0,0 +1,137 @@
+/** Installed pi-ai providers remapped onto independent harness routes. */
+
+import { builtinProviders } from '@earendil-works/pi-ai/providers/all'
+import type { Api, ApiKeyAuth, Model, Provider } from '@earendil-works/pi-ai'
+import { PI_LOGIN_PROVIDERS } from './catalog.ts'
+import type { PiLoginProvider } from './catalog.ts'
+import { extraModelsFor } from './extra-models.ts'
+import {
+  DEFAULT_NATIVE_TOOL_POLICY,
+  prepareNativeToolRequest,
+} from './native-tools.ts'
+import type { NativeToolPolicy } from './native-tools.ts'
+import type { OpenRouterCatalog } from './openrouter-catalog.ts'
+import { openRouterPiModel } from './openrouter-models.ts'
+import { prepareOpenRouterOptions } from './openrouter-free.ts'
+
+function harnessApiKeyAuth(name: string): ApiKeyAuth {
+  return {
+    name,
+    resolve: ({ credential }) => Promise.resolve({
+      auth: credential?.key === undefined ? {} : { apiKey: credential.key },
+      source: name,
+    }),
+  }
+}
+
+export function catalogProvider(id: string): Provider {
+  const base = builtinProviders().find(candidate => candidate.id === id)
+  if (base === undefined) {
+    throw new Error(`dsh-oauth-login: the installed pi-ai catalog ships no "${id}" provider`)
+  }
+  return base
+}
+
+/**
+ * Catalog models plus plugin-owned extras, remapped onto the harness route.
+ * Extras fill gaps the installed pi-ai version has not shipped yet (e.g. grok-4.6).
+ */
+/**
+ * Prefer the extra's effort map when the installed catalog still lacks one.
+ * Official OpenRouter generation currently sets `reasoning: true` and no map.
+ */
+function overlayExtraModel(model: Model<Api>, extra: Model<Api>): Model<Api> {
+  const transport = model.provider === 'xai'
+    && model.id === 'grok-4.6'
+    && extra.api === 'openai-responses'
+    ? { api: extra.api, compat: extra.compat }
+    : {}
+  const reasoning = extra.thinkingLevelMap !== undefined && model.thinkingLevelMap === undefined
+    ? { reasoning: extra.reasoning, thinkingLevelMap: extra.thinkingLevelMap }
+    : {}
+  if (Object.keys(transport).length === 0 && Object.keys(reasoning).length === 0) return model
+  return { ...model, ...transport, ...reasoning }
+}
+
+export function harnessModels(spec: PiLoginProvider, catalog?: OpenRouterCatalog): Model<Api>[] {
+  const base = catalogProvider(spec.id).getModels()
+  const extras = extraModelsFor(spec.id)
+  const extraById = new Map(extras.map(model => [model.id, model]))
+  const seen = new Set<string>()
+  const merged: Model<Api>[] = []
+  for (const model of base) {
+    seen.add(model.id)
+    const extra = extraById.get(model.id)
+    merged.push(extra === undefined ? model : overlayExtraModel(model, extra))
+  }
+  for (const extra of extras) {
+    if (seen.has(extra.id)) continue
+    seen.add(extra.id)
+    merged.push(extra)
+  }
+  const live = spec.id === 'openrouter' ? catalog?.models() : undefined
+  const byId = new Map(merged.map(model => [model.id, model]))
+  // A complete successful catalog replaces static discovery. Do not resurrect
+  // removed endpoints from pi-ai/extras; a selected missing ID stays unselected.
+  const models = live === undefined ? merged : live.map(info => openRouterPiModel(info, byId.get(info.id)))
+  return models.map(model => (
+    model.provider === spec.route ? model : { ...model, provider: spec.route }
+  ))
+}
+
+export function preferredModel(
+  spec: PiLoginProvider,
+  models: readonly { id: string }[] = harnessModels(spec),
+): string {
+  const ids = new Set(models.map(model => model.id))
+  for (const candidate of spec.preferredModels) {
+    if (ids.has(candidate)) return candidate
+  }
+  return models[0]?.id ?? spec.id
+}
+
+export function harnessProvider(
+  spec: PiLoginProvider,
+  native: NativeToolPolicy = DEFAULT_NATIVE_TOOL_POLICY,
+  catalog?: OpenRouterCatalog,
+): Provider {
+  const base = catalogProvider(spec.id)
+  return {
+    id: spec.route,
+    name: spec.displayName,
+    ...base.baseUrl === undefined ? {} : { baseUrl: base.baseUrl },
+    auth: { ...base.auth, apiKey: harnessApiKeyAuth(spec.displayName) },
+    getModels: () => harnessModels(spec, catalog),
+    stream: (model, context, options) => {
+      const request = prepareNativeToolRequest(context, options ?? {}, spec.id, model.api, native)
+      const guarded = spec.id === 'openrouter'
+        ? prepareOpenRouterOptions(model, request.options, catalog) : request.options
+      return base.stream(
+        model,
+        request.context,
+        // pi-ai's generic ApiStreamOptions<T> is a conditional type. The
+        // preparation step preserves every provider-specific field and only
+        // adds StreamOptions.onPayload, but TypeScript cannot prove that for T.
+        guarded as typeof options,
+      )
+    },
+    streamSimple: (model, context, options) => {
+      const request = prepareNativeToolRequest(context, options ?? {}, spec.id, model.api, native)
+      const guarded = spec.id === 'openrouter'
+        ? prepareOpenRouterOptions(model, request.options, catalog) : request.options
+      return base.streamSimple(
+        model,
+        request.context,
+        guarded,
+      )
+    },
+  }
+}
+
+export function allCatalogProviders(): Provider[] {
+  return PI_LOGIN_PROVIDERS.map(spec => catalogProvider(spec.id))
+}
+
+export function allHarnessProviders(): Provider[] {
+  return PI_LOGIN_PROVIDERS.map(spec => harnessProvider(spec))
+}