model-compare-opencode-plugin 0.1.1 → 0.3.0

package/src/opencode/commands.ts

@@ -8,7 +8,7 @@
 // not upstream's `generated_at`.
 
 import { effectiveWeights, overallScore } from "../core/rank"
-import type { Catalog, ModelEntry, Priority, Sourced, Weights } from "../core/types"
+import type { Catalog, EndpointCapture, ModelEntry, Priority, Sourced, Weights } from "../core/types"
 import type { AliasTarget } from "./aliases"
 
 const PRIORITIES: Priority[] = ["balanced", "price", "quality"]
@@ -64,13 +64,66 @@ export function sanitizeCatalogText(text: string): string {
 }
 
 // What the report knows beyond the ranking: the pick each alias currently
-// serves (a pin can differ from rank 1 — minLead hysteresis) and which
-// priorities rank under a weights override.
+// serves (a pin can differ from rank 1 — minLead hysteresis), which priorities
+// rank under a weights override, the aliases' enabled flags (the steering
+// note's "every enabled alias" scope), and the session's last-endpoint
+// capture (the footer's last-response line — absent when nothing was
+// captured for the session the report belongs to).
 export type ReportContext = {
   picks?: Partial<Record<Priority, AliasTarget>>
   overrides?: Partial<Record<Priority, Partial<Weights>>>
+  enabled?: Partial<Record<Priority, boolean>>
+  capture?: { endpoint: string; model: string; downgrade: boolean } | null
 }
 
+// The report footer's steering note (design §Steering visibility): the union
+// of the current picks' steering blocks' `quantizations` lists, resolved
+// through the catalog's ModelEntry map, across the three ENABLED aliases.
+// It renders only when EVERY enabled alias's current pick carries
+// quantizations data (a pick missing from the catalog, or a steering block
+// without the list, withholds the whole note — no claim on partial data);
+// a disabled alias's pick is excluded from both the union and the check, and
+// an empty quantizations list contributes nothing without withholding. No
+// enabled aliases → no note. Steering shipped with the Q2 verdict PASS, so
+// the note renders purely per this data rule. (That data-only rule holds
+// because steering injection IS wired — Q2 PASS; in the hypothetical Q2 FAIL
+// world the note's suppression would be a code change, not a data condition.)
+export function steeringNote(
+  doc: Catalog,
+  picks: Partial<Record<Priority, AliasTarget>> = {},
+  enabled: Partial<Record<Priority, boolean>> = {},
+): string | null {
+  const byId = new Map(doc.models.map((model) => [model.id, model]))
+  const union: string[] = []
+  for (const p of PRIORITIES) {
+    if (enabled[p] !== true) continue
+    const pick = picks[p]
+    const steering =
+      pick === undefined || pick.id === null ? undefined : byId.get(pick.id)?.steering
+    const quants = steering?.quantizations
+    if (quants === undefined) return null
+    for (const quant of quants) if (!union.includes(quant)) union.push(quant)
+  }
+  return union.length === 0 ? null : `routing steered to ${union.join(", ")} endpoints (aliases only)`
+}
+
+// The report footer's last-response line (design §Steering visibility, the
+// user's option C): `last response: <model> @ <endpoint>` — the captured
+// response's concrete model id and the served endpoint verbatim. An empty
+// model (a response whose provider carried no model id) omits the model part
+// rather than rendering an empty `@` slot. No capture → null: the line is
+// omitted entirely, never a placeholder.
+export function lastResponseLine(
+  capture: Pick<EndpointCapture, "endpoint" | "model" | "downgrade"> | null | undefined,
+): string | null {
+  if (capture === null || capture === undefined) return null
+  const endpoint = sanitizeCatalogText(capture.endpoint)
+  return capture.model === ""
+    ? `last response: ${endpoint}`
+    : `last response: ${sanitizeCatalogText(capture.model)} @ ${endpoint}`
+}
+
+
 // Whether a priority's weights override actually took effect, shared by the
 // two report builders (formatReport, reportEntries) so the "(custom weights)"
 // label and the recomputed scores can never disagree: the effective weights
