opencode-plugboard 0.9.1 → 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.9.1",
+      "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.9.1",
+  "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.",
@@ -19,13 +19,26 @@
   },
   "files": ["index.ts", "src/", "README.md", "LICENSE"],
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test": "bun test",
+    "smoke:pack": "bun .github/scripts/smoke-pack.ts",
     "release": "bun .github/scripts/release.ts"
   },
+  "dependencies": {
+    "escape-html": "1.0.3",
+    "ipaddr.js": "2.5.0",
+    "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/abort.ts

@@ -0,0 +1,26 @@
+/** The one "settle or reject when aborted" helper that request-side code races host calls against. */
+
+/**
+ * Settles with `promise`, or rejects with `signal.reason` as soon as `signal` aborts. The promise
+ * itself keeps running (it cannot be cancelled): it is always observed, so a late rejection after
+ * the race was lost never becomes an unhandled rejection. A signal that is already aborted rejects
+ * at once.
+ */
+export function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  promise.catch(() => {})
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener("abort", onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort)
+        reject(error)
+      },
+    )
+  })
+}

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

@@ -1,6 +1,8 @@
 /** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
 
+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"
 
@@ -13,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
@@ -125,6 +133,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   // Own-property construction: a key such as `__proto__` must stay a key, never reach the prototype.
   const keys: Record<string, string> = Object.fromEntries(keyEntries)
+  digestsOf(keys)
   if (keyEntries.length === 0 && !isLoopbackHost(host))
     throw new Error(`plugboard refuses to listen on non-loopback host \`${host}\` without \`keys\``)
 
@@ -135,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")
@@ -168,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),
@@ -186,20 +206,30 @@ const UNAUTHORIZED: PlugError = {
   code: "invalid_api_key",
 }
 
-function same(a: string, b: string): boolean {
-  let diff = a.length ^ b.length
-  const length = Math.max(a.length, b.length)
-  for (let i = 0; i < length; i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0)
-  return diff === 0
+const sha256 = (text: string): Buffer => createHash("sha256").update(text).digest()
+
+/**
+ * SHA-256 digest of each key, computed once per `keys` object (at parse; lazily for an options
+ * object built without `parseOptions`). Comparing fixed-size digests means a wrong token's length
+ * and content do not change how long the comparison takes.
+ */
+const keyDigests = new WeakMap<object, ReadonlyArray<readonly [string, Buffer]>>()
+
+function digestsOf(keys: Readonly<Record<string, string>>): ReadonlyArray<readonly [string, Buffer]> {
+  let digests = keyDigests.get(keys)
+  if (!digests) keyDigests.set(keys, (digests = Object.entries(keys).map(([name, key]) => [name, sha256(key)] as const)))
+  return digests
 }
 
 /** No keys -> app `default`; with keys every request needs `Authorization: Bearer <key>`. */
 export function authenticate(options: PlugboardOptions, authorization: string | undefined): { app: string } | PlugError {
-  const entries = Object.entries(options.keys)
+  const entries = digestsOf(options.keys)
   if (entries.length === 0) return { app: DEFAULT_APP }
   const token = /^Bearer\s+(\S+)\s*$/i.exec(authorization ?? "")?.[1]
   if (!token) return UNAUTHORIZED
+  const digest = sha256(token)
   let app: string | undefined
-  for (const [name, key] of entries) if (same(token, key)) app = name
+  // Every key is compared, no early exit.
+  for (const [name, expected] of entries) if (timingSafeEqual(digest, expected)) app = name
   return app === undefined ? UNAUTHORIZED : { app }
 }

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

@@ -16,6 +16,7 @@
  */
 
 import type { ServerResponse } from "node:http"
+import escapeText from "escape-html"
 import type { PlugboardOptions } from "./config.js"
 import type { CatalogModel } from "./contract.js"
 import { listAvailableModels } from "./models.js"
@@ -40,8 +41,7 @@ export function sendText(response: ServerResponse, status: number, contentType:
   response.end(body)
 }
 
