opencode-plugboard 0.11.0 → 0.13.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.13.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"
@@ -53,19 +54,26 @@ export default Plugin.define({
         port: createSessionPort(ctx),
         sessions,
         maxTools: options.maxTools,
+        apps: options.apps,
         remoteImages: options.remoteImages,
         // 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,
@@ -95,7 +103,7 @@ export default Plugin.define({
       // ---- the context hook, the agent deny and the seed tools. Ownership of the Location is only
       // known after an asynchronous check (`ensureBackend`), so all three are no-ops until
       // `registration.confirmed()`: in real projects nothing is ever added or rewritten.
-      yield* installSessionHooks(ctx, { maxTools: options.maxTools, sessions, active: registration.confirmed })
+      yield* installSessionHooks(ctx, { maxTools: options.maxTools, apps: options.apps, sessions, active: registration.confirmed })
       registration.ready()
     }),
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.11.0",
+  "version": "0.13.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,27 @@
     "safe-stable-stringify": "2.5.0"
   },
   "devDependencies": {
+    "@ai-sdk/anthropic": "4.0.78",
+    "@ai-sdk/google": "4.0.93",
+    "@ai-sdk/openai": "4.0.91",
+    "@anthropic-ai/sdk": "0.133.0",
+    "@commitlint/cli": "21.2.3",
+    "@commitlint/config-conventional": "21.2.3",
+    "@google/genai": "2.28.0",
     "@opencode/plugin": "2.0.26",
     "@types/bun": "1.4.2",
     "@types/escape-html": "^1.0.4",
+    "@types/lcov-parse": "1.0.2",
     "@types/node": "^26.6.2",
+    "ai": "7.0.137",
+    "conventional-commits-parser": "7.1.3",
     "effect": "4.0.0-rc.112",
+    "eventsource-parser": "4.1.1",
+    "fast-check": "4.10.2",
+    "fast-xml-parser": "5.11.2",
+    "lcov-parse": "1.0.0",
+    "lefthook": "2.2.1",
+    "openai": "7.32.0",
     "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,7 +25,9 @@ import {
   sseWriter,
   type RequestScope,
 } from "../http.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
 import { resolveModel } from "../models.js"
+import { reportPolicy } from "../policy.js"
 import { dropRejected } from "../openai/sampling.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseMessagesRequest } from "./request.js"
@@ -45,7 +47,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 +123,8 @@ 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)),
+        onPolicy: reportPolicy(response),
       }),
       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,18 +2,27 @@
 
 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"
 
 /** Plugin options, after defaults and validation (see `parseOptions`). */
 export interface PlugboardOptions {
   readonly listen: { readonly host: string; readonly port: number }
-  /** App name -> API key. App names match APP_NAME_PATTERN; "default" is reserved. */
+  /** App name -> API key, from `keys` and `apps.<name>.key` merged. App names match APP_NAME_PATTERN; "default" is reserved. */
   readonly keys: Readonly<Record<string, string>>
+  /** Per-app policy (`apps`); only apps that set a policy field appear. Look one up with `appPolicy`. */
+  readonly apps: Readonly<Record<string, AppPolicy>>
   /** Allowlist: exact `provider/model`, `provider/model#variant`, or `provider/*` patterns. Empty = nothing allowed. */
   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
@@ -35,6 +44,23 @@ export interface PlugboardOptions {
   readonly metrics: boolean
 }
 
+export type SystemMode = "prepend" | "append" | "replace"
+
+/**
+ * What the operator fixes for one app, whatever the caller sends (option `apps`). `models` only narrows the
+ * global allowlist: entries are `provider/model[#variant]`, `provider/*` or alias names.
+ */
+export interface AppPolicy {
+  readonly models?: ReadonlyArray<string>
+  /** Text added to the caller's system prompt, or replacing it (`systemMode`). */
+  readonly system?: string
+  readonly systemMode: SystemMode
+  /** false: the caller's tools are dropped before the model sees them. */
+  readonly tools: boolean
+  /** Lowers the global `maxTools` for this app. */
+  readonly maxTools?: number
+}
+
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
 export const DEFAULT_APP = "default"
 const DEFAULTS = {
@@ -45,7 +71,7 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics"])
+const KNOWN = new Set(["listen", "keys", "apps", "models", "aliases", "maxTools", "maxN", "requestTimeoutMs", "remoteImages", "history", "dropUnsupportedParams", "logFormat", "metrics"])
 const HISTORY_KNOWN = new Set(["maxSessions", "maxAgeDays"])
 /** About 100 years: keeps `maxAgeDays * 86_400_000` a safe integer. */
 const MAX_AGE_DAYS = 36_500
@@ -95,6 +121,75 @@ function parseRemoteImages(value: unknown): RemoteImages {
   return { allow: allow as string[] }
 }
 
+/**
+ * `keys` and the `key` of each `apps` entry as one list. An app named in both must carry the same
+ * value: two sources that disagree are a config mistake, not a precedence rule. Values are validated
+ * by the caller of this function (non-empty strings, unique).
+ */
+function mergedKeys(keys: unknown, apps: unknown): Array<[string, unknown]> {
+  const merged = new Map<string, unknown>(Object.entries(isRecord(keys) ? keys : {}))
+  for (const [app, policy] of Object.entries(isRecord(apps) ? apps : {})) {
+    if (!isRecord(policy) || policy.key === undefined) continue
+    if (merged.has(app) && merged.get(app) !== policy.key)
+      throw new Error(`plugboard app \`${app}\` has a different key in \`keys\` and in \`apps.${app}.key\`; set it in one place or make them equal`)
+    merged.set(app, policy.key)
+  }
+  return [...merged]
+}
+
+const APP_KNOWN = new Set(["key", "models", "system", "systemMode", "tools", "maxTools"])
+const SYSTEM_MODES: ReadonlySet<string> = new Set(["prepend", "append", "replace"])
+
+/** Validates `apps` (the `key` field was merged into `keys` already) into per-app policies. */
+function parseApps(
+  raw: unknown,
+  context: { keys: Readonly<Record<string, string>>; aliases: Readonly<Record<string, string>>; maxTools: number },
+): Record<string, AppPolicy> {
+  const entries: Array<[string, AppPolicy]> = []
+  for (const [app, value] of Object.entries(isRecord(raw) ? raw : {})) {
+    const at = `plugboard \`apps.${app}\``
+    if (app !== DEFAULT_APP && !APP_NAME_PATTERN.test(app)) throw new Error(`plugboard app name \`${app}\` must match ${APP_NAME_PATTERN} (or be \`${DEFAULT_APP}\`)`)
+    if (!isRecord(value)) throw new Error(`${at} must be an object`)
+    for (const field of Object.keys(value))
+      if (!APP_KNOWN.has(field)) throw new Error(`Unknown plugboard option \`apps.${app}.${field}\` (known: ${[...APP_KNOWN].join(", ")})`)
+    const keyed = Object.keys(context.keys).length > 0
+    if (app === DEFAULT_APP && (keyed || value.key !== undefined))
+      throw new Error(`${at} configures the keyless app and cannot be used together with \`keys\`; name the app and give it a key instead`)
+    if (app !== DEFAULT_APP && !Object.hasOwn(context.keys, app)) throw new Error(`${at} has no key: add \`key\` there or an entry in \`keys\``)
+
+    if (value.models !== undefined) {
+      if (!Array.isArray(value.models) || value.models.length === 0)
+        throw new Error(`${at}.models must be a non-empty array (omit it to inherit the global \`models\`)`)
+      for (const entry of value.models)
+        if (typeof entry !== "string" || !(MODEL_PATTERN.test(entry) || Object.hasOwn(context.aliases, entry)))
+          throw new Error(`${at}.models entry \`${String(entry)}\` must be \`provider/model\`, \`provider/model#variant\`, \`provider/*\` or an alias name`)
+    }
+    if (value.system !== undefined && (typeof value.system !== "string" || value.system.trim().length === 0))
+      throw new Error(`${at}.system must be a non-empty string`)
+    if (value.systemMode !== undefined && (typeof value.systemMode !== "string" || !SYSTEM_MODES.has(value.systemMode)))
+      throw new Error(`${at}.systemMode must be \`prepend\`, \`append\` or \`replace\``)
+    if (value.systemMode !== undefined && value.system === undefined) throw new Error(`${at}.systemMode needs \`system\``)
+    if (value.tools !== undefined && typeof value.tools !== "boolean") throw new Error(`${at}.tools must be a boolean`)
+    const maxTools = value.maxTools === undefined ? undefined : positiveInt(value.maxTools, `apps.${app}.maxTools`, 0, context.maxTools)
+
+    const policy: AppPolicy = {
+      ...(value.models === undefined ? {} : { models: value.models as string[] }),
+      ...(value.system === undefined ? {} : { system: value.system as string }),
+      systemMode: (value.systemMode as SystemMode | undefined) ?? "prepend",
+      tools: value.tools !== false,
+      ...(maxTools === undefined ? {} : { maxTools }),
+    }
+    // An app that only carries a key has no policy to look up.
+    if (value.models !== undefined || value.system !== undefined || value.tools !== undefined || maxTools !== undefined) entries.push([app, policy])
+  }
+  return Object.fromEntries(entries)
+}
+
+/** The policy configured for `app` (`default` for the keyless app), if any. Own-property lookup: an app name never reaches the prototype. */
+export function appPolicy(options: Pick<PlugboardOptions, "apps">, app: string): AppPolicy | undefined {
+  return Object.hasOwn(options.apps, app) ? options.apps[app] : undefined
+}
+
 /** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
 export function parseOptions(raw: unknown): PlugboardOptions {
   if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
@@ -112,8 +207,9 @@ export function parseOptions(raw: unknown): PlugboardOptions {
 
   const keyEntries: Array<[string, string]> = []
   if (input.keys !== undefined && !isRecord(input.keys)) throw new Error("plugboard option `keys` must be an object of app name -> key")
+  if (input.apps !== undefined && !isRecord(input.apps)) throw new Error("plugboard option `apps` must be an object of app name -> policy")
   const appOfKey = new Map<string, string>()
-  for (const [app, key] of Object.entries(input.keys ?? {})) {
+  for (const [app, key] of mergedKeys(input.keys, input.apps)) {
     if (app === DEFAULT_APP) throw new Error(`plugboard key name \`${DEFAULT_APP}\` is reserved for keyless loopback use`)
     if (!APP_NAME_PATTERN.test(app)) throw new Error(`plugboard key name \`${app}\` must match ${APP_NAME_PATTERN}`)
     if (typeof key !== "string" || key.length === 0)
@@ -137,18 +233,31 @@ 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 maxTools = positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024)
+  const apps = parseApps(input.apps, { keys, aliases, maxTools })
 
   const remoteImages = parseRemoteImages(input.remoteImages)
   if (input.dropUnsupportedParams !== undefined && typeof input.dropUnsupportedParams !== "boolean")
@@ -168,9 +277,11 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   return {
     listen: { host, port: port ?? DEFAULTS.port },
     keys,
+    apps,
     models: models as string[],
     aliases,
-    maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
+    fallbacks,
+    maxTools,
     maxN: positiveInt(input.maxN, "maxN", DEFAULTS.maxN, 64),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
     remoteImages,

package/src/contract.ts

@@ -161,6 +161,9 @@ export const isPlugError = (value: unknown): value is PlugError =>
 
 // ---------------------------------------------------------------- caller
 
+/** What an app's policy (option `apps`) changed in a request in a way the caller should be told about. */
+export type PolicyNote = "tools-stripped"
+
 export interface CallContext {
   /** App name (key name, or the default app). Decides the history directory. */
   readonly app: string
@@ -168,6 +171,21 @@ 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
+  /** Called once, before the first event, with each change the app's policy made that the caller sent for. Front-ends report them in the `x-plugboard-policy` header. */
+  readonly onPolicy?: (notes: ReadonlyArray<PolicyNote>) => 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
@@ -134,7 +136,7 @@ export function buildDiscovery({ options, app, catalog }: DiscoveryInput): Disco
   const detail = !keyed || app !== undefined
   const auth = keyed ? ({ required: true, scheme: "Bearer" } as const) : { required: false }
 
-  const listed = detail && catalog ? listAvailableModels(options, catalog) : []
+  const listed = detail && catalog ? listAvailableModels(options, catalog, app) : []
   const summary = detail && catalog ? summarize(catalog) : undefined
   const suggested = summary?.providers.map((provider) => `${provider.id}/*`)
 
@@ -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)}`)}`)
@@ -274,7 +277,7 @@ export function buildStatus(input: {
     servingConfirmed: runtime.servingConfirmed,
     eventPump: { running: runtime.pumpRunning },
     sessionGuards: runtime.guards,
-    models: catalog ? { catalog: catalog.length, available: listAvailableModels(options, catalog).length } : { error: "catalog_unavailable" },
+    models: catalog ? { catalog: catalog.length, available: listAvailableModels(options, catalog, app).length } : { error: "catalog_unavailable" },
     metrics: options.metrics,
   }
 }

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, context.app)
+      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, app: string): Promise<ModelRef[]> {
+  try {
+    return fallbackRefs(deps.options, request.model, await deps.loadCatalog(), app)
+  } 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,8 +16,10 @@
 
 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 { reportPolicy } from "../policy.js"
 import type { RouteHost } from "../openai/route.js"
 import { dropRejected } from "../openai/sampling.js"
 import { parseGeminiRequest } from "./request.js"
@@ -88,7 +90,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> {
@@ -98,7 +100,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
     return fail({ status: 404, kind: "not_found", code: "method_not_supported", message: `Method ${match.verb} is not supported; plugboard serves generateContent and streamGenerateContent` })
 
   if (match.op === "list" || match.op === "get") {
-    const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
+    const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()), app)
     if (match.op === "list") return sendJson(response, 200, encodeGeminiModelList(listed))
     const item = listed.find((m) => m.id === match.model)
     if (!item) return fail({ status: 404, kind: "not_found", code: "model_not_found", param: "model", message: `Model ${match.model} is not available` })
@@ -137,6 +139,8 @@ 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)),
+      onPolicy: reportPolicy(response),
     }),
     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

