@qadanm/opencode-smart-router 0.0.0-stage → 0.4.0

package/src/core/history/opencode.ts

@@ -0,0 +1,173 @@
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+/**
+ * Read OpenCode's own message history.
+ *
+ * The router's ledger only ever saw traffic it routed. Everything before the
+ * first install is invisible to it, which is why an account that was already
+ * 42% used looked untouched. That history is not actually missing: OpenCode
+ * records every message with its provider, model, tokens, cost and timestamp in
+ * a local SQLite database. Reading it gives the estimate a real starting point
+ * on day one, with no paste and no guess.
+ *
+ * Message granularity matters, not session granularity. The Design Plan window is
+ * fixed at seven days from subscription start, so an event needs its own
+ * timestamp to be bucketed into the right window; a session summary carries only
+ * the session's last-updated time and smears a week of work across one instant.
+ *
+ * Deliberate limits:
+ *
+ *   - **Read-only, always.** The database is opened with `readOnly: true`. This
+ *     module must never be able to damage the user's history, and the cheapest
+ *     way to guarantee that is to make a write impossible.
+ *   - **Optional dependency.** `node:sqlite` is experimental and absent on older
+ *     Node. Every failure path returns nothing plus a reason, because history is
+ *     an enhancement and the router must route without it.
+ *   - **Never guesses a schema.** Only the columns this needs are read, and a row
+ *     that does not parse is skipped rather than defaulted.
+ */
+
+export interface HistoryEntry {
+  readonly id: string
+  readonly at: number
+  readonly providerID: string
+  readonly modelID: string
+  readonly cost: number
+  readonly input: number
+  readonly output: number
+  readonly cacheRead: number
+  readonly cacheWrite: number
+}
+
+export interface HistoryRead {
+  readonly entries: ReadonlyArray<HistoryEntry>
+  /** Why nothing was read, when nothing was. */
+  readonly reason?: string
+  readonly dbPath?: string
+}
+
+export interface ReadHistoryOptions {
+  /** Override the database location, for tests. */
+  readonly dbPath?: string
+  readonly home?: string
+  /** Ignore anything older than this. */
+  readonly sinceMs?: number
+  readonly limit?: number
+}
+
+export const defaultHistoryPath = (home = homedir()): string =>
+  join(home, ".local", "share", "opencode", "opencode.db")
+
+const numberOrZero = (value: unknown): number => {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0
+}
+
+/**
+ * Turn one stored message into a history entry, or `undefined` when the row
+ * cannot support one.
+ *
+ * Only assistant messages carry a cost, and only a row with a provider, a model
+ * and a timestamp is usable. Anything else is skipped: a defaulted model would
+ * attribute real spend to the wrong provider.
+ */
+export const toHistoryEntry = (row: { id?: unknown; data?: unknown }): HistoryEntry | undefined => {
+  let data: any
+  try {
+    data = typeof row.data === "string" ? JSON.parse(row.data) : row.data
+  } catch {
+    return undefined
+  }
+  if (!data || typeof data !== "object") return undefined
+  if (data.role !== "assistant") return undefined
+
+  const providerID = typeof data.providerID === "string" ? data.providerID : undefined
+  const modelID = typeof data.modelID === "string" ? data.modelID : undefined
+  const at = typeof data.time?.created === "number" ? data.time.created : undefined
+  if (!providerID || !modelID || at === undefined) return undefined
+
+  const cost = numberOrZero(data.cost)
+  const tokens = data.tokens ?? {}
+  const entry: HistoryEntry = {
+    id: String(row.id ?? `${providerID}:${modelID}:${at}`),
+    at,
+    providerID,
+    modelID,
+    cost,
+    input: numberOrZero(tokens.input),
+    output: numberOrZero(tokens.output),
+    cacheRead: numberOrZero(tokens.cache?.read),
+    cacheWrite: numberOrZero(tokens.cache?.write),
+  }
+  // A row with no cost and no tokens is not evidence of anything.
+  if (entry.cost === 0 && entry.input + entry.output + entry.cacheRead + entry.cacheWrite === 0) return undefined
+  return entry
+}
+
+/**
+ * Read recent history, newest first.
+ *
+ * Synchronous by design: `node:sqlite`'s API is synchronous, and wrapping it in a
+ * promise would suggest it is cheap when it is blocking. Callers run it once at
+ * startup, on a bounded number of rows.
+ */
+export const readOpenCodeHistory = (options: ReadHistoryOptions = {}): HistoryRead => {
+  const dbPath = options.dbPath ?? defaultHistoryPath(options.home)
+  if (!existsSync(dbPath)) {
+    return { entries: [], reason: "No OpenCode database found on this machine", dbPath }
+  }
+
+  let DatabaseSync: any
+  try {
+    // Resolved lazily so a Node without the module still loads this file.
+    ;({ DatabaseSync } = require("node:sqlite"))
+  } catch {
+    return { entries: [], reason: "This Node build has no node:sqlite; history import is unavailable", dbPath }
+  }
+  if (!DatabaseSync) {
+    return { entries: [], reason: "node:sqlite is unavailable; history import is skipped", dbPath }
+  }
+
+  let db: any
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true })
+  } catch (error) {
+    // A locked database is normal while a session is writing. Not an error worth
+    // surfacing as a failure; the next start will read it.
+    return {
+      entries: [],
+      reason: `Could not open the history database read-only (${error instanceof Error ? error.message : String(error)})`,
+      dbPath,
+    }
+  }
+
+  try {
+    const limit = Math.max(1, Math.min(options.limit ?? 5_000, 50_000))
+    const since = options.sinceMs
+    const sql = since
+      ? "SELECT id, data FROM message WHERE time_created >= ? ORDER BY time_created DESC LIMIT ?"
+      : "SELECT id, data FROM message ORDER BY time_created DESC LIMIT ?"
+    const statement = db.prepare(sql)
+    const rows = since ? statement.all(since, limit) : statement.all(limit)
+    const entries: HistoryEntry[] = []
+    for (const row of rows as Array<{ id?: unknown; data?: unknown }>) {
+      const entry = toHistoryEntry(row)
+      if (entry) entries.push(entry)
+    }
+    return { entries, dbPath }
+  } catch (error) {
+    return {
+      entries: [],
+      reason: `Could not read history (${error instanceof Error ? error.message : String(error)})`,
+      dbPath,
+    }
+  } finally {
+    try {
+      db.close()
+    } catch {
+      // Closing a read-only handle that is already gone is not a problem.
+    }
+  }
+}