-const escapeHtml = (value: unknown): string =>
-  String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char)
+const escapeHtml = (value: unknown): string => escapeText(String(value))
 
 /** `http://host:port` for a listen address; an IPv6 literal gets brackets. */
 function origin(listen: PlugboardOptions["listen"]): string {
@@ -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/http.ts

@@ -5,6 +5,7 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
+import { raceAbort } from "./abort.js"
 import { isLoopbackHost, type PlugboardOptions } from "./config.js"
 import type { PlugError, PlugEvent } from "./contract.js"
 
@@ -49,9 +50,9 @@ export interface RequestScope {
 
 /**
  * Establishes cancellation and the deadline. Call before the first `await` of a request: a socket
- * that is already gone aborts immediately, so abandoned work never starts.
+ * that is already gone aborts immediately, so abandoned work never starts. `graceMs` is for tests.
  */
-export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number): RequestScope {
+export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number, graceMs = DEADLINE_GRACE_MS): RequestScope {
   const controller = new AbortController()
   const abort = (kind: RequestAborted["kind"]) => {
     if (!controller.signal.aborted) controller.abort(new RequestAborted(kind))
@@ -68,7 +69,7 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
     graceTimer = setTimeout(() => {
       response.destroy()
       request.socket?.destroy()
-    }, DEADLINE_GRACE_MS)
+    }, graceMs)
     graceTimer.unref?.()
   }
   timer = setTimeout(onDeadline, Math.min(Math.max(timeoutMs, 1), MAX_TIMER_MS))
@@ -98,24 +99,7 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
       code: "timeout",
       message: `Request timed out after ${timeoutMs} ms (option requestTimeoutMs)`,
     },
-    race<T>(promise: Promise<T>): Promise<T> {
-      promise.catch(() => {})
-      if (signal.aborted) return Promise.reject(signal.reason)
-      return new Promise<T>((resolve, reject) => {
-        const onAbort = () => reject(signal.reason)
-        signal.addEventListener("abort", onAbort, { once: true })
-        promise.then(
-          (value) => {
-            signal.removeEventListener("abort", onAbort)
-            resolve(value)
-          },
-          (error) => {
-            signal.removeEventListener("abort", onAbort)
-            reject(error)
-          },
-        )
-      })
-    },
+    race: (promise) => raceAbort(promise, signal),
     dispose,
   }
 }

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>>
@@ -79,10 +79,16 @@ const structuredFailure = (exchange: ResponsesExchange, finish: Exclude<PlugFini
         message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
       }
 
