opencode-plugboard 0.12.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.12.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

@@ -54,6 +54,7 @@ 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),
@@ -102,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.12.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,15 +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/route.ts

@@ -27,6 +27,7 @@ import {
 } 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"
@@ -123,6 +124,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
           response.setHeader(SESSION_HEADER, recordID)
         },
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
+        onPolicy: reportPolicy(response),
       }),
       scope,
     )

package/src/config.ts

@@ -9,8 +9,10 @@ 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. */
@@ -42,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 = {
@@ -52,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
@@ -102,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")
@@ -119,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)
@@ -167,6 +256,9 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   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")
     throw new Error("plugboard option `dropUnsupportedParams` must be a boolean")
@@ -185,10 +277,11 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   return {
     listen: { host, port: port ?? DEFAULTS.port },
     keys,
+    apps,
     models: models as string[],
     aliases,
     fallbacks,
-    maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
+    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
@@ -175,6 +178,8 @@ export interface CallContext {
    * 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. */

package/src/discovery.ts

@@ -136,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}/*`)
 
@@ -277,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

@@ -110,7 +110,7 @@ async function* chain(inner: ModelCaller, deps: FallbackDeps, request: PlugReque
     if (context.signal.aborted) reason = undefined
 
     if (reason !== undefined) {
-      rest ??= await resolveRest(deps, request)
+      rest ??= await resolveRest(deps, request, context.app)
       const target = rest[attempt]
       if (target) {
         if (!thrown) await close(iterator)
@@ -145,9 +145,9 @@ function retarget(options: PlugboardOptions, request: PlugRequest, ref: ModelRef
 }
 
 /** 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[]> {
+async function resolveRest(deps: FallbackDeps, request: PlugRequest, app: string): Promise<ModelRef[]> {
   try {
-    return fallbackRefs(deps.options, request.model, await deps.loadCatalog())
+    return fallbackRefs(deps.options, request.model, await deps.loadCatalog(), app)
   } catch {
     return []
   }

package/src/gemini/route.ts

@@ -19,6 +19,7 @@ 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"
@@ -99,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` })
@@ -139,6 +140,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
         response.setHeader(SESSION_HEADER, recordID)
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
+      onPolicy: reportPolicy(response),
     }),
     scope,
   )

package/src/models.ts

@@ -1,6 +1,6 @@
 /** 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`). */
@@ -31,6 +31,22 @@ export function allowedBy(models: ReadonlyArray<string>, ref: ModelRef): boolean
 
 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
@@ -78,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.
@@ -88,14 +108,14 @@ 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
@@ -104,13 +124,15 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
 /**
  * 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>): ModelRef[] {
+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) && find(catalog, ref)) refs.push(ref)
+    if (ref && allowed(options, ref) && inAppScope(policy, alias, ref) && find(catalog, ref)) refs.push(ref)
   }
   return refs
 }

package/src/openai/fanout.ts

@@ -23,6 +23,7 @@
 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"
@@ -166,6 +167,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
   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]!, {
@@ -177,6 +179,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
           response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
         },
         onServed: served,
+        onPolicy: policy,
       }),
       gscope,
     )

package/src/openai/route.ts

@@ -42,6 +42,7 @@ import { geminiAuthorization, matchGeminiRoute, serveGemini } from "../gemini/ro
 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"
@@ -196,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) {
@@ -249,6 +250,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
         },
         // 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,
     )

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/route.ts

@@ -13,6 +13,7 @@ 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"
@@ -52,6 +53,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
         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