@@ -138,6 +191,14 @@ export function formatReport(
       }
     }
   }
+  // The footer (design §Steering visibility): the steering note ABOVE the
+  // last-response line, both omitted when their data is absent. The
+  // transcript's text report and the TUI dialog's footer agree — one
+  // derivation, two surfaces.
+  const note = steeringNote(sourced.doc, context.picks, context.enabled)
+  if (note !== null) lines.push(note)
+  const lastResponse = lastResponseLine(context.capture)
+  if (lastResponse !== null) lines.push(lastResponse)
   return lines.join("\n")
 }
 

package/src/opencode/storage.ts

@@ -16,6 +16,7 @@ export type Storage = {
 // Reads a versioned record. Returns null — never throws — when the key is
 // missing, the value is not a JSON object, or `v` is missing or not 1 (§7.2:
 // corrupt or unknown-version entries are discarded and treated as absent).
+// The doc-cache layer adds its own field checks (readCachedDoc below).
 export async function readRecord<T extends { v: number }>(
   storage: Storage,
   key: string,
@@ -60,7 +61,11 @@ export async function readCachedDoc(storage: Storage, identity: string): Promise
   const record = await readRecord<DocCacheRecord>(storage, docCacheKey(identity))
   if (record === null) return null
   if (record.source !== identity) return null
-  if (typeof record.acquiredAt !== "number") return null
+  // acquiredAt must be a FINITE number, mirroring isValidPin (src/index.ts):
+  // JSON.parse("1e999") parses to Infinity, and now() - Infinity < ttlMs is
+  // always true — an unchecked Infinity would be served as perpetually fresh
+  // and never re-fetched under this identity (final-review BUG-04).
+  if (typeof record.acquiredAt !== "number" || !Number.isFinite(record.acquiredAt)) return null
   const validated = validateStoredCatalog(record.doc)
   if (!validated.ok) {
     console.warn("[model-compare]", `discarding the cached catalog: ${validated.reason}`)

package/src/rpc.ts

@@ -8,16 +8,41 @@
 // surfaces at the session's next turn.
 import { Rpc } from "@opencode/plugin/rpc"
 
+// The capture record the report payload carries (the footer's last-response
+// line and the alt+e toast's data): the served endpoint verbatim, the
+// response's concrete model id (empty when the response had none), and the
+// downgrade verdict. Null when nothing was captured for the session.
+const captureSchema = {
+  type: ["object", "null"],
+  properties: {
+    endpoint: { type: "string" },
+    model: { type: "string" },
+    downgrade: { type: "boolean" },
+  },
+  required: ["endpoint", "model", "downgrade"],
+  additionalProperties: false,
+} as const
+
 export const ModelCompare = Rpc.define({
   id: "model-compare",
   methods: {
     report: {
-      input: { type: "object", properties: {}, additionalProperties: false },
+      // The session whose capture the footer fields report: the TUI passes
+      // the CURRENT session's id (null on the opening screen — no capture
+      // can belong to no session). Optional for the opening screen's
+      // existing `{}` calls.
+      input: {
+        type: "object",
+        properties: { sessionID: { type: ["string", "null"] } },
+        additionalProperties: false,
+      },
       output: {
         type: "object",
         properties: {
           text: { type: "string" },
           age: { type: ["string", "null"] },
+          capture: captureSchema,
+          steeringNote: { type: ["string", "null"] },
           entries: {
             type: "array",
             items: {
@@ -38,7 +63,7 @@ export const ModelCompare = Rpc.define({
             },
           },
         },
-        required: ["text", "age", "entries"],
+        required: ["text", "age", "capture", "steeringNote", "entries"],
         additionalProperties: false,
       },
     },
@@ -50,6 +75,8 @@ export const ModelCompare = Rpc.define({
         properties: {
           sessionID: { type: "string" },
           age: { type: ["string", "null"] },
+          capture: captureSchema,
+          steeringNote: { type: ["string", "null"] },
           entries: {
             type: "array",
             items: {
@@ -70,7 +97,22 @@ export const ModelCompare = Rpc.define({
             },
           },
         },
-        required: ["sessionID", "age", "entries"],
+        required: ["sessionID", "age", "capture", "steeringNote", "entries"],
+        additionalProperties: false,
+      },
+    },
+    // The Q2 fallback's cannot-steer notification (the runtime hook emits it
+    // once per session when a steerable alias request finds no steering
+    // data): the TUI's toast listens for `rpc.model-compare.cannotSteer`.
+    // Declared here like every other event — the host fails emits of
+    // undeclared names with "Unknown RPC event".
+    cannotSteer: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+        },
+        required: ["sessionID"],
         additionalProperties: false,
       },
     },

package/src/sources/drops.ts

@@ -0,0 +1,37 @@
+// src/sources/drops.ts
+// Acquisition diagnostics (final-review BUG-02): since upstream 0.4.0 the
+// vendored script can drop models at its endpoint-pricing stage when their
+// endpoint fetch fails (retries exhausted), reporting it in the raw
+// document's `pool.dropped` map under `endpoint_fetch_failed`. The catalog
+// projection discards that field, so without this check a cold-cache run on
+// a degraded network silently serves a smaller pool — and the smaller pool
+// can change which model a pin switches to. The warning travels in
+// Acquired.warnings, which the refresh tick logs.
+//
+// Scope (orchestrator ruling on the fix-wave-2 brief): `pool.dropped` also
+// carries the by-design funnel drops (a healthy 468-listed run reports
+// ~397 models dropped for context/pricing/batch/ZDR/... to reach its 71
+// candidates). Only `endpoint_fetch_failed` signals a degraded-network
+// shrink; warning on the funnel would fire on every healthy run. Limitation
+// (README, Troubleshooting): under `opencode serve` plugin console output
+// reaches no log — this is diagnostics for contexts that see plugin output,
+// not a user-visible alarm.
+
+// Reads the raw upstream document's `pool.dropped` map and returns one
+// warning string when models were dropped at the endpoint stage. Defensive
+// at every step: a document without a well-formed pool.dropped emits nothing
+// (the warning is best-effort diagnostics, never a validation gate).
+export function dropWarningsFromRaw(raw: unknown): string[] {
+  if (typeof raw !== "object" || raw === null) return []
+  const pool = (raw as { pool?: unknown }).pool
+  if (typeof pool !== "object" || pool === null) return []
+  const dropped = (pool as { dropped?: unknown }).dropped
+  if (typeof dropped !== "object" || dropped === null) return []
+  const endpointFailed = (dropped as Record<string, unknown>).endpoint_fetch_failed
+  if (typeof endpointFailed !== "number" || !Number.isFinite(endpointFailed) || endpointFailed <= 0) {
+    return []
+  }
+  return [
+    `catalog pool shrunk: ${endpointFailed} model(s) dropped at the endpoint stage (endpoint_fetch_failed: ${endpointFailed})`,
+  ]
+}

package/src/sources/index.ts

@@ -57,19 +57,28 @@ export async function acquire(cfg: Config, deps: AcquireDeps): Promise<Acquired>
   // fromCache flag is lifted to the result; sourced itself stays a plain
   // Sourced (§5).
   if (cfg.source === "remote") {
-    const { doc, acquiredAt, fromCache } = await doFetch(cfg.catalogURL, deps.storage)
+    const { doc, acquiredAt, fromCache, warnings: remoteWarnings } = await doFetch(
+      cfg.catalogURL,
+      deps.storage,
+    )
     return {
       sourced: { doc, acquiredAt },
       source: "remote",
       identity: remoteIdentity(cfg.catalogURL),
       fromCache,
-      warnings: [],
+      warnings: remoteWarnings ?? [],
     }
   }
 
   if (cfg.source === "local") {
     const sourced = await runLocal(scriptPath)
-    return { sourced, source: "local", identity: localIdentity(cfg.scriptPath), fromCache: false, warnings: [] }
+    return {
+      sourced,
+      source: "local",
+      identity: localIdentity(cfg.scriptPath),
+      fromCache: false,
+      warnings: sourced.warnings ?? [],
+    }
   }
 
   // Auto: probe first; a usable python gets one local attempt. Either
@@ -84,7 +93,7 @@ export async function acquire(cfg: Config, deps: AcquireDeps): Promise<Acquired>
         source: "local",
         identity: localIdentity(cfg.scriptPath),
         fromCache: false,
-        warnings: [],
+        warnings: sourced.warnings ?? [],
       }
     } catch (error) {
       const cause = asReason(error).replace(LOCAL_PREFIX, "")
@@ -94,13 +103,16 @@ export async function acquire(cfg: Config, deps: AcquireDeps): Promise<Acquired>
     warnings.push(`${probed.reason}; using remote catalog`)
   }
 
-  const { doc, acquiredAt, fromCache } = await doFetch(cfg.catalogURL, deps.storage)
+  const { doc, acquiredAt, fromCache, warnings: remoteWarnings } = await doFetch(
+    cfg.catalogURL,
+    deps.storage,
+  )
   return {
     sourced: { doc, acquiredAt },
     source: "remote",
     identity: remoteIdentity(cfg.catalogURL),
     fromCache,
-    warnings,
+    warnings: [...warnings, ...(remoteWarnings ?? [])],
   }
 }
 

package/src/sources/local.ts

@@ -10,6 +10,7 @@ import { execFile as execFileCallback } from "node:child_process"
 import { promisify } from "node:util"
 import { validateCatalog } from "../core/catalog"
 import type { Sourced } from "../core/types"
+import { dropWarningsFromRaw } from "./drops"
 
 const execFile = promisify(execFileCallback)
 
@@ -120,11 +121,14 @@ export async function probePython(
 
 // Run the script (an explicit path — resolving the vendored default is the
 // caller's job), validate its stdout, and stamp the plugin's own acquisition
-// time on the document (design §5, §9).
+// time on the document (design §5, §9). The raw document's pool.dropped map
+// (models the vendored script dropped at its endpoint stage) travels as
+// acquisition warnings — the projection discards it, so this is the only
+// place the shrink can be observed.
 export async function runLocalScript(
   scriptPath: string,
   timeoutMs = 60_000,
-): Promise<Sourced> {
+): Promise<Sourced & { warnings?: string[] }> {
   let stdout: string
   try {
     const result = await execFile("python3", [scriptPath, "--catalog"], {
@@ -171,5 +175,5 @@ export async function runLocalScript(
   if (!validated.ok) {
     throw new Error(`local source failed: invalid catalog document: ${validated.reason}`)
   }
-  return { doc: validated.catalog, acquiredAt: Date.now() }
+  return { doc: validated.catalog, acquiredAt: Date.now(), warnings: dropWarningsFromRaw(raw) }
 }

package/src/sources/remote.ts

@@ -14,6 +14,7 @@ import {
   writeCachedDoc,
   type Storage,
 } from "../opencode/storage"
+import { dropWarningsFromRaw } from "./drops"
 
 // The cache is revalidated after six hours (design §8).
 const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000
@@ -83,18 +84,69 @@ export type RemoteDeps = {
 // HTTP status, the body parse, and the document each get their own reason).
 // Network errors surface with their own message; non-OK statuses name the
 // status code.
+//
+// Redirects are followed MANUALLY (Ruling 9): a redirect target is not
+// re-checked by the config's https-only catalogURL rule, so a 301 to a
+// plaintext http URL would otherwise deliver the catalog unencrypted. Every
+// hop's resolved target must be https — the first non-https target fails the
+// attempt BEFORE that request is made — and one signal bounds the whole
+// chain.
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+const MAX_REDIRECT_HOPS = 5
+
 async function fetchAndValidate(
   url: string,
   doFetch: typeof fetch,
   now: () => number,
   timeoutMs: number,
-): Promise<{ ok: true; sourced: Sourced } | { ok: false; reason: string }> {
-  let response: Response
-  try {
-    response = await doFetch(url, { signal: AbortSignal.timeout(timeoutMs) })
-  } catch (error) {
-    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+): Promise<{ ok: true; sourced: Sourced & { warnings: string[] } } | { ok: false; reason: string }> {
+  const signal = AbortSignal.timeout(timeoutMs)
+  let current = url
+  for (let hops = 0; ; hops++) {
+    let response: Response
+    try {
+      response = await doFetch(current, { signal, redirect: "manual" })
+    } catch (error) {
+      return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+    }
+    if (REDIRECT_STATUSES.has(response.status)) {
+      await response.body?.cancel().catch(() => {})
+      if (hops >= MAX_REDIRECT_HOPS) {
+        return { ok: false, reason: `too many redirects (more than ${MAX_REDIRECT_HOPS} hops)` }
+      }
+      const location = response.headers?.get("location")
+      if (location === null || location.trim() === "") {
+        return {
+          ok: false,
+          reason: `redirect response ${response.status} without a Location header`,
+        }
+      }
+      let target: URL
+      try {
+        target = new URL(location, current)
+      } catch {
+        return {
+          ok: false,
+          reason: `redirect response ${response.status} with an unparseable Location header`,
+        }
+      }
+      if (target.protocol !== "https:") {
+        return {
+          ok: false,
+          reason: `refusing redirect that leaves https (${target.href})`,
+        }
+      }
+      current = target.href
+      continue
+    }
+    return await acceptResponse(response, now)
   }
+}
+
+async function acceptResponse(
+  response: Response,
+  now: () => number,
+): Promise<{ ok: true; sourced: Sourced & { warnings: string[] } } | { ok: false; reason: string }> {
   if (!response.ok) {
     return { ok: false, reason: `HTTP status ${response.status}` }
   }
@@ -121,7 +173,10 @@ async function fetchAndValidate(
   if (!validated.ok) {
     return { ok: false, reason: `invalid catalog document: ${validated.reason}` }
   }
-  return { ok: true, sourced: { doc: validated.catalog, acquiredAt: now() } }
+  return {
+    ok: true,
+    sourced: { doc: validated.catalog, acquiredAt: now(), warnings: dropWarningsFromRaw(raw) },
+  }
 }
 
 // Fetch the remote catalog with a persisted six-hour cache (design §5, §8):
@@ -133,7 +188,7 @@ export async function fetchRemote(
   url: string,
   storage: Storage,
   deps: RemoteDeps = {},
-): Promise<Sourced & { fromCache: boolean }> {
+): Promise<Sourced & { fromCache: boolean; warnings?: string[] }> {
   const doFetch = deps.fetch ?? globalThis.fetch
   const now = deps.now ?? Date.now
   const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS
@@ -141,14 +196,17 @@ export async function fetchRemote(
   const identity = remoteIdentity(url)
   const cached = await readCachedDoc(storage, identity)
   if (cached !== null && now() - cached.acquiredAt < ttlMs) {
+    // A TTL-fresh cache hit carries no warnings: the cached record is the
+    // projected catalog (no raw pool), and re-warning on every cache read
+    // would turn one shrink into an alarm on each 30-minute tick.
     return { ...cached, fromCache: true }
   }
 
   const attempt = await fetchAndValidate(url, doFetch, now, deps.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS)
   if (attempt.ok) {
-    const { doc, acquiredAt } = attempt.sourced
+    const { doc, acquiredAt, warnings } = attempt.sourced
     await writeCachedDoc(storage, identity, { doc, acquiredAt })
-    return { doc, acquiredAt, fromCache: false }
+    return { doc, acquiredAt, warnings, fromCache: false }
   }
   if (cached !== null) return { ...cached, fromCache: true }
   throw new Error(`remote source failed: ${attempt.reason}`)