+/**
+ * `committed`: whether the transport already committed a 200 stream before any event was emitted
+ * (the SSE writer does at the first reasoning event, #49). A failure then still opens the response
+ * and ends it with `response.failed`, instead of leaving the client an empty 200 stream.
+ */
 export async function runResponse(
   events: AsyncIterable<PlugEvent>,
   exchange: ResponsesExchange,
   emit: (event: ResponsesStreamEvent) => void,
+  committed: () => boolean = () => false,
 ): Promise<ResponseRun> {
   const id = newId("resp")
   const createdAt = Math.floor(Date.now() / 1000)
@@ -203,14 +209,15 @@ export async function runResponse(
   const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
   failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
   if (failure) {
-    if (!started) return { failure, started }
+    if (!started && !committed()) return { failure, started }
+    start()
     closeMessage()
     const response = envelope("failed", items, {
       error: { code: failure.code ?? failure.kind, message: failure.message },
       ...(usage ? { usage: encodeUsage(usage) } : {}),
     })
     send("response.failed", { response })
-    return { failure, started, response }
+    return { failure, started: true, response }
   }
   start()
   if (held && structuredAnswer) text(args(held.input))

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,13 +51,14 @@ 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,
   )
 
   if (exchange.stream) {
     const sse = sseWriter(response, scope.signal)
-    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)))
+    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
     if (!sse.started && !response.headersSent) {
       if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
     } else {

package/src/runtime.ts

@@ -44,7 +44,10 @@
  */
 
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
+import { setTimeout as delay } from "node:timers/promises"
 import { Cause, Effect, Stream } from "effect"
+import stableStringify from "safe-stable-stringify"
+import { raceAbort } from "./abort.js"
 import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
 import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
 import { createMetrics, type Metrics, type RuntimeSnapshot } from "./metrics.js"
@@ -104,8 +107,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 6
+/** 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 7
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -298,19 +301,9 @@ export function loadServingCatalog(fallback: () => Promise<ReadonlyArray<Catalog
   return (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
 }
 
-/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order. */
+/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order (undefined values are left out, as in `JSON.stringify`). */
 function canonicalJson(value: unknown): string {
-  const canonical = (item: unknown): unknown => {
-    if (Array.isArray(item)) return item.map(canonical)
-    if (typeof item !== "object" || item === null) return item
-    return Object.fromEntries(
-      Object.entries(item)
-        .filter(([, entry]) => entry !== undefined)
-        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-        .map(([key, entry]) => [key, canonical(entry)]),
-    )
-  }
-  return JSON.stringify(canonical(value))
+  return stableStringify(value) ?? ""
 }
 
 const unavailable = (response: ServerResponse, message: string) => {
@@ -512,30 +505,8 @@ export function ensurePump(subscribe: () => Stream.Stream<unknown, unknown, neve
 
 const backendUnavailable = (message: string): PlugError => ({ status: 503, kind: "server", code: "backend_unavailable", message })
 
-/** Rejects when `signal` aborts; the underlying promise is left running (its late result or error is swallowed). */
-function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(new Error("aborted"))
-    if (signal.aborted) return onAbort()
-    signal.addEventListener("abort", onAbort, { once: true })
-    promise.then(
-      (value) => (signal.removeEventListener("abort", onAbort), resolve(value)),
-      (error) => (signal.removeEventListener("abort", onAbort), reject(error)),
-    )
-  })
-}
-
-const sleep = (ms: number, signal: AbortSignal) =>
-  new Promise<void>((resolve) => {
-    if (signal.aborted) return resolve()
-    const timer = setTimeout(done, ms)
-    function done() {
-      clearTimeout(timer)
-      signal.removeEventListener("abort", done)
-      resolve()
-    }
-    signal.addEventListener("abort", done, { once: true })
-  })
+/** Waits `ms`, or until `signal` aborts (which resolves, never rejects). */
+const sleep = (ms: number, signal: AbortSignal): Promise<void> => delay(ms, undefined, { signal }).catch(() => {})
 
 /** Rebuild the transforms of a generation set up before its directory was confirmed; shared by concurrent requests. */
 function activate(generation: Generation): Promise<void> {
@@ -593,7 +564,7 @@ export async function ensureBackend(
         if (!booted) {
           booted = true
           try {
-            await abortable(boot(directory), bounded)
+            await raceAbort(boot(directory), bounded)
           } catch (error) {
             if (bounded.aborted) continue
             logError("backend.boot_failed", { app, error: errorMessage(error) })
@@ -603,7 +574,7 @@ export async function ensureBackend(
         }
       } else {
         try {
-          await abortable(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
+          await raceAbort(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
         } catch (error) {
           if (bounded.aborted) continue
           throw error

package/src/session/caller.ts

@@ -17,6 +17,7 @@
  */
 
 import { randomUUID } from "node:crypto"
+import { raceAbort } from "../abort.js"
 import { APP_NAME_PATTERN, DEFAULT_APP } from "../config.js"
 import { isPlugError, type CallContext, type ModelCaller, type PlugError, type PlugEvent, type PlugRequest } from "../contract.js"
 import { log, logError } from "../log.js"
@@ -72,17 +73,6 @@ function checkPreparation(request: PlugRequest, images: number, maxTools: number
   return undefined
 }
 
-/** Settles with `promise`, or rejects as soon as `signal` aborts. Request side only: the promise itself keeps running. */
-function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
-  promise.catch(() => {}) // a late rejection after the race was lost must not become unhandled
-  if (signal.aborted) return Promise.reject(signal.reason)
-  return new Promise<T>((resolve, reject) => {
-    const onAbort = () => reject(signal.reason)
-    signal.addEventListener("abort", onAbort, { once: true })
-    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort))
-  })
-}
-
 export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
   const { port, sessions, maxTools, ensureBackend } = deps
   const remoteImages = deps.remoteImages ?? false

package/src/session/media.ts

@@ -9,15 +9,17 @@
  * server's own network (#84): the host is resolved first, every address it resolves to must be a
  * public one (loopback, private, link-local, CGNAT, ULA, multicast, reserved and mapped or
  * translated forms of those are refused) unless the operator's `remoteImages.allow` list names the
- * host or the address, and the request then connects to the address that was checked, not to the
- * name, so a second DNS answer cannot redirect it (DNS rebinding). The caller sees one generic
- * error for every fetch failure, whatever the cause.
+ * host or the address, and the request then connects to the addresses that were checked (tried in
+ * order until one accepts), not to the name, so a second DNS answer cannot redirect it (DNS
+ * rebinding). Addresses are classified by ipaddr.js. The caller sees one generic error for every
+ * fetch failure, whatever the cause.
  */
 
 import { lookup } from "node:dns/promises"
 import { request as httpRequest, type IncomingMessage } from "node:http"
 import { request as httpsRequest } from "node:https"
 import { isIP } from "node:net"
+import ipaddr from "ipaddr.js"
 import type { PlugRequest } from "../contract.js"
 import { log } from "../log.js"
 
@@ -49,127 +51,64 @@ export class ImageError extends Error {
 
 // ---- addresses
 
-interface Ip {
-  readonly family: 4 | 6
-  readonly bytes: ReadonlyArray<number>
-}
+type Ip = ipaddr.IPv4 | ipaddr.IPv6
 
-/** Dotted IPv4 or any IPv6 text form (compressed, with an embedded IPv4 tail, with a zone) to bytes. */
+/** Strict dotted IPv4 or any IPv6 text form (compressed, with an embedded IPv4 tail, with a zone). Odd IPv4 spellings (`0x7f.1`) never get here: a URL host is normalized by `new URL` first. */
 function parseIp(text: string): Ip | undefined {
-  const family = isIP(text)
-  if (family === 4) return { family, bytes: text.split(".").map(Number) }
-  if (family !== 6) return undefined
-  let head = text.split("%")[0]!
-  const dot = head.lastIndexOf(".")
-  if (dot !== -1) {
-    const colon = head.lastIndexOf(":")
-    const v4 = head.slice(colon + 1).split(".").map(Number)
-    head = `${head.slice(0, colon + 1)}${((v4[0]! << 8) | v4[1]!).toString(16)}:${((v4[2]! << 8) | v4[3]!).toString(16)}`
-  }
-  const [left = "", right = ""] = head.split("::")
-  const first = left === "" ? [] : left.split(":")
-  const last = head.includes("::") ? (right === "" ? [] : right.split(":")) : []
-  const groups = head.includes("::") ? [...first, ...Array<string>(8 - first.length - last.length).fill("0"), ...last] : head.split(":")
-  const bytes: number[] = []
-  for (const group of groups) {
-    const value = Number.parseInt(group, 16)
-    bytes.push(value >> 8, value & 0xff)
-  }
-  return { family, bytes }
-}
-
-interface Cidr {
-  readonly ip: Ip
-  readonly bits: number
-}
-
-function inCidr(ip: Ip, cidr: Cidr): boolean {
-  if (ip.family !== cidr.ip.family) return false
-  let left = cidr.bits
-  for (let i = 0; left > 0; i++, left -= 8) {
-    const mask = left >= 8 ? 0xff : (0xff << (8 - left)) & 0xff
-    if ((ip.bytes[i]! & mask) !== (cidr.ip.bytes[i]! & mask)) return false
+  if (isIP(text) === 0) return undefined
+  try {
+    return ipaddr.parse(text)
+  } catch {
+    return undefined
   }
-  return true
 }
 
-function parseCidr(text: string): Cidr | undefined {
-  const [address = "", length, extra] = text.split("/")
-  const ip = parseIp(address)
-  if (!ip || extra !== undefined) return undefined
-  const max = ip.family === 4 ? 32 : 128
-  if (length === undefined) return { ip, bits: max }
-  const bits = Number(length)
-  return /^\d{1,3}$/.test(length) && bits <= max ? { ip, bits } : undefined
-}
+/** `address/bits` match; false for another family (ipaddr.js throws on one). */
+const inNet = (ip: Ip, net: Ip, bits: number): boolean => ip.kind() === net.kind() && ip.match(net, bits)
 
-const cidrs = (list: string[]): Cidr[] => list.map((entry) => parseCidr(entry)!)
+const NAT64 = ipaddr.IPv6.parseCIDR("64:ff9b::/96")
+/** `::/96`: unspecified, loopback and the deprecated IPv4-compatible form (`::7f00:1`), which ipaddr.js calls unicast. */
+const IPV4_COMPATIBLE = ipaddr.IPv6.parseCIDR("::/96")
 
-/** IPv4 that is not a public unicast address. */
-const BLOCKED_V4 = cidrs([
-  "0.0.0.0/8", // "this network"
-  "10.0.0.0/8",
-  "100.64.0.0/10", // CGNAT
-  "127.0.0.0/8", // loopback
-  "169.254.0.0/16", // link-local, cloud metadata
-  "172.16.0.0/12",
-  "192.0.0.0/24", // IETF protocol assignments
-  "192.0.2.0/24", // documentation
-  "192.168.0.0/16",
-  "198.18.0.0/15", // benchmarking
-  "198.51.100.0/24", // documentation
-  "203.0.113.0/24", // documentation
-  "224.0.0.0/4", // multicast
-  "240.0.0.0/4", // reserved, broadcast
-])
+const v4From = (high: number, low: number) => new ipaddr.IPv4([high >> 8, high & 0xff, low >> 8, low & 0xff])
 
 /**
- * IPv6 that is not a public unicast address. NAT64 (`64:ff9b::/96`) and 6to4 (`2002::/16`) are
- * not listed: they embed an IPv4 address, which `isPublic` checks as IPv4 (a DNS64 network answers
- * with NAT64 addresses for ordinary public hosts).
+ * A public unicast address. ipaddr.js names the special ranges (loopback, private, link-local, CGNAT,
+ * multicast, reserved and documentation, ULA, Teredo, local-use NAT64, IPv4-mapped, ...); only
+ * `unicast` passes. NAT64 (`64:ff9b::/96`) and 6to4 (`2002::/16`) embed an IPv4 address, which is
+ * checked as IPv4 instead of being refused outright (a DNS64 network answers with NAT64 addresses
+ * for ordinary public hosts). An IPv4-mapped address is never a real answer for a public host.
  */
-const BLOCKED_V6 = cidrs([
-  "::/96", // unspecified, loopback, deprecated IPv4-compatible
-  "::ffff:0:0/96", // IPv4-mapped: never a real answer for a public host
-  "64:ff9b:1::/48", // local-use NAT64
-  "100::/64", // discard
-  "2001::/32", // Teredo
-  "2001:db8::/32", // documentation
-  "fc00::/7", // unique local
-  "fe80::/10", // link-local
-  "fec0::/10", // site-local (deprecated)
-  "ff00::/8", // multicast
-])
-
-/** The IPv4 address embedded in a NAT64 or 6to4 address (or a mapped one), if it is one. */
-function embeddedV4(ip: Ip): Ip | undefined {
-  if (ip.family !== 6) return undefined
-  const b = ip.bytes
-  const mapped = b.slice(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff
-  const nat64 = b[0] === 0 && b[1] === 0x64 && b[2] === 0xff && b[3] === 0x9b && b.slice(4, 12).every((x) => x === 0)
-  if (mapped || nat64) return { family: 4, bytes: b.slice(12, 16) }
-  if (b[0] === 0x20 && b[1] === 0x02) return { family: 4, bytes: b.slice(2, 6) }
-  return undefined
+export function isPublicAddress(text: string): boolean {
+  const ip = parseIp(text)
+  return ip !== undefined && isPublic(ip)
 }
 
 function isPublic(ip: Ip): boolean {
-  const inner = embeddedV4(ip)
-  if (inner && !isPublic(inner)) return false
-  return !(ip.family === 4 ? BLOCKED_V4 : BLOCKED_V6).some((cidr) => inCidr(ip, cidr))
+  if (ip instanceof ipaddr.IPv4) return ip.range() === "unicast"
+  const range = ip.range()
+  const inner = range === "6to4" ? v4From(ip.parts[1]!, ip.parts[2]!) : ip.match(NAT64) ? v4From(ip.parts[6]!, ip.parts[7]!) : undefined
+  if (inner) return isPublic(inner)
+  return range === "unicast" && !ip.match(IPV4_COMPATIBLE)
 }
 
 // ---- allowlist
 
 /** One `remoteImages.allow` entry: a host name (`images.internal`, or `*.internal` for subdomains), an IP address, or a CIDR range. */
-type AllowEntry = { readonly kind: "host"; readonly name: string } | { readonly kind: "net"; readonly cidr: Cidr }
+type AllowEntry = { readonly kind: "host"; readonly name: string } | { readonly kind: "net"; readonly address: Ip; readonly bits: number }
 
 const HOSTNAME = /^(?:\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/
 
 /** Undefined when `entry` is none of the three forms. */
 export function parseAllowEntry(entry: string): AllowEntry | undefined {
   const text = entry.trim().toLowerCase()
-  const cidr = parseCidr(text)
-  if (cidr) return { kind: "net", cidr }
+  const [address = "", length, extra] = text.split("/")
+  const ip = parseIp(address)
+  if (ip && extra === undefined) {
+    const max = ip instanceof ipaddr.IPv4 ? 32 : 128
+    if (length === undefined) return { kind: "net", address: ip, bits: max }
+    if (/^\d{1,3}$/.test(length) && Number(length) <= max) return { kind: "net", address: ip, bits: Number(length) }
+  }
   return HOSTNAME.test(text) && !text.includes("/") ? { kind: "host", name: text } : undefined
 }
 
@@ -190,11 +129,12 @@ function resolveAddresses(host: string, signal: AbortSignal): Promise<string[]>
 }
 
 /**
- * Resolve the URL's host and decide which address to connect to. Every address the name resolves
- * to has to be allowed (a name that answers with one public and one private address is refused),
- * so the pinned one cannot be a surprise. Throws the generic fetch error when anything is refused.
+ * Resolve the URL's host and return the addresses to connect to, in resolver order. Every address
+ * the name resolves to has to be allowed (a name that answers with one public and one private
+ * address is refused), so a pinned one cannot be a surprise. Throws the generic fetch error when
+ * anything is refused.
  */
-async function pickAddress(url: URL, allow: ReadonlyArray<AllowEntry>, signal: AbortSignal): Promise<string> {
+async function checkedAddresses(url: URL, allow: ReadonlyArray<AllowEntry>, signal: AbortSignal): Promise<string[]> {
   const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase()
   const literal = parseIp(host)
   const addresses = literal ? [host] : await resolveAddresses(host, signal)
@@ -202,14 +142,14 @@ async function pickAddress(url: URL, allow: ReadonlyArray<AllowEntry>, signal: A
   const permitted = (address: string): boolean => {
     const ip = parseIp(address)
     if (!ip) return false
-    return nameAllowed || isPublic(ip) || allow.some((entry) => entry.kind === "net" && inCidr(ip, entry.cidr))
+    return nameAllowed || isPublic(ip) || allow.some((entry) => entry.kind === "net" && inNet(ip, entry.address, entry.bits))
   }
   if (addresses.length === 0 || !addresses.every(permitted)) {
     // The log says which kind of refusal, never the host or the URL.
     log("media.remote_refused", { reason: addresses.length === 0 ? "no_address" : "address_not_allowed" })
     throw FETCH_FAILED()
   }
-  return addresses[0]!
+  return addresses
 }
 
 /** GET `url` over a connection to `address` (already checked), keeping the URL's host for `Host` and TLS. No redirects are followed by the caller. */
@@ -239,6 +179,18 @@ function get(url: URL, address: string, signal: AbortSignal): Promise<IncomingMe
   })
 }
 
+/** The first connection that succeeds, trying each checked address in order (#134); only a connection failure moves on, never a response. */
+async function getFirst(url: URL, addresses: ReadonlyArray<string>, signal: AbortSignal): Promise<IncomingMessage> {
+  for (const address of addresses) {
+    try {
+      return await get(url, address, signal)
+    } catch {
+      if (signal.aborted) break
+    }
+  }
+  throw FETCH_FAILED()
+}
+
 // ---- preparation
 
 async function toDataUrl(url: string, signal: AbortSignal, remoteImages: RemoteImages, budget: Budget): Promise<string> {
@@ -260,12 +212,10 @@ async function toDataUrl(url: string, signal: AbortSignal, remoteImages: RemoteI
     throw FETCH_FAILED()
   }
   const allow = typeof remoteImages === "object" ? remoteImages.allow.flatMap((entry) => parseAllowEntry(entry) ?? []) : []
-  const address = await pickAddress(target, allow, bounded).catch((error: unknown) => {
+  const addresses = await checkedAddresses(target, allow, bounded).catch((error: unknown) => {
     throw error instanceof ImageError ? error : FETCH_FAILED()
   })
-  const response = await get(target, address, bounded).catch(() => {
-    throw FETCH_FAILED()
-  })
+  const response = await getFirst(target, addresses, bounded)
   // A redirect is never followed (it could point inside); anything but a plain success is a failed fetch.
   if (response.statusCode === undefined || response.statusCode < 200 || response.statusCode > 299) {
     response.destroy()