package/src/core/models/protocol.ts

@@ -0,0 +1,22 @@
+import type { ModelRecord } from "../types.js"
+
+export type ProviderProtocol = "anthropic" | "openai-compat"
+
+/**
+ * Which wire protocol the provider's serving path speaks, as far as prompt
+ * shaping is concerned. The Anthropic Messages protocol is the strict one:
+ * anything but `user | assistant` as a message role is a deterministic 400.
+ * OpenAI-compatible gateways tolerate more shapes, so no repair is needed.
+ *
+ * A seeded record may carry the answer explicitly. Everything else is
+ * inferred: `claude` model names are served over the Anthropic protocol by
+ * every provider observed so far, and the remaining gateways are
+ * OpenAI-compatible including their claude relays that translate for them.
+ */
+export const providerProtocol = (
+  record: Pick<ModelRecord, "protocol" | "providerID" | "modelID">,
+): ProviderProtocol => {
+  if (record.protocol === "anthropic") return "anthropic"
+  if (record.protocol === "openai-compat") return "openai-compat"
+  return /claude/i.test(`${record.providerID}/${record.modelID}`) ? "anthropic" : "openai-compat"
+}

package/src/core/models/registry.ts

@@ -0,0 +1,203 @@
+import type { CostTier, ModelRecord, RouterSettings } from "../types.js"
+import { modelKey } from "../util.js"
+import { modelMonthlyAllowanceUsd, resolvePlan } from "../plans/catalog.js"
+import { SEED_MODELS, type SeedModel } from "./seed.js"
+import { OFFLINE_PROVIDER_ID } from "../offline/mode.js"
+
+export interface LiveModel {
+  readonly id: string
+  readonly providerID: string
+  readonly name?: string
+  readonly limit?: { readonly context?: number; readonly output?: number }
+  readonly capabilities?: {
+    readonly tools?: boolean
+    readonly input?: ReadonlyArray<string>
+    readonly output?: ReadonlyArray<string>
+  }
+  readonly cost?: ReadonlyArray<CostTier>
+  readonly enabled?: boolean
+  readonly disabled?: boolean
+}
+
+export interface RegistryBuildInput {
+  readonly live: ReadonlyArray<LiveModel>
+  readonly settings: RouterSettings
+  readonly seed?: ReadonlyArray<SeedModel>
+  readonly definitions?: ReadonlyArray<SeedModel>
+}
+
+const normalizeCost = (cost: ReadonlyArray<CostTier> | undefined): CostTier[] => {
+  if (!cost || cost.length === 0) return [{ input: 0, output: 0, cache: { read: 0, write: 0 } }]
+  return cost.map((tier) => ({
+    input: Number.isFinite(tier.input) ? tier.input : 0,
+    output: Number.isFinite(tier.output) ? tier.output : 0,
+    cache: {
+      read: Number.isFinite(tier.cache?.read) ? tier.cache.read : 0,
+      write: Number.isFinite(tier.cache?.write) ? tier.cache.write : 0,
+    },
+    ...(tier.tier ? { tier: { type: "context" as const, size: tier.tier.size } } : {}),
+  }))
+}
+
+const fromSeed = (seed: SeedModel): ModelRecord => ({
+  key: seed.key,
+  providerID: seed.providerID,
+  modelID: seed.modelID,
+  name: seed.name,
+  context: seed.context,
+  maxOutput: seed.maxOutput,
+  inputModalities: seed.input,
+  outputModalities: ["text"],
+  tools: seed.tools ?? true,
+  cost: seed.cost,
+  ...(seed.peakPricing ? { peakPricing: seed.peakPricing } : {}),
+  intelligence: seed.intelligence,
+  design: seed.design,
+  designEvidence: seed.designEvidence ?? "curated",
+  ...(seed.creditMultiplier && seed.creditMultiplier > 0 ? { creditMultiplier: seed.creditMultiplier } : {}),
+  ...(seed.protocol ? { protocol: seed.protocol } : {}),
+  ...(seed.escalationOnly ? { escalationOnly: true } : {}),
+  premium: seed.premium ?? false,
+  training: seed.training ?? false,
+  free: seed.free ?? false,
+  tier: seed.tier,
+  approved: seed.approved ?? true,
+  approvalSource: "seed",
+  monthlyAllowanceUsd: seed.monthlyAllowanceUsd,
+  notes: seed.notes,
+})
+
+const mergeLive = (record: ModelRecord, live: LiveModel): ModelRecord => ({
+  ...record,
+  name: live.name && live.name.trim().length > 0 ? live.name : record.name,
+  context: live.limit?.context && live.limit.context > 0 ? live.limit.context : record.context,
+  maxOutput: live.limit?.output && live.limit.output > 0 ? live.limit.output : record.maxOutput,
+  tools: live.capabilities?.tools ?? record.tools,
+  inputModalities:
+    live.capabilities?.input && live.capabilities.input.length > 0 ? [...live.capabilities.input] : record.inputModalities,
+  outputModalities:
+    live.capabilities?.output && live.capabilities.output.length > 0 ? [...live.capabilities.output] : record.outputModalities,
+  cost: normalizeCost(live.cost ?? record.cost),
+})
+
+const fromLive = (live: LiveModel): ModelRecord => {
+  const key = modelKey(live.providerID, live.id)
+  return {
+    key,
+    providerID: live.providerID,
+    modelID: live.id,
+    name: live.name?.trim() || live.id,
+    context: live.limit?.context && live.limit.context > 0 ? live.limit.context : 0,
+    maxOutput: live.limit?.output && live.limit.output > 0 ? live.limit.output : 0,
+    inputModalities: live.capabilities?.input ? [...live.capabilities.input] : ["text"],
+    outputModalities: live.capabilities?.output ? [...live.capabilities.output] : ["text"],
+    tools: live.capabilities?.tools ?? false,
+    cost: normalizeCost(live.cost),
+    intelligence: 0,
+    design: 0,
+    designEvidence: "unverified",
+    premium: false,
+    training: /contributor|-free$|iceman/i.test(live.id),
+    free: /(^|[-/])(free|beam-free|laguna-s-2\.1-free)$/i.test(live.id),
+    tier: 2,
+    approved: false,
+    approvalSource: "discovered",
+    monthlyAllowanceUsd: 0,
+    notes: "Discovered model. Not qualified for automatic routing until approved.",
+  }
+}
+
+export class ModelRegistry {
+  private readonly records = new Map<string, ModelRecord>()
+  private readonly liveCount: number
+
+  constructor(input: RegistryBuildInput) {
+    const seeds = [...(input.seed ?? SEED_MODELS), ...(input.definitions ?? [])]
+    const seedByKey = new Map(seeds.map((seed) => [seed.key, seed]))
+    const liveByKey = new Map(input.live.map((model) => [modelKey(model.providerID, model.id), model]))
+
+    this.liveCount = input.live.length
+
+    for (const seed of seeds) {
+      const live = liveByKey.get(seed.key)
+      this.records.set(seed.key, live ? mergeLive(fromSeed(seed), live) : fromSeed(seed))
+    }
+
+    for (const live of input.live) {
+      const key = modelKey(live.providerID, live.id)
+      if (this.records.has(key)) continue
+      this.records.set(key, fromLive(live))
+    }
+
+    const approved = new Set(input.settings.models.approved)
+    const excluded = new Set(input.settings.models.excluded)
+    const overrides = input.settings.models.tierOverrides
+
+    for (const [key, record] of this.records) {
+      const tierOverride = overrides[key]
+      const explicitlyApproved = approved.has(key)
+      const isExcluded = excluded.has(key)
+      const providerEnabled = input.settings.providers[record.providerID]?.enabled ?? true
+      const approvedBySeed = record.approvalSource === "seed" && record.approved
+      // The plan catalog is authoritative for a plan-metered allowance. A
+      // seed value is a fallback for a provider with no catalog entry, so a
+      // plan change is a configuration change rather than a code change.
+      const plan = resolvePlan(record.providerID, input.settings.providers[record.providerID]?.plan)
+      const catalogAllowance = plan ? modelMonthlyAllowanceUsd(plan, record.modelID) : 0
+      this.records.set(key, {
+        ...record,
+        tier: tierOverride ?? record.tier,
+        monthlyAllowanceUsd: catalogAllowance > 0 ? catalogAllowance : record.monthlyAllowanceUsd,
+        approved: providerEnabled && !isExcluded && (explicitlyApproved || approvedBySeed),
+        approvalSource: explicitlyApproved ? "user" : record.approvalSource,
+      })
+    }
+  }
+
+  get count() {
+    return this.records.size
+  }
+
+  get liveModelCount() {
+    return this.liveCount
+  }
+
+  all(): ModelRecord[] {
+    return [...this.records.values()]
+  }
+
+  get(providerID: string, modelID: string): ModelRecord | undefined {
+    return this.records.get(modelKey(providerID, modelID))
+  }
+
+  getByKey(key: string): ModelRecord | undefined {
+    return this.records.get(key)
+  }
+
+  approved(): ModelRecord[] {
+    return this.all().filter((model) => model.approved)
+  }
+
+  approvedForProvider(providerID: string): ModelRecord[] {
+    return this.approved().filter((model) => model.providerID === providerID)
+  }
+
+  /**
+   * Models available to an offline session.
+   *
+   * Offline mode deliberately bypasses the online `approved` list. Approval is
+   * an online-policy decision ("may this model serve paid work alongside the
+   * hosted floor"), and a local model is excluded from it on purpose. Requiring
+   * the owner to approve a local model for *online* routing in order to use it
+   * while offline would be exactly the kind of manual configuration step this
+   * feature is supposed to remove.
+   *
+   * The offline allow-list still applies on top of this, so the result can only
+   * ever contain local models.
+   */
+  modelsForOffline(): ModelRecord[] {
+    return this.all().filter((model) => model.providerID === OFFLINE_PROVIDER_ID)
+  }
+}
+
+export const buildRegistry = (input: RegistryBuildInput) => new ModelRegistry(input)