model-compare-opencode-plugin 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-compare-opencode-plugin",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "OpenCode plugin that switches OpenRouter model aliases to the best value-for-money pick from canonical/model-compare's ranking (balanced, price, quality).",
   "keywords": [
     "opencode",

package/src/config.ts

@@ -21,7 +21,7 @@ export type Config = {
   weights: Partial<Record<Priority, Partial<Weights>>>
   pinDays: number // default 14
   minLead: number // default 0.03
-  catalogURL: string // default "https://canonical.github.io/model-compare/catalog.json"
+  catalogURL: string // default "https://model-compare.dev/catalog.json"
   scriptPath: string | null // null → vendored copy
 }
 
@@ -29,7 +29,10 @@ const SOURCES = ["auto", "local", "remote"] as const
 const PRIORITIES = ["balanced", "price", "quality"] as const
 const WEIGHT_KEYS = ["quality", "price", "context", "age"] as const
 
-const DEFAULT_CATALOG_URL = "https://canonical.github.io/model-compare/catalog.json"
+// The published catalog's direct https URL — no redirect involved (the old
+// canonical.github.io home redirected to a plaintext http target, which
+// fetchRemote now refuses; see Ruling 9).
+const DEFAULT_CATALOG_URL = "https://model-compare.dev/catalog.json"
 const FALLBACK_PREFIX = "openrouter/"
 
 // True for plain config objects. Arrays are excluded: their index keys are

package/src/core/catalog.ts

@@ -1,5 +1,5 @@
 // src/core/catalog.ts
-// Catalog document validation (design §5). Accepts schema v2 documents (only) from
+// Catalog document validation (design §5). Accepts schema v3 documents (only) from
 // either source (vendored script or remote catalog) and projects them onto
 // the plugin's Catalog type. Validation only — ranking lives elsewhere.
 
@@ -12,19 +12,48 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
 
+function isNonEmptyStringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length > 0 && value.every((id) => typeof id === "string")
+}
+
+// The steering block (F-11/F-12): the raw upstream entry carries
+// { model, provider: { order, ignore, quantizations?, allow_fallbacks } }.
+// The projection unwraps `provider` as ModelEntry.steering and never projects
+// the top-level `model`. Per-field absence (the pricing-split posture), no
+// throw, no partial field: order/ignore must be non-empty string arrays (an
+// empty list would filter out every endpoint) and allow_fallbacks a boolean —
+// any miss drops the whole block; quantizations is optional and kept only as
+// a non-empty string array, otherwise that field alone is dropped and the
+// block survives.
+function steer(raw: unknown): ModelEntry["steering"] {
+  if (!isObject(raw)) return undefined
+  const provider = raw.provider
+  if (!isObject(provider)) return undefined
+  const order = provider.order
+  const ignore = provider.ignore
+  const fallbacks = provider.allow_fallbacks
+  if (!isNonEmptyStringList(order) || !isNonEmptyStringList(ignore) || typeof fallbacks !== "boolean") {
+    return undefined
+  }
+  const steering: NonNullable<ModelEntry["steering"]> = {
+    order: [...order],
+    ignore: [...ignore],
+    allow_fallbacks: fallbacks,
+  }
+  if (isNonEmptyStringList(provider.quantizations)) steering.quantizations = [...provider.quantizations]
+  return steering
+}
+
 export function validateCatalog(
   raw: unknown,
 ): { ok: true; catalog: Catalog } | { ok: false; reason: string } {
   if (!isObject(raw)) return { ok: false, reason: "catalog must be a JSON object" }
 
-  // Supported schema: v2 only — upstream's current contract (0.3.0: pricing
-  // scalars are effective-tier values; pricing.base/tiers/schedule and a
-  // top-level schedules index were added — ignored here, see the roadmap
-  // for consumer ideas). The plugin has never been released, so no stored
-  // v1 documents exist anywhere; the published catalog has served v2 since
-  // 2026-10-10.
-  if (raw.schema_version !== 2) {
-    return { ok: false, reason: `schema_version must be 2, got ${JSON.stringify(raw.schema_version)}` }
+  // Supported schema: v3 only — upstream's current contract (0.4.0's
+  // schema_version 3). Every other version is rejected with the reason string
+  // the canary and the stored-document path rely on.
+  if (raw.schema_version !== 3) {
+    return { ok: false, reason: `schema_version must be 3, got ${JSON.stringify(raw.schema_version)}` }
   }
   if (typeof raw.generated_at !== "string") {
     return { ok: false, reason: "generated_at must be a string" }
@@ -128,6 +157,11 @@ export function validateCatalog(
     // stays absent, present-but-invalid behaves as absent).
     const input = pricing.input_per_1m
     const output = pricing.output_per_1m
+    // The steering block projects (or reads as absent) per the steer() rules.
+    // The assignment sits AFTER the spread so it explicitly overrides the raw
+    // block that `...entry` would otherwise carry through verbatim — a
+    // hostile steering block must never survive onto the projected entry.
+    const steering = steer(entry.steering)
     models.push({
       ...entry,
       id: entry.id,
@@ -141,6 +175,7 @@ export function validateCatalog(
       context: entry.context,
       scores: { ...components, overall },
       quality,
+      steering,
     })
   }
 
@@ -174,16 +209,26 @@ export function validateCatalog(
 // `Catalog`, not the raw upstream document) by rebuilding the raw shape and
 // running it through validateCatalog: a corrupt or hand-edited record is
 // rejected instead of reaching ranking code. The round trip is lossless for a
-// catalog validateCatalog produced.
+// catalog validateCatalog produced. A model carrying a projected steering
+// block is re-wrapped into the raw { model, provider } shape first — the
+// top-level `model` is never projected, so entry.id stands in for it (the
+// projection ignores it either way). A hand-edited steering block re-projects
+// or reads as absent, exactly like a raw one would.
 export function validateStoredCatalog(
   stored: unknown,
 ): { ok: true; catalog: Catalog } | { ok: false; reason: string } {
   if (!isObject(stored)) return { ok: false, reason: "stored catalog must be an object" }
+  const models = Array.isArray(stored.models)
+    ? stored.models.map((entry) => {
+        if (!isObject(entry) || entry.steering === undefined) return entry
+        return { ...entry, steering: { model: entry.id, provider: entry.steering } }
+      })
+    : stored.models
   return validateCatalog({
-    schema_version: 2,
+    schema_version: 3,
     generated_at: stored.generatedAt,
     parameters: { weights: stored.weights },
-    models: stored.models,
+    models,
     rankings: stored.rankings,
   })
 }

package/src/core/steering.ts

@@ -0,0 +1,145 @@
+// src/core/steering.ts
+// The steering decision core (design §Steering injection + served-endpoint
+// visibility): whether a request may carry the catalog's steering block, the
+// injection shape, and the served-endpoint membership verdict. Pure functions
+// over the data the wiring hooks supply — no I/O, no OpenCode imports.
+//
+// Layering note: the guard module (src/opencode/guard.ts) owns the canonical
+// alias-ref parse, but core modules never import from src/opencode (this
+// repo's rule: only opencode → core). The identification below mirrors the
+// guard's parseAliasRef exactly — variant-blind, exact-priority remainder —
+// and both copies are pinned to the same vectors (tests/unit/guard.test.ts
+// and the steeringFor cases here); a semantic change to one must be mirrored
+// in the other.
+
+import type { ModelEntry, Priority } from "./types"
+
+// A model reference as the hook event carries it (`event.model`), mirroring
+// the guard's ModelRef (src/opencode/guard.ts) structurally — the wiring
+// passes the event's ref straight through, and any `variant` key the event
+// adds is ignored (spike fact 1: the alias ref's variant is not stable across
+// binding styles — absent for root-default/frontmatter, "default" for
+// `--model` — so identification must stay variant-blind).
+export type ModelRef = { providerID: string; id: string }
+
+// The resolved pick for one priority, mirroring the alias registry's
+// AliasTarget (src/opencode/aliases.ts) structurally for the same layering
+// reason: the wiring passes its plan's picks directly.
+export type AliasTarget = { id: string | null; fromFallback: boolean }
+
+// The steering block exactly as ModelEntry.steering projects it (Task 2):
+// OpenRouter's provider routing sub-object. The raw upstream block's
+// top-level `model` field is never part of it.
+export type Steering = NonNullable<ModelEntry["steering"]>
+
+const ALIAS_PREFIX = "model-compare/"
+
+const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+
+// Alias identification over the event's model ref — the guard's parseAliasRef
+// rule mirrored (see the layering note above): ONLY openrouter plus
+// `model-compare/<p>` whose remainder is exactly a priority name; ids may
+// carry more slashes in OpenRouter's vendor/model style, so anything after
+// the priority disqualifies. Accepts undefined for runtime robustness (the
+// caller's ref is runtime data).
+function aliasPriority(ref: ModelRef | undefined): Priority | null {
+  if (ref === undefined || ref.providerID !== "openrouter") return null
+  if (!ref.id.startsWith(ALIAS_PREFIX)) return null
+  const remainder = ref.id.slice(ALIAS_PREFIX.length)
+  return PRIORITIES.includes(remainder as Priority) ? (remainder as Priority) : null
+}
+
+// The steering block to inject for a request, or null when the request must
+// not be steered: a non-alias ref (including a DIRECTLY-PICKED model — even
+// when its id equals the current pick's; matching on that equality would
+// INVERT the rule, since an alias-bound ref is never equal to a concrete pick
+// id while a directly-picked one is — and steer requests outside the aliases,
+// the anti-goal), a pick that resolved to nothing, a body model that is not
+// the pick's id, or a pick whose catalog entry carries no steering block.
+//
+// `bodyModel` is the request body's `model` field when the wiring has read it
+// (the live body carries the pick id verbatim — spike fact 1); undefined
+// skips that gate and lets the alias signal decide. The `models` map is keyed
+// by bare catalog id — the pick ids' form.
+export function steeringFor(
+  eventModel: ModelRef,
+  bodyModel: string | undefined,
+  picks: Partial<Record<Priority, AliasTarget>>,
+  models: Map<string, ModelEntry>,
+): Steering | null {
+  const p = aliasPriority(eventModel)
+  if (p === null) return null
+  const pick = picks[p]
+  if (pick === undefined || pick.id === null) return null
+  if (bodyModel !== undefined && bodyModel !== pick.id) return null
+  return models.get(pick.id)?.steering ?? null
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// The body with the steering block's provider sub-object injected under the
+// `provider` key — or the input returned untouched when it already carries a
+// `provider` key (the plugin never clobbers routing the user or a provider
+// configured) or is not a JSON object. The injected routing object is built
+// field-by-field, never spread from the steering block, so the raw block's
+// top-level `model` field (or any unknown key) cannot reach the body; an
+// absent `quantizations` stays absent (OpenRouter reads the key's presence).
+//
+// Contract the wiring relies on: the SAME reference comes back when nothing
+// was injected, a NEW object when it was — reference inequality is the
+// "re-create the Request" signal.
+export function injectSteering(body: unknown, steering: Steering): unknown {
+  if (!isPlainObject(body) || Object.hasOwn(body, "provider")) return body
+  return {
+    ...body,
+    provider: {
+      order: steering.order,
+      ignore: steering.ignore,
+      ...(steering.quantizations === undefined ? {} : { quantizations: steering.quantizations }),
+      allow_fallbacks: steering.allow_fallbacks,
+    },
+  }
+}
+
+// normalize_provider (vendor/model_compare.py): casefold the name and strip
+// ALL non-alphanumeric characters — "Z.AI", "z-ai" and "z ai" all normalize
+// to "zai". JS toLowerCase stands in for Python's casefold (provider display
+// names are ASCII in practice; a non-ASCII residue the casefold would keep is
+// stripped by the character class either way).
+function normalizeProvider(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "")
+}
+
+// The provider part of a routing reference: the text before the first `/`
+// (`novita/fp8`, `deepinfra/fp8/flex` → `novita`/`deepinfra`), or the whole
+// string when it carries none — a served display name (`Novita`) is therefore
+// its own provider part. Applied to BOTH sides symmetrically (spike fact 3:
+// the served string is a display name, never the script's tagged-slug form).
+function providerPart(ref: string): string {
+  const slash = ref.indexOf("/")
+  return slash === -1 ? ref : ref.slice(0, slash)
+}
+
+// The served-endpoint verdict for one response: compare the response's
+// `provider` string against the steering `order` that was actually applied to
+// the request. `endpoint` is the served string verbatim (the alt+e toast's
+// text) — null only when there is nothing to record (no provider at all, or a
+// name with no provider part). `downgrade` is true ONLY when a parseable
+// provider matches no entry of a NON-EMPTY order; an absent or empty order
+// (no steering data — offline, or a model without a steering block) records
+// the endpoint with no verdict, because `!` may only assert a fallback
+// "despite the steering" when a non-empty order was actually applied.
+export function captureEndpoint(
+  provider: string | null,
+  order: string[] | null,
+): { endpoint: string | null; downgrade: boolean } {
+  if (provider === null) return { endpoint: null, downgrade: false }
+  const served = normalizeProvider(providerPart(provider))
+  if (served === "") return { endpoint: null, downgrade: false }
+  const entries = order ?? []
+  if (entries.length === 0) return { endpoint: provider, downgrade: false }
+  const matched = entries.some((entry) => normalizeProvider(providerPart(entry)) === served)
+  return { endpoint: provider, downgrade: !matched }
+}

package/src/core/types.ts

@@ -20,6 +20,17 @@ export type ModelEntry = {
   }
   context: number
   quality: number | null
+  // The steering block (F-11/F-12): upstream records the provider's
+  // endpoint-routing hints as { model, provider: { order, ignore,
+  // quantizations?, allow_fallbacks } }; the projection unwraps the provider
+  // sub-object into this shape and never projects the top-level `model`.
+  // Present only when the raw block projects cleanly (absent stays absent).
+  steering?: {
+    order: string[]
+    ignore: string[]
+    quantizations?: string[]
+    allow_fallbacks: boolean
+  }
   scores: {
     quality: number
     price: number
@@ -36,7 +47,7 @@ export type Catalog = {
   models: ModelEntry[]
 }
 
-// Upstream.s PRIORITY_WEIGHTS at the pinned tag (v0.3.1; unchanged since v0.3.0). Used when a
+// Upstream.s PRIORITY_WEIGHTS at the pinned tag (v0.4.0; unchanged since v0.3.0). Used when a
 // document carries no `parameters.weights` at all (design §5); individual
 // missing keys fall back to weight 0 instead.
 export const DEFAULT_WEIGHTS: Record<Priority, Weights> = {
@@ -48,3 +59,19 @@ export const DEFAULT_WEIGHTS: Record<Priority, Weights> = {
 // A validated catalog plus when the plugin itself accepted it. The plugin's
 // own clock, not `generated_at`, is the data age (design §5, §9).
 export type Sourced = { doc: Catalog; acquiredAt: number }
+
+// The served-endpoint capture record (design §Steering visibility): what the
+// http.response hook wrote for one session's most recent primary response.
+// `endpoint` is the served `provider` string verbatim (a display name like
+// "Novita" or a tagged slug like "novita/fp8" — spike fact 3); `model` is the
+// response's concrete model id, captured alongside it (the spike confirmed
+// OpenRouter responses carry both). `downgrade` is captureEndpoint's verdict
+// — true ONLY when a non-empty steering order was actually applied to the
+// request and the served provider matches none of it.
+export type EndpointCapture = {
+  sessionID: string
+  endpoint: string
+  model: string
+  downgrade: boolean
+  at: number
+}