@@ -1,10 +1,10 @@
 /** Model refs and the allowlist/alias policy over a neutral catalog. Protocol-neutral: front-ends format the results. */
 
-import type { PlugboardOptions } from "./config.js"
+import { appPolicy, type AppPolicy, 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,37 @@ 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)
+
+/**
+ * Per-app narrowing (`apps.<name>.models`), applied on top of the global allowlist, never instead of it.
+ * `name` is what the caller sent (an alias or a model id). An entry that is an alias name admits that
+ * name; a pattern entry admits every resolved model it matches, whichever name reached it. No `models`
+ * on the app means no narrowing. Alias names never match as patterns: they are not `provider/model` shaped.
+ */
+function inAppScope(policy: AppPolicy | undefined, name: string, ref: ModelRef): boolean {
+  return policy?.models === undefined || policy.models.includes(name) || allowedBy(policy.models, ref)
+}
+
+/** 404 `model_not_found` when `app` may not use the (already resolved) model; the same error as an unknown model. */
+export function checkAppModel(policy: AppPolicy | undefined, name: string, ref: ModelRef): PlugError | undefined {
+  if (inAppScope(policy, name, ref)) return undefined
+  return { status: 404, message: `Model ${name} is not available`, kind: "not_found", code: "model_not_found", param: "model" }
+}
+
 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
