opencode-plugboard 0.11.0 → 0.12.0

package/README.md

@@ -30,7 +30,7 @@ export PLUGBOARD_KEY_MY_APP=choose-a-long-random-string
 {
   "plugins": [
     {
-      "package": "opencode-plugboard@0.11.0",
+      "package": "opencode-plugboard@0.12.0",
       "options": {
         "keys": { "my-app": "{env:PLUGBOARD_KEY_MY_APP}" },
         "models": ["anthropic/claude-sonnet-4-6", "github-copilot/*", "opencode-go/glm-5.3-flash"],

package/index.ts

@@ -22,8 +22,9 @@ import { Plugin } from "@opencode/plugin/effect"
 import { Effect } from "effect"
 import { parseOptions } from "./src/config.js"
 import { errorMessage, logError } from "./src/log.js"
+import { withFallbacks } from "./src/fallback.js"
 import { createOpenAiRoute } from "./src/openai/route.js"
-import { ensureBackend, ensurePump, loadServingCatalog, registerGeneration, sessionStore } from "./src/runtime.js"
+import { ensureBackend, ensurePump, loadServingCatalog, processMetrics, registerGeneration, sessionStore } from "./src/runtime.js"
 import { createSessionCaller } from "./src/session/caller.js"
 import { installSessionHooks } from "./src/session/context.js"
 import { createHistoryPort, createSessionPort, loadCatalog } from "./src/session/host.js"
@@ -57,15 +58,21 @@ export default Plugin.define({
         // The readiness gate the caller awaits before creating a session (fails closed: 503 `backend_unavailable`).
         ensureBackend: (app: string, signal: AbortSignal) => ensureBackend(app, signal, bootLocation),
       }
+      // The catalog comes from the preferred accepted generation (a data-root Location when there is
+      // one), not from whichever Location registered last; this generation's own is the fallback.
+      const servingCatalog = async () => {
+        startPump()
+        return loadServingCatalog(ownCatalog)
+      }
       const handle = createOpenAiRoute({
         options,
-        caller: createSessionCaller(callerDeps),
-        // The catalog comes from the preferred accepted generation (a data-root Location when there is
-        // one), not from whichever Location registered last; this generation's own is the fallback.
-        loadCatalog: async () => {
-          startPump()
-          return loadServingCatalog(ownCatalog)
-        },
+        // Aliases written as a list retry the next target before the first output (src/fallback.ts).
+        caller: withFallbacks(createSessionCaller(callerDeps), {
+          options,
+          loadCatalog: servingCatalog,
+          onFallback: options.metrics ? (app) => processMetrics().fallback(app) : undefined,
+        }),
+        loadCatalog: servingCatalog,
       })
       const registration = registerGeneration({
         listen: options.listen,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "license": "MIT",
   "description": "Use the ChatGPT, Claude, Copilot and OpenCode Go logins in your OpenCode server from any app. An OpenCode V2 plugin serving OpenAI-compatible Chat Completions, Responses and model endpoints.",
@@ -30,11 +30,15 @@
     "safe-stable-stringify": "2.5.0"
   },
   "devDependencies": {
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
     "@opencode/plugin": "2.0.26",
     "@types/bun": "1.4.2",
     "@types/escape-html": "^1.0.4",
     "@types/node": "^26.6.2",
+    "conventional-commits-parser": "7.1.3",
     "effect": "4.0.0-rc.112",
+    "lefthook": "2.2.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {

package/src/anthropic/response.ts

@@ -12,8 +12,8 @@ type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
 /** What the encoder needs besides the model events: Messages presentation state. The request decoder produces it. */
 export interface MessagesExchange {
-  /** The model string the client sent; echoed in the message object. */
-  readonly model: string
+  /** The model string the client sent; echoed in the message object. A request that used an alias with fallbacks echoes the target that answered (`CallContext.onServed`). */
+  model: string
   readonly stream: boolean
   /** `thinking` was enabled or adaptive: reasoning text is returned as thinking blocks. */
   readonly thinking: boolean

package/src/anthropic/route.ts

@@ -25,6 +25,7 @@ import {
   sseWriter,
   type RequestScope,
 } from "../http.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
 import { resolveModel } from "../models.js"
 import { dropRejected } from "../openai/sampling.js"
 import type { RouteHost } from "../openai/route.js"
@@ -45,7 +46,7 @@ export interface MessagesCall {
   readonly response: ServerResponse
   readonly scope: RequestScope
   /** The route's log fields: the route name, the app, the resolved model, dropped parameters, and the outcome of a stream that failed after it committed. */
-  readonly info: { route: string; app?: string; model?: string; failed?: string; dropped?: string }
+  readonly info: ServedInfo & { route: string; app?: string; model?: string; failed?: string; dropped?: string }
 }
 
 const header = (request: IncomingMessage, name: string): string | undefined => {
@@ -121,6 +122,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           response.setHeader(SESSION_HEADER, recordID)
         },
+        onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       }),
       scope,
     )

package/src/completions/response.ts

@@ -11,8 +11,8 @@ import { encodeError, type StreamChoice, type StreamResult } from "../openai/res
 
 /** What the encoders need besides the model events; the request decoder produces it, the model call never sees it. */
 export interface CompletionsExchange {
-  /** The model string the client sent; echoed in every response object. */
-  readonly model: string
+  /** The model string the client sent; echoed in every response object. A request that used an alias with fallbacks echoes the target that answered (`CallContext.onServed`). */
+  model: string
   readonly stream: boolean
   /** `stream_options.include_usage`: a final chunk with `choices: []` and the summed usage. */
   readonly includeUsage: boolean
@@ -144,4 +144,5 @@ export const completionsCodec = (exchange: CompletionsExchange): ChoiceCodec =>
     choices: [],
     usage: encodeUsage(usage),
   }),
+  setModel: (model) => void (exchange.model = model),
 })

package/src/completions/route.ts

@@ -11,6 +11,7 @@
 
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import type { ServedInfo } from "../fallback.js"
 import { sendJson, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { serveChoices } from "../openai/fanout.js"
@@ -28,7 +29,7 @@ export interface CompletionsCall {
   readonly response: ServerResponse
   readonly scope: RequestScope
   /** The route's log fields: the resolved model, the sampling parameters dropped, and the outcome of a stream that failed after it committed. */
-  readonly info: { model?: string; failed?: string; dropped?: string }
+  readonly info: ServedInfo & { model?: string; failed?: string; dropped?: string }
 }
 
 export async function serveCompletions(host: RouteHost, { app, body, response, scope, info }: CompletionsCall): Promise<void> {

package/src/config.ts

@@ -2,6 +2,7 @@
 
 import { createHash, timingSafeEqual } from "node:crypto"
 import type { PlugError } from "./contract.js"
+import { allowedBy, parseModelRef } from "./models.js"
 import { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
 
@@ -14,6 +15,12 @@ export interface PlugboardOptions {
   readonly models: ReadonlyArray<string>
   /** Alias -> `provider/model[#variant]`. Targets must also pass the allowlist. */
   readonly aliases: Readonly<Record<string, string>>
+  /**
+   * Alias -> the targets after the first, in order, for an alias written as an array. `aliases` holds the
+   * first target, so everything that resolves an alias keeps working; the model caller retries the rest
+   * (`src/fallback.ts`). Absent for an alias with one target. Every target passes the allowlist.
+   */
+  readonly fallbacks: Readonly<Record<string, ReadonlyArray<string>>>
   readonly maxTools: number
   /** Most model calls one request may fan out to: `n` for chat completions, prompts x `n` for legacy completions. Each is a full call and a kept session. */
   readonly maxN: number
@@ -137,18 +144,28 @@ export function parseOptions(raw: unknown): PlugboardOptions {
       throw new Error(`plugboard model \`${String(pattern)}\` must be \`provider/model\`, \`provider/model#variant\` or \`provider/*\``)
 
   const aliasEntries: Array<[string, string]> = []
-  if (input.aliases !== undefined && !isRecord(input.aliases)) throw new Error("plugboard option `aliases` must be an object of alias -> model")
+  const fallbackEntries: Array<[string, string[]]> = []
+  if (input.aliases !== undefined && !isRecord(input.aliases)) throw new Error("plugboard option `aliases` must be an object of alias -> model or alias -> [model, ...]")
   for (const [alias, target] of Object.entries(input.aliases ?? {})) {
     if (alias.length === 0 || /[\s]/.test(alias)) throw new Error(`plugboard alias \`${alias}\` must be a non-empty string without whitespace`)
     // Plain-object lookups downstream would hit the prototype accessor instead of the alias.
     if (alias === "__proto__") throw new Error("plugboard alias `__proto__` is not allowed")
-    if (typeof target !== "string" || !ALIAS_TARGET.test(target))
-      throw new Error(`plugboard alias \`${alias}\` must target \`provider/model\` or \`provider/model#variant\``)
+    const chain = Array.isArray(target) ? target : [target]
+    if (chain.length === 0) throw new Error(`plugboard alias \`${alias}\` must list at least one target`)
+    for (const entry of chain) {
+      if (typeof entry !== "string" || !ALIAS_TARGET.test(entry))
+        throw new Error(`plugboard alias \`${alias}\` must target \`provider/model\` or \`provider/model#variant\` (or a list of them)`)
+      // A list is new, so it is strict: a target the allowlist would refuse can never serve, so fail at load.
+      if (Array.isArray(target) && !allowedBy(models as string[], parseModelRef(entry)!))
+        throw new Error(`plugboard alias \`${alias}\` target \`${entry}\` is not allowed by the \`models\` option`)
+    }
     if (CANONICAL_SHAPE.test(alias))
       throw new Error(`plugboard alias \`${alias}\` is written like a \`provider/model\` id; aliases must not contain \`/\` (use a short name such as \`fast\`)`)
-    aliasEntries.push([alias, target])
+    aliasEntries.push([alias, chain[0] as string])
+    if (chain.length > 1) fallbackEntries.push([alias, chain.slice(1) as string[]])
   }
   const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
+  const fallbacks: Record<string, string[]> = Object.fromEntries(fallbackEntries)
 
   const remoteImages = parseRemoteImages(input.remoteImages)
   if (input.dropUnsupportedParams !== undefined && typeof input.dropUnsupportedParams !== "boolean")
@@ -170,6 +187,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     keys,
     models: models as string[],
     aliases,
+    fallbacks,
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
     maxN: positiveInt(input.maxN, "maxN", DEFAULTS.maxN, 64),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),

package/src/contract.ts

@@ -168,6 +168,19 @@ export interface CallContext {
   readonly signal: AbortSignal
   /** Called once, before the first event, with the id of the history record this call writes (if any). */
   readonly onRecord?: (recordID: string) => void
+  /**
+   * Called once, before the first event, only for a request whose model is an alias with fallbacks
+   * (`src/fallback.ts`): which target answered and how many earlier targets failed first. A front-end
+   * uses it for `x-plugboard-model` and the `model` it echoes. A call that fails on every target never
+   * reports it.
+   */
+  readonly onServed?: (served: ServedModel) => void
+}
+
+/** The target of an alias that answered: `provider/model[#variant]`, and the targets tried before it. */
+export interface ServedModel {
+  readonly model: string
+  readonly fallbacks: number
 }
 
 /** The seam between the core and a backend (the session backend now, `ctx.llm.stream` possibly later). */

package/src/discovery.ts

@@ -94,6 +94,8 @@ export interface Discovery {
     readonly state: ModelsState
     readonly allowlist: ReadonlyArray<string>
     readonly aliases: Readonly<Record<string, string>>
+    /** Alias -> the targets tried after its first one, for aliases written as a list. Absent when there are none. */
+    readonly fallbacks?: Readonly<Record<string, ReadonlyArray<string>>>
     /** Ids `GET /v1/models` lists (allowlist intersected with the catalog, plus aliases). */
     readonly available?: number
     readonly hint?: string
@@ -171,6 +173,7 @@ export function buildDiscovery({ options, app, catalog }: DiscoveryInput): Disco
             state,
             allowlist: options.models,
             aliases: options.aliases,
+            ...(Object.keys(options.fallbacks).length > 0 ? { fallbacks: options.fallbacks } : {}),
             ...(catalog ? { available: listed.length } : {}),
             ...(modelsHint ? { hint: modelsHint } : {}),
           },
@@ -202,7 +205,7 @@ export function renderDiscoveryHtml(doc: Discovery): string {
     if (models.available !== undefined) sections.push(`<p>${escapeHtml(models.available)} model ids available.</p>`)
     sections.push(`<h3>Allowlist</h3>${models.allowlist.length > 0 ? list(models.allowlist) : "<p>Empty.</p>"}`)
     const aliases = Object.entries(models.aliases)
-    if (aliases.length > 0) sections.push(`<h3>Aliases</h3>${list(aliases.map(([alias, target]) => `${alias} -> ${target}`))}`)
+    if (aliases.length > 0) sections.push(`<h3>Aliases</h3>${list(aliases.map(([alias, target]) => [alias, target, ...(models.fallbacks?.[alias] ?? [])].join(" -> ")))}`)
   }
   if (doc.suggestedModels) {
     sections.push(`<h2>Suggested <code>models</code> option</h2>${pre(`"models": ${JSON.stringify(doc.suggestedModels)}`)}`)

package/src/fallback.ts

@@ -0,0 +1,167 @@
+/**
+ * Ordered model fallbacks: a `ModelCaller` wrapper, so every front-end gets them.
+ *
+ * An alias written as a list (`"fast": ["a/x", "b/y"]`) is a chain. The route resolves the first
+ * target as usual; this wrapper calls it, looks ahead to the first event only, and when that event
+ * is a failure of a retryable class (or the call throws, or ends with nothing) it calls the next
+ * target in a fresh call, so each attempt is its own session. Once any event has been handed on
+ * nothing is retried: a partly streamed answer is never restarted. Attempts are capped at the chain
+ * length, share the request's signal (so the deadline and a disconnect end the chain) and nothing is
+ * buffered beyond that first event.
+ *
+ * A call whose model is not an alias with fallbacks goes straight to the wrapped caller.
+ */
+
+import type { ServerResponse } from "node:http"
+import type { PlugboardOptions } from "./config.js"
+import type { CallContext, CatalogModel, ModelCaller, ModelRef, PlugError, PlugEvent, PlugRequest, ServedModel } from "./contract.js"
+import { log } from "./log.js"
+import { fallbackRefs, refToString } from "./models.js"
+import { dropRejected } from "./openai/sampling.js"
+
+export interface FallbackDeps {
+  readonly options: PlugboardOptions
+  /** The serving Location's enabled models; read only after a first failure, to skip targets that are not available. */
+  loadCatalog(): Promise<ReadonlyArray<CatalogModel>>
+  /** A call is about to be retried on the next target (metrics). */
+  readonly onFallback?: (app: string) => void
+}
+
+/**
+ * Failures that say something about this model or provider, not about the request: another target
+ * may well answer. Client errors (invalid request, context length, content filter) and plugboard's
+ * own failures (backend not ready, bad preparation) are not retried. `provider_auth_failed` is: a
+ * provider that lost its sign-in is as down as one that is rate limiting.
+ */
+const RETRYABLE = new Set([
+  "rate_limited",
+  "quota_exceeded",
+  "provider_unavailable",
+  "provider_timeout",
+  "provider_auth_failed",
+  "model_run_failed",
+  "prompt_failed",
+  "backend_failed",
+])
+
+export const MODEL_HEADER = "x-plugboard-model"
+export const FALLBACKS_HEADER = "x-plugboard-fallbacks"
+
+/** The route's log fields a served model fills in. */
+export interface ServedInfo {
+  served?: string
+  fallbacks?: number
+}
+
+/**
+ * The `CallContext.onServed` of a route: `x-plugboard-model` (and `x-plugboard-fallbacks` when targets
+ * failed first) while the headers are still open, and the log fields. The first call wins, so several
+ * choices of one request report the first answer. `then` runs for that first call (a single-call route
+ * echoes the served model in the body there).
+ */
+export function reportServed(response: ServerResponse, info: ServedInfo, then?: (served: ServedModel) => void): (served: ServedModel) => void {
+  return (served) => {
+    if (info.served !== undefined) return
+    info.served = served.model
+    info.fallbacks = served.fallbacks
+    if (!response.headersSent && !response.destroyed) {
+      response.setHeader(MODEL_HEADER, served.model)
+      if (served.fallbacks > 0) response.setHeader(FALLBACKS_HEADER, String(served.fallbacks))
+    }
+    then?.(served)
+  }
+}
+
+export const isRetryable = (error: PlugError): boolean => error.code !== undefined && RETRYABLE.has(error.code)
+
+/** The caller's events with a chain of fallbacks behind the request's model; see the file comment. */
+export function withFallbacks(inner: ModelCaller, deps: FallbackDeps): ModelCaller {
+  return {
+    stream(request, context) {
+      if (!Object.hasOwn(deps.options.fallbacks, request.model)) return inner.stream(request, context)
+      return chain(inner, deps, request, context)
+    },
+  }
+}
+
+async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
+  let rest: ModelRef[] | undefined
+  let ref = request.ref
+  let attempt = 0
+  for (;;) {
+    // The history id of this attempt: handed on only if the attempt is the one that answers (or the last).
+    let recordID: string | undefined
+    const next = attempt === 0 ? request : retarget(deps.options, request, ref)
+    const iterator = inner.stream(next, { ...context, onRecord: (id) => void (recordID = id) })[Symbol.asyncIterator]()
+
+    let first: IteratorResult<PlugEvent> | undefined
+    let thrown: { readonly error: unknown } | undefined
+    try {
+      first = await iterator.next()
+    } catch (error) {
+      thrown = { error }
+    }
+
+    // Why this attempt failed before any output, or undefined when it answered.
+    let reason: string | undefined
+    if (thrown) reason = "caller_error"
+    else if (first!.done) reason = "no_response"
+    else if (first!.value.type === "error" && isRetryable(first!.value.error)) reason = first!.value.error.code
+    if (context.signal.aborted) reason = undefined
+
+    if (reason !== undefined) {
+      rest ??= await resolveRest(deps, request)
+      const target = rest[attempt]
+      if (target) {
+        if (!thrown) await close(iterator)
+        log("model.fallback", { app: context.app, from: refToString(ref), to: refToString(target), reason, attempt: attempt + 1 })
+        deps.onFallback?.(context.app)
+        ref = target
+        attempt++
+        continue
+      }
+      log("model.fallback_exhausted", { app: context.app, attempts: attempt + 1, reason })
+    }
+
+    // Answered, ran out of targets, or the request ended: this attempt's outcome is the response.
+    if (recordID !== undefined) report(context, recordID)
+    if (thrown) throw thrown.error
+    if (first!.done) return
+    // An error is not an answer: a call that fails (non-retryable, or on its last target) reports no served model.
+    if (reason === undefined && first!.value.type !== "error") context.onServed?.({ model: refToString(ref), fallbacks: attempt })
+    try {
+      yield first!.value
+      for (let step = await iterator.next(); !step.done; step = await iterator.next()) yield step.value
+    } finally {
+      await close(iterator)
+    }
+    return
+  }
+}
+
+/** The request for a later target: its ref, and the sampling parameters that target is known to reject dropped. */
+function retarget(options: PlugboardOptions, request: PlugRequest, ref: ModelRef): PlugRequest {
+  return { ...request, ref, ...(options.dropUnsupportedParams ? { generation: dropRejected(ref, request.generation).generation } : {}) }
+}
+
+/** The fallbacks that are allowed and enabled. A catalog that cannot be loaded leaves none: the failure stands. */
+async function resolveRest(deps: FallbackDeps, request: PlugRequest): Promise<ModelRef[]> {
+  try {
+    return fallbackRefs(deps.options, request.model, await deps.loadCatalog())
+  } catch {
+    return []
+  }
+}
+
+const report = (context: CallContext, recordID: string): void => {
+  try {
+    context.onRecord?.(recordID)
+  } catch {}
+}
+
+/** Ends an attempt's stream so its cleanup runs; it must never fail the request. */
+async function close(iterator: AsyncIterator<PlugEvent>): Promise<void> {
+  try {
+    await iterator.return?.()
+  } catch {}
+}

package/src/gemini/response.ts

@@ -15,8 +15,8 @@ type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
 /** What the encoder needs besides the model events: Gemini presentation state. The request decoder produces it. */
 export interface GeminiExchange {
-  /** The model string from the URL; echoed as `modelVersion`. */
-  readonly model: string
+  /** The model string from the URL; echoed as `modelVersion`. A request that used an alias with fallbacks echoes the target that answered (`CallContext.onServed`). */
+  model: string
   readonly stream: boolean
   /** Name of the forced tool that carries `responseSchema` output; its input becomes the text of the answer. */
   readonly structuredTool?: string

package/src/gemini/route.ts

@@ -16,6 +16,7 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
 import { boundEvents, checkJsonContentType, readJsonBody, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { listAvailableModels, resolveModel } from "../models.js"
 import type { RouteHost } from "../openai/route.js"
@@ -88,7 +89,7 @@ export interface GeminiCall {
   readonly response: ServerResponse
   readonly scope: RequestScope
   /** The route's log fields: the resolved model, and the outcome of a stream that failed after it committed. */
-  readonly info: { model?: string; failed?: string; dropped?: string }
+  readonly info: ServedInfo & { model?: string; failed?: string; dropped?: string }
 }
 
 export async function serveGemini(host: RouteHost, { match, request, url, app, response, scope, info }: GeminiCall): Promise<void> {
@@ -137,6 +138,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
         if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
         response.setHeader(SESSION_HEADER, recordID)
       },
+      onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
     }),
     scope,
   )

package/src/metrics.ts

@@ -112,6 +112,8 @@ export interface Metrics {
   tokens(app: string, usage: PlugUsage): void
   /** Sampling parameters dropped for one request. */
   dropped(params: ReadonlyArray<string>): void
+  /** A model call failed before any output and was retried on the next target of its alias. */
+  fallback(app: string): void
   /** One history sweep ended. */
   sweep(result: "ok" | "failed" | "timeout", removed: number): void
   /** The exposition text. Called from a request that is itself in flight, which is not counted. */
@@ -128,6 +130,7 @@ export function createMetrics(): Metrics {
     ["app", "kind"],
   )
   const dropped = new Counter("plugboard_dropped_params_total", "Sampling parameters dropped because the target model rejects them, by parameter.", ["param"])
+  const fallbacks = new Counter("plugboard_fallbacks_total", "Model calls retried on the next target of an alias after a failure before any output, by app.", ["app"])
   const sweeps = new Counter("plugboard_history_sweeps_total", "History sweeps that ended, by result.", ["result"])
   const removed = new Counter("plugboard_history_sessions_removed_total", "Request sessions removed by history sweeps.", [])
 
@@ -151,6 +154,7 @@ export function createMetrics(): Metrics {
     dropped(params) {
       for (const param of params) dropped.add([param])
     },
+    fallback: (app) => fallbacks.add([app]),
     sweep(result, count) {
       sweeps.add([result])
       removed.add([], count)
@@ -163,6 +167,7 @@ export function createMetrics(): Metrics {
         ...gauge("plugboard_requests_in_flight", "Requests being handled right now, not counting this scrape.", Math.max(0, inFlight - 1)),
         ...tokens.render(),
         ...dropped.render(),
+        ...fallbacks.render(),
         ...sweeps.render(),
         ...removed.render(),
         ...gauge("plugboard_generations", "Accepted plugin generations (one per OpenCode Location) serving requests.", snapshot.generations),

package/src/models.ts

@@ -4,7 +4,7 @@ import type { PlugboardOptions } from "./config.js"
 import type { CatalogModel, ModelRef, PlugError } from "./contract.js"
 
 /** `provider/model[#variant]`. The model id may contain slashes (`openrouter/vendor/model`). */
-function parseModelRef(s: string): ModelRef | undefined {
+export function parseModelRef(s: string): ModelRef | undefined {
   if (typeof s !== "string") return undefined
   const slash = s.indexOf("/")
   if (slash <= 0) return undefined
@@ -16,19 +16,21 @@ function parseModelRef(s: string): ModelRef | undefined {
   return { providerID: s.slice(0, slash), id, ...(variant ? { variant } : {}) }
 }
 
-function refToString(ref: ModelRef): string {
+export function refToString(ref: ModelRef): string {
   return `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
 }
 
 /** `provider/*` any model of the provider; `provider/model` any variant; `provider/model#variant` exactly. */
-function allowed(options: PlugboardOptions, ref: ModelRef): boolean {
-  return options.models.some((pattern) => {
+export function allowedBy(models: ReadonlyArray<string>, ref: ModelRef): boolean {
+  return models.some((pattern) => {
     if (pattern.endsWith("/*")) return pattern.slice(0, -2) === ref.providerID
     const p = parseModelRef(pattern)
     return p !== undefined && p.providerID === ref.providerID && p.id === ref.id && (p.variant === undefined || p.variant === ref.variant)
   })
 }
 
+const allowed = (options: PlugboardOptions, ref: ModelRef): boolean => allowedBy(options.models, ref)
+
 function find(catalog: ReadonlyArray<CatalogModel>, ref: ModelRef): CatalogModel | undefined {
   const model = catalog.find((m) => m.providerID === ref.providerID && m.id === ref.id)
   return model && (ref.variant === undefined || model.variants.includes(ref.variant)) ? model : undefined
@@ -98,3 +100,17 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
   }
   return data
 }
+
+/**
+ * The targets an alias falls back to, in order: the fallbacks that are allowed and enabled on the server.
+ * Empty for a plain model id or an alias without fallbacks. The primary target is `resolveModel`'s answer.
+ */
+export function fallbackRefs(options: PlugboardOptions, alias: string, catalog: ReadonlyArray<CatalogModel>): ModelRef[] {
+  const targets = Object.hasOwn(options.fallbacks, alias) ? options.fallbacks[alias]! : []
+  const refs: ModelRef[] = []
+  for (const target of targets) {
+    const ref = parseModelRef(target)
+    if (ref && allowed(options, ref) && find(catalog, ref)) refs.push(ref)
+  }
+  return refs
+}

package/src/openai/fanout.ts

@@ -22,6 +22,7 @@
 
 import type { ServerResponse } from "node:http"
 import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
 import { RequestAborted, boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
 import type { RouteHost } from "./route.js"
@@ -40,6 +41,8 @@ export interface ChoiceCodec {
   streamChoice(events: AsyncIterable<PlugEvent>, write: (chunk: string) => void, choice: StreamChoice): Promise<StreamResult>
   /** The final chunk with the summed usage (`include_usage`). */
   usageChunk(choice: Omit<StreamChoice, "index">, usage: PlugUsage): object
+  /** Echo the served model of an alias with fallbacks as the response model. Used for a single call only: with several choices the body keeps the requested model. */
+  setModel(model: string): void
 }
 
 /** The Chat Completions encoder as a `ChoiceCodec`. */
@@ -50,6 +53,7 @@ export const chatCodec = (exchange: OpenAiExchange): ChoiceCodec => ({
   collect: (events) => collectCompletion(events, exchange),
   streamChoice: (events, write, choice) => streamCompletion(events, exchange, write, choice),
   usageChunk: (choice, usage) => chatUsageChunk(exchange.model, choice.id, choice.created, usage),
+  setModel: (model) => void (exchange.model = model),
 })
 
 export interface ChoicesCall {
@@ -58,8 +62,8 @@ export interface ChoicesCall {
   readonly calls: ReadonlyArray<PlugRequest>
   readonly response: ServerResponse
   readonly scope: RequestScope
-  /** The route's log fields: the outcome of a stream that failed after it committed. */
-  readonly info: { failed?: string }
+  /** The route's log fields: the outcome of a stream that failed after it committed, and the first served model. */
+  readonly info: ServedInfo & { failed?: string }
   readonly codec: ChoiceCodec
 }
 
@@ -158,6 +162,10 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
   const gscope = groupScope(scope, AbortSignal.any([scope.signal, group.signal]))
   /** History record ids as the callers report them, in choice order, for the response header (comma separated). */
   const records: Array<string | undefined> = []
+  // Headers: the first choice to be served wins. Body model: only a single call echoes the served model.
+  const served = reportServed(response, info, (s) => {
+    if (calls.length === 1) codec.setModel(s.model)
+  })
   const open = (index: number) =>
     boundEvents(
       host.caller.stream(calls[index]!, {
@@ -168,6 +176,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
           records[index] = recordID
           response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
         },
+        onServed: served,
       }),
       gscope,
     )

package/src/openai/response.ts

@@ -14,8 +14,8 @@ type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
  * presentation state. The request decoder produces it; the model call never sees it.
  */
 export interface OpenAiExchange {
-  /** The model string the client sent; echoed in every response object. */
-  readonly model: string
+  /** The model string the client sent; echoed in every response object. A request that used an alias with fallbacks echoes the target that answered (`CallContext.onServed`). */
+  model: string
   readonly stream: boolean
   /** `stream_options.include_usage`: the stream carries a usage field per chunk and a final usage chunk. */
   readonly includeUsage: boolean

package/src/openai/route.ts

@@ -36,6 +36,7 @@ import {
   sseWriter,
   type RequestScope,
 } from "../http.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
 import { encodeGeminiError } from "../gemini/response.js"
 import { geminiAuthorization, matchGeminiRoute, serveGemini } from "../gemini/route.js"
 import { errorMessage, log, logError, withRequestId } from "../log.js"
@@ -96,7 +97,7 @@ const decodeSegment = (raw: string): string => {
 }
 
 /** What a request log line may carry: ids and outcomes only. */
-interface RequestInfo {
+interface RequestInfo extends ServedInfo {
   route: string
   app?: string
   model?: string
@@ -246,6 +247,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           response.setHeader(SESSION_HEADER, recordID)
         },
+        // An alias with fallbacks: report which target answered, and echo it as the response model.
+        onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       }),
       scope,
     )
@@ -328,7 +331,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       metrics?.requestFinished({ app: info.app ?? NO_APP, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
       // Probes and scrapes that succeed are not worth a line each.
       if ((info.route !== "GET /healthz" && info.route !== "GET /metrics") || outcome !== "ok") {
-        const fields = { id, route: info.route, app: info.app, model: info.model, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
+        const fields = { id, route: info.route, app: info.app, model: info.model, served: info.served, fallbacks: info.fallbacks, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
         if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
         else log("request", fields)
       }

package/src/responses/response.ts

@@ -12,8 +12,8 @@ type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
 /** What the encoder needs besides the model events: Responses presentation state. The request decoder produces it. */
 export interface ResponsesExchange {
-  /** The model string the client sent; echoed in every response object. */
-  readonly model: string
+  /** The model string the client sent; echoed in every response object. A request that used an alias with fallbacks echoes the target that answered (`CallContext.onServed`). */
+  model: string
   readonly stream: boolean
   /** Request fields echoed into the response object (instructions, tools, temperature, ...). */
   readonly envelope: Readonly<Record<string, unknown>>

package/src/responses/route.ts

@@ -10,6 +10,7 @@
 
 import type { ServerResponse } from "node:http"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
 import { boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { resolveModel } from "../models.js"
 import { encodeError } from "../openai/response.js"
@@ -25,7 +26,7 @@ export interface ResponsesCall {
   readonly response: ServerResponse
   readonly scope: RequestScope
   /** The route's log fields: the resolved model, and the outcome of a stream that failed after it committed. */
-  readonly info: { model?: string; failed?: string }
+  readonly info: ServedInfo & { model?: string; failed?: string }
 }
 
 export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
@@ -50,6 +51,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
         if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
         response.setHeader(SESSION_HEADER, recordID)
       },
+      onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
     }),
     scope,
   )