@@ -76,8 +94,12 @@ export interface ListedModel {
   readonly model: CatalogModel
 }
 
-/** The allowlist intersected with the catalog, plus aliases whose target qualifies. Ids are unique except an alias may repeat one. */
-export function listAvailableModels(options: PlugboardOptions, catalog: ReadonlyArray<CatalogModel>): ListedModel[] {
+/**
+ * The allowlist intersected with the catalog, plus aliases whose target qualifies. Ids are unique except an alias may repeat one.
+ * With `app`, the list is narrowed to that app's `models` (see `inAppScope`).
+ */
+export function listAvailableModels(options: PlugboardOptions, catalog: ReadonlyArray<CatalogModel>, app?: string): ListedModel[] {
+  const policy = app === undefined ? undefined : appPolicy(options, app)
   const entry = (id: string, ref: ModelRef, model: CatalogModel): ListedModel => ({ id, ref, model })
   const data: ListedModel[] = []
   // The catalog can list a model more than once (and repeat variants); ids must be unique.
@@ -86,15 +108,31 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
     const base = { providerID: model.providerID, id: model.id }
     for (const ref of [base, ...model.variants.map((variant) => ({ ...base, variant }))]) {
       const id = refToString(ref)
-      if (seen.has(id) || !allowed(options, ref)) continue
+      if (seen.has(id) || !allowed(options, ref) || !inAppScope(policy, id, ref)) continue
       seen.add(id)
       data.push(entry(id, ref, model))
     }
   }
   for (const [alias, target] of Object.entries(options.aliases)) {
     const ref = parseModelRef(target)
-    const model = ref && allowed(options, ref) ? find(catalog, ref) : undefined
+    const model = ref && allowed(options, ref) && inAppScope(policy, alias, ref) ? find(catalog, ref) : undefined
     if (ref && model) data.push(entry(alias, ref, model))
   }
   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.
+ * With `app`, a target outside that app's `models` is skipped (an app scoped to the alias name admits every target).
+ */
+export function fallbackRefs(options: PlugboardOptions, alias: string, catalog: ReadonlyArray<CatalogModel>, app?: string): ModelRef[] {
+  const policy = app === undefined ? undefined : appPolicy(options, app)
+  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) && inAppScope(policy, alias, ref) && find(catalog, ref)) refs.push(ref)
+  }
+  return refs
+}

package/src/openai/fanout.ts

@@ -22,6 +22,8 @@
 
 import type { ServerResponse } from "node:http"
 import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.js"
+import { reportServed, type ServedInfo } from "../fallback.js"
+import { reportPolicy } from "../policy.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 +42,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 +54,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 +63,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 +163,11 @@ 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 policy = reportPolicy(response)
   const open = (index: number) =>
     boundEvents(
       host.caller.stream(calls[index]!, {
@@ -168,6 +178,8 @@ 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,
+        onPolicy: policy,
       }),
       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,11 +36,13 @@ 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"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
+import { reportPolicy } from "../policy.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
@@ -96,7 +98,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
@@ -195,7 +197,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     }
 
     if (route === "GET /v1/models" || modelId !== undefined) {
-      const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
+      const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()), auth.app)
       if (modelId === undefined) return sendJson(response, 200, encodeModelList(listed))
       const item = listed.find((m) => m.id === modelId)
       if (!item) {
@@ -246,6 +248,9 @@ 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)),
+        onPolicy: reportPolicy(response),
       }),
       scope,
     )
@@ -328,7 +333,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/policy.ts

@@ -0,0 +1,17 @@
+/** The response side of per-app policy (option `apps`): what a route tells the caller about changes the policy made. */
+
+import type { ServerResponse } from "node:http"
+import type { PolicyNote } from "./contract.js"
+
+export const POLICY_HEADER = "x-plugboard-policy"
+
+/**
+ * The `CallContext.onPolicy` of a route: `x-plugboard-policy` (the notes, comma separated) while the
+ * headers are still open. The first writer wins, so several choices of one request report once.
+ */
+export function reportPolicy(response: ServerResponse): (notes: ReadonlyArray<PolicyNote>) => void {
+  return (notes) => {
+    if (notes.length === 0 || response.headersSent || response.destroyed || response.hasHeader(POLICY_HEADER)) return
+    response.setHeader(POLICY_HEADER, notes.join(","))
+  }
+}

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,8 +10,10 @@
 
 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 { reportPolicy } from "../policy.js"
 import { encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseResponsesRequest } from "./request.js"
@@ -25,7 +27,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 +52,8 @@ 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)),
+      onPolicy: reportPolicy(response),
     }),
     scope,
   )

package/src/session/caller.ts

@@ -18,9 +18,10 @@
 
 import { randomUUID } from "node:crypto"
 import { raceAbort } from "../abort.js"
-import { APP_NAME_PATTERN, DEFAULT_APP } from "../config.js"
+import { APP_NAME_PATTERN, DEFAULT_APP, appPolicy, type AppPolicy, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CallContext, type ModelCaller, type PlugError, type PlugEvent, type PlugRequest } from "../contract.js"
 import { log, logError } from "../log.js"
+import { checkAppModel } from "../models.js"
 import { RequestCollector } from "./events.js"
 import { ensureAppDir, makeTitle, renderTranscript } from "./history.js"
 import { describeError, type SessionPort } from "./host.js"
@@ -34,6 +35,8 @@ export interface SessionCallerDeps {
   readonly sessions: SessionStore
   /** The seed pool size of the app directories (option `maxTools`); a request needing more tools fails before dispatch. */
   readonly maxTools: number
+  /** Per-app policy (option `apps`): model scope, tools off, a lower tool cap. The system prompt part is applied by the context hook. */
+  readonly apps?: PlugboardOptions["apps"]
   /** Allow fetching http(s) image URLs (option `remoteImages`: off, public addresses only, or with an allowlist). */
   readonly remoteImages?: RemoteImages
   /**
@@ -73,12 +76,36 @@ function checkPreparation(request: PlugRequest, images: number, maxTools: number
   return undefined
 }
 
+/**
+ * The app's tool policy applied to the request: `tools: false` drops every tool (and a tool choice that
+ * would refer to them). Returns the request the session is built from, and whether anything was dropped.
+ * Note that a `response_format` of `json_schema` is answered through a tool, so it is dropped too.
+ */
+function applyToolPolicy(request: PlugRequest, policy: AppPolicy | undefined): { request: PlugRequest; stripped: boolean } {
+  if (policy?.tools !== false) return { request, stripped: false }
+  const { toolChoice: _dropped, ...rest } = request
+  return { request: { ...rest, tools: [] }, stripped: request.tools.length > 0 }
+}
+
+/** An app's own `maxTools`, checked on top of the global one (which `checkPreparation` and the request decoders enforce). */
+function checkAppTools(request: PlugRequest, app: string, policy: AppPolicy | undefined): PlugError | undefined {
+  const max = policy?.maxTools
+  if (max === undefined || request.tools.length <= max) return undefined
+  return {
+    status: 400,
+    kind: "invalid_request",
+    code: "too_many_tools",
+    param: "tools",
+    message: `Request has ${request.tools.length} tools; app ${app} allows ${max} (option \`apps.${app}.maxTools\`)`,
+  }
+}
 export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
   const { port, sessions, maxTools, ensureBackend } = deps
+  const apps = deps.apps ?? {}
   const remoteImages = deps.remoteImages ?? false
 
   return {
-    async *stream(request: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
+    async *stream(called: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
       const app = APP_NAME_PATTERN.test(context.app) || context.app === DEFAULT_APP ? context.app : undefined
       if (!app) return yield failure(400, `Invalid app name: ${context.app}`, "invalid_app")
       if (context.signal.aborted) return
@@ -92,6 +119,21 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
         return event
       }
 
+      // The app's policy: model scope first (a model outside it is as unknown as one off the allowlist), then tools.
+      const policy = appPolicy({ apps }, app)
+      const outOfScope = checkAppModel(policy, called.model, called.ref)
+      if (outOfScope) return yield note({ type: "error", error: outOfScope })
+      const { request, stripped } = applyToolPolicy(called, policy)
+      const tooMany = checkAppTools(request, app, policy)
+      if (tooMany) return yield note({ type: "error", error: tooMany })
+      if (stripped) {
+        try {
+          context.onPolicy?.(["tools-stripped"])
+        } catch (error) {
+          logError("request.on_policy_failed", { app, error: describeError(error) })
+        }
+      }
+
       let sessionID: string | undefined
       let collector: RequestCollector | undefined
       let promptStarted = false

package/src/session/context.ts

@@ -8,6 +8,7 @@
  */
 
 import { Effect } from "effect"
+import { appPolicy, type AppPolicy, type PlugboardOptions } from "../config.js"
 import type { PlugError, PlugMessage, PlugRequest } from "../contract.js"
 import type { ContextHookEvent, HostContext, HostPart, HostToolDescriptor } from "./host.js"
 import { SEED_PREFIX, SEED_RESULT, seedToolsFor } from "./seeds.js"
@@ -80,13 +81,29 @@ function remapSeedTools(session: ContextHookEvent, request: PlugRequest): number
   return tools.length - next.size
 }
 
+/**
+ * The caller's system prompts with the app's `system` applied: before them (default), after them, or
+ * instead of them (`replace` also drops instructions the front-end put there, such as the JSON-mode one).
+ */
+function systemFor(caller: ReadonlyArray<string>, policy: AppPolicy | undefined): ReadonlyArray<string> {
+  if (policy?.system === undefined) return caller
+  switch (policy.systemMode) {
+    case "prepend":
+      return [policy.system, ...caller]
+    case "append":
+      return [...caller, policy.system]
+    case "replace":
+      return [policy.system]
+  }
+}
+
 const preparationFailed = (message: string): PlugError => ({ status: 500, kind: "server", code: "backend_preparation_failed", message })
 
 /**
  * `session.hook("context")` body: swap the request session's system, messages, tools and
- * generation options for the caller's.
+ * generation options for the caller's, with the app's system prompt (option `apps`) applied.
  */
-function applyContext(event: unknown, sessions: SessionStore): void {
+function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOptions["apps"]): void {
   // Assumed invariant: the host passes its mutable `SessionContext` (checked structurally by `HostContextMatches`).
   const session = event as ContextHookEvent
   const state = sessions.lookup(String(session.sessionID))
@@ -106,7 +123,7 @@ function applyContext(event: unknown, sessions: SessionStore): void {
     return text("[image unavailable]")
   }
 
-  const system = request.system.map(text)
+  const system = systemFor(request.system, appPolicy({ apps }, state.app)).map(text)
   // The OpenCode session API has no tool-choice control, so a forced or required tool is steered by instruction.
   const choice = request.toolChoice
   if (choice === "required") system.push(text("You must respond by calling one of the provided tools."))
@@ -144,11 +161,11 @@ function applyContext(event: unknown, sessions: SessionStore): void {
  */
 export function installSessionHooks(
   ctx: HostContext,
-  options: { readonly maxTools: number; readonly sessions: SessionStore; readonly active: () => boolean },
+  options: { readonly maxTools: number; readonly sessions: SessionStore; readonly active: () => boolean; readonly apps?: PlugboardOptions["apps"] },
 ) {
   return Effect.gen(function* () {
     // Swap in the caller's system/messages/tools for plugboard request sessions only.
-    yield* ctx.session.hook("context", (event) => Effect.sync(() => (options.active() ? applyContext(event, options.sessions) : undefined)))
+    yield* ctx.session.hook("context", (event) => Effect.sync(() => (options.active() ? applyContext(event, options.sessions, options.apps ?? {}) : undefined)))
 
     yield* ctx.agent.transform((editor) => {
       if (!options.active()) return