zuplo 7.6.7 → 7.6.9

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -35,6 +35,11 @@ the AI Gateway.
 ```
 ANTHROPIC_AUTH_TOKEN=<your-ai-gateway-app-api-key>
 ANTHROPIC_BASE_URL=https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e
+ANTHROPIC_MODEL=anthropic/claude-sonnet-5
+ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
+ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-5
+ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-5
+ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4-5
 ```
 
 ### Using settings.json
@@ -43,7 +48,12 @@ ANTHROPIC_BASE_URL=https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d28
 {
   "env": {
     "ANTHROPIC_AUTH_TOKEN": "<your-ai-gateway-app-api-key>",
-    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e"
+    "ANTHROPIC_BASE_URL": "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e",
+    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4-5",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4-5"
   }
 }
 ```
@@ -58,16 +68,47 @@ Claude Code appends `/v1/messages` to the base URL itself, so
 Restart Claude and it will switch to using your new AI Gateway configuration and
 all your Claude Code LLM requests will route through the AI Gateway.
 
-### Choosing a model
-
-The gateway routes models named as `providerName/model`, where `providerName` is
-the provider name configured in your gateway. Claude Code's default model names
-don't carry that prefix, so set the model explicitly:
+### Model names include your provider's name
+
+The gateway routes every request by a model reference of the form
+`providerName/model`, where `providerName` is the name of the provider **you
+configured** in your gateway — not a fixed vendor id. A single gateway can
+contain several providers that serve Anthropic models — Anthropic itself, Google
+Vertex AI, AWS Bedrock, or multiple keyed instances of the same vendor — so the
+gateway never guesses a provider for a bare model name like `claude-sonnet-5`.
+
+The examples on this page assume the provider is named `anthropic`. Use the name
+of your own provider: a provider named `my-anthropic` routes
+`my-anthropic/claude-sonnet-5`, and a Bedrock provider named `bedrock` routes
+`bedrock/anthropic.claude-sonnet-5` (the model part is always the id the
+provider itself understands).
+
+The model ids in these examples reflect what was current when this page was
+written, and ids differ across providers — a Bedrock provider serves different
+ids than Anthropic directly, and availability can vary by region. Check
+[your provider's page](../managing-providers.mdx) in the portal for the models
+it currently serves, and use those ids.
+
+None of Claude Code's built-in model names carry a provider prefix, so each of
+the model variables above must be set to a prefixed reference:
+
+- `ANTHROPIC_MODEL` — the main model. Required: without it Claude Code sends its
+  built-in default model unprefixed and the first request fails.
+- `ANTHROPIC_SMALL_FAST_MODEL` — the model for background tasks.
+- `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
+  `ANTHROPIC_DEFAULT_HAIKU_MODEL` — what the `opus`/`sonnet`/`haiku` aliases
+  resolve to, so `claude --model opus` and `/model sonnet` keep working.
+
+:::caution{title='HTTP 400: model must use "providerName/model"'}
+
+If Claude Code fails immediately with
+`The request body model must use "providerName/model"`, the request carried a
+model name without a provider prefix. The tier alias variables
+(`ANTHROPIC_DEFAULT_*_MODEL`) alone don't prevent this — they don't cover Claude
+Code's built-in default model. Always set `ANTHROPIC_MODEL` to a prefixed model
+reference.
 
-```
-ANTHROPIC_MODEL=anthropic/claude-sonnet-4-5-20250929
-ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-haiku-4-5
-```
+:::
 
 The app's
 [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)

package/docs/ai-gateway/usage-limits.mdx

@@ -118,13 +118,13 @@ at $80, block at $100. The warn amount has to be the lower of the two.
 The **Overview** tab charts daily and monthly usage only. Hourly and weekly rows
 are enforced, but no meter on that tab tracks them.
 
-:::note
+:::note{title="Budget rule periods follow the UTC calendar"}
 
-Periods are anchored to your gateway, not the calendar. Every period rolls over
-relative to the time (UTC) the gateway was created, so a daily period resets at
-that hour rather than at midnight, and a monthly one on that day of the month.
-Teams and apps created later use the same anchor. Changing a limit mid-period
-doesn't reset the period's usage.
+Hourly periods reset at the top of each hour, daily at 00:00 UTC, weekly on
+Monday at 00:00 UTC, and monthly on the first of the month. A rule added
+mid-period gets the full allowance for the rest of that period—the limit isn't
+prorated—and resets at the next boundary. Changing a limit mid-period doesn't
+reset the period's usage. Custom anchors aren't configurable.
 
 :::
 
@@ -184,6 +184,56 @@ App rules are stored in `options.budgetRules` on the app's own Budgets and Costs
 policy entry. For the app rule schema, see the
 [Budgets and Costs policy reference](../policies/ai-gateway-metering-v2-inbound.mdx).
 
+This rule set budgets each user, each organization, and the app as a whole:
+
+```json
+{
+  "budgetRules": [
+    {
+      "budgetBy": "expression",
+      "expression": "request.headers.get(\"x-user\")",
+      "meters": [
+        {
+          "meter": "tokens",
+          "period": "hourly",
+          "value": 20000,
+          "action": "block"
+        }
+      ]
+    },
+    {
+      "budgetBy": "expression",
+      "expression": "request.headers.get(\"x-organization\")",
+      "meters": [
+        { "meter": "cost", "period": "daily", "value": 50, "action": "block" }
+      ]
+    },
+    {
+      "budgetBy": "app",
+      "meters": [
+        {
+          "meter": "cost",
+          "period": "monthly",
+          "value": 2000,
+          "action": "warn"
+        },
+        {
+          "meter": "cost",
+          "period": "monthly",
+          "value": 2500,
+          "action": "block"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Every distinct `x-user` value gets its own 20,000 tokens per hour, resetting at
+the top of the hour. Every distinct `x-organization` value gets its own $50 per
+day, resetting at 00:00 UTC. The `app` rule caps the whole app at $2,500 per
+month, warning at $2,000, resetting on the first of the month.
+
 ## Setting team and gateway limits
 
 Team and gateway limits cover the node's own usage and all descendant usage.

package/docs/articles/configuring-auth0-for-mcp-auth.mdx

@@ -174,11 +174,16 @@ will need to do the following:
        new OAuthProtectedResourcePlugin({
          authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
          resourceName: "My MCP OAuth Resource",
+         scopesSupported: ["openid", "profile", "email", "offline_access"],
        }),
      );
    }
    ```
 
+   `scopesSupported` lists the scopes MCP clients request. Replace the example
+   values with the permissions your Auth0 API defines; keep `offline_access` if
+   clients need refresh tokens.
+
    See the
    [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin)
    for more details.

package/docs/articles/configuring-okta-for-mcp-auth.mdx

@@ -50,6 +50,19 @@ Next, you'll need to configure the scopes for your authorization server.
    tools").
 5. Check **Set as a default scope** and click **Create**.
 
+:::caution{title="Reserved Okta scopes break MCP clients"}
+
+Every Okta custom authorization server also publishes `device_sso` and
+`interclient_access` in its `scopes_supported` metadata. The **Include in public
+metadata** toggle for those two scopes is disabled, so you can't remove them. An
+MCP client that builds its scope list from the authorization server's metadata
+requests them together with `mcp:access`, and Okta rejects the authorization
+request with `illegal_scope_combination`. To keep clients off that list, set
+`scopesSupported` on the `OAuthProtectedResourcePlugin` in
+[Configure OAuth on Zuplo](#configure-oauth-on-zuplo) below.
+
+:::
+
 ## Create an OAuth Client Application
 
 Next, you'll need to create an OAuth client application for your MCP server.
@@ -102,7 +115,10 @@ Now create a rule for this policy:
      **Device Authorization**
    - **User is**: Select **Any user assigned the app**
    - **Scopes requested**: Select **The following scopes** and choose the scope
-     you created for the authorization server (that is, `mcp:access`)
+     you created for the authorization server (that is, `mcp:access`) and
+     `offline_access`, so clients can obtain refresh tokens. Okta rejects a
+     request that includes a scope no rule allows, so this list must cover every
+     scope you put in `scopesSupported` later in this guide.
 4. In the **THEN AND** section:
    - **Use this inline hook**: None (disabled)
    - **Access token lifetime is**: Set to desired value (for example, 1 hour)
@@ -128,7 +144,7 @@ will need to do the following:
        "options": {
          "oAuthResourceMetadataEnabled": true,
          "audience": "https://my-gateway.zuplo.dev/mcp",
-         "issuer": "https://your-okta-domain.okta.com/oauth2/your-auth-server-id"
+         "issuerUrl": "https://your-okta-domain.okta.com/oauth2/your-auth-server-id"
        }
      }
    }
@@ -136,10 +152,10 @@ will need to do the following:
 
    - Replace `my-gateway.zuplo.dev/mcp` with the audience you defined in your
      authorization server.
-   - Replace `your-okta-domain` in the `issuer` field with your actual Okta
+   - Replace `your-okta-domain` in the `issuerUrl` field with your actual Okta
      domain.
-   - Replace `your-auth-server-id` in the `issuer` field with the actual ID of
-     your Okta authorization server.
+   - Replace `your-auth-server-id` in the `issuerUrl` field with the actual ID
+     of your Okta authorization server.
 
 2. Add the OAuth policy to the MCP Server route. For example:
 
@@ -179,19 +195,24 @@ will need to do the following:
            "https://your-okta-domain.okta.com/oauth2/your-auth-server-id",
          ],
          resourceName: "My MCP OAuth Resource",
+         scopesSupported: ["mcp:access", "offline_access"],
        }),
      );
    }
    ```
 
-   - Replace `your-okta-domain` in the `issuer` field with your actual Okta
-     domain.
-   - Replace `your-auth-server-id` in the `issuer` field with the actual ID of
-     your Okta authorization server.
+   - Replace `your-okta-domain` in the `authorizationServers` value with your
+     actual Okta domain.
+   - Replace `your-auth-server-id` in the `authorizationServers` value with the
+     actual ID of your Okta authorization server.
+   - Set `scopesSupported` to the scopes you created in
+     [Configure Scopes](#configure-scopes). Keep `offline_access` if clients
+     need refresh tokens. Add `openid`, `profile`, or `email` only if your
+     tokens need those claims.
 
    This plugin populates the `.well-known` routes for the MCP server auth
    metadata discovery. This enables MCP clients to automatically discover the
-   authorization issuer endpoint. See the
+   authorization issuer endpoint and the scopes to request. See the
    [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin)
    for more details on this runtime plugin.
 
@@ -206,3 +227,20 @@ further instructions on testing your MCP server with `curl`.
 
 If you need more help debugging, see
 [Testing OAuth on Zuplo](../handlers/mcp-server.mdx#oauth-testing).
+
+## Troubleshooting
+
+### `illegal_scope_combination` in the Okta system log
+
+**Cause:** The MCP client requested `device_sso` or `interclient_access`
+together with your custom scopes. Okta publishes those two scopes in every
+custom authorization server's metadata and can't hide them, and a client that
+finds no scopes in the 401 challenge or the protected resource metadata falls
+back to that list. Okta rejects the combination and grants no scopes.
+
+**Fix:** Set `scopesSupported` on the `OAuthProtectedResourcePlugin` to the
+scopes you created, as shown in
+[Configure OAuth on Zuplo](#configure-oauth-on-zuplo), and redeploy. The gateway
+then advertises exactly those scopes in both the 401 challenge and the metadata
+document, so the client never consults the authorization server's list.
+Reconnect the client so it repeats discovery.

package/docs/articles/oauth-authentication.mdx

@@ -52,3 +52,37 @@ If you would like to remove the authorization header after you use one of the
 authorization policies, simply add the
 [Remove Request Headers](/docs/policies/remove-headers-inbound) policy after the
 authorization policy and set it to remove the `Authorization` header.
+
+## OAuth 2.0 Protected Resource Metadata
+
+OAuth clients, including MCP clients, discover how to obtain a token for your
+API through
+[OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728).
+Zuplo implements it in two parts:
+
+- The
+  [`OAuthProtectedResourcePlugin`](../programmable-api/oauth-protected-resource-plugin.mdx)
+  serves the metadata document at `/.well-known/oauth-protected-resource` and
+  every path beneath it. The document lists your authorization servers, a
+  human-readable resource name, and, when you set `scopesSupported`, the scopes
+  clients should request.
+- The `oAuthResourceMetadataEnabled` option on the JWT authentication policies
+  makes the policy answer requests without a bearer token with a 401 response
+  that carries a `WWW-Authenticate` header. The header's `resource_metadata`
+  parameter points at the metadata document for that route, and its `scope`
+  parameter repeats `scopesSupported` when the plugin sets it.
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="mcp:access offline_access"
+```
+
+The
+[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
+requires clients to discover the authorization server this way, and tells them
+to take the scopes they request from the challenge first and from the metadata
+document second. Set `scopesSupported` whenever a policy protects an MCP server,
+so clients request the scopes your resource expects instead of every scope the
+authorization server advertises. See
+[Advertising supported scopes](../programmable-api/oauth-protected-resource-plugin.mdx#advertising-supported-scopes)
+for the full order of precedence and an Okta-specific pitfall.

package/docs/handlers/mcp-server.mdx

@@ -412,14 +412,24 @@ enable OAuth authentication on your MCP Server:
        new OAuthProtectedResourcePlugin({
          authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
          resourceName: "My MCP OAuth Resource",
+         scopesSupported: ["mcp:access", "offline_access"],
        }),
      );
    }
    ```
 
+   `scopesSupported` lists the scopes MCP clients should request. The plugin
+   emits it as `scopes_supported` in the metadata document, and the OAuth policy
+   adds it as the `scope` parameter of its 401 `WWW-Authenticate` challenge.
+   Without it, some clients request every scope the authorization server
+   advertises. Replace the example values with the scopes your authorization
+   server defines for this resource.
+
    See the
    [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin.mdx)
-   for more details.
+   for all options and
+   [Advertising supported scopes](../programmable-api/oauth-protected-resource-plugin.mdx#advertising-supported-scopes)
+   for how clients pick scopes.
 
 ### API Key Auth
 
@@ -697,6 +707,12 @@ in the MCP Inspector UI to move to the next step.
    canonical URL of your Authorization server, and registered an OAuth policy to
    the route of your MCP server.
 
+   If the authorization server later rejects the authorization request with a
+   scope error (Okta reports `illegal_scope_combination`), the client built its
+   scope list from the authorization server's metadata. Set `scopesSupported` on
+   the plugin so the client requests only those scopes. See
+   [Advertising supported scopes](../programmable-api/oauth-protected-resource-plugin.mdx#advertising-supported-scopes).
+
 2. **Client Registration**: The MCP Inspector will try to use
    [Dynamic Client Registration](https://modelcontextprotocol.io/specification/draft/basic/authorization#dynamic-client-registration)
    to register a new client with the Authorization server. Note that not all MCP

package/docs/policies/ai-gateway-smart-router-inbound/doc.md

@@ -1,21 +1,14 @@
 # AI Gateway Smart Router
 
 Use this policy to classify the last user prompt on Chat Completions, Responses,
-and Anthropic Messages requests. It calls a dedicated AI Gateway application
-(`/{classifierAppID}/v1/chat/completions`) and stores the result on
-`AIGatewaySmartRouter` for later policies in the same request.
+and Anthropic Messages requests. Using the classification results, configure
+where to route the request based on its complexity.
 
-When `smartRoutingEnabled` is true, it overwrites completions routing from
-`modelsByComplexity`. Place it **after** Model Filtering so an invalid client
-model is still rejected before classification runs. The classified model then
-replaces that selection.
+When `smartRoutingEnabled` is true, it overwrites completions routing based on
+the configuration in `modelsByComplexity`.
 
-Classification is optional. Timeouts, classifier errors, unreadable bodies, and
-invalid options fail open: the original request is forwarded.
-
-> **Loop prevention.** The classifier hop is an `invokeRoute` sub-request. The
-> policy no-ops when `context.parentContext` is set, so the classifier app can
-> share the same route chain without classifying its own request.
+> **Classification failure handling.** If the message classification fails or
+> times out, the request is forwarded to the original model.
 
 ## Required options
 
@@ -24,11 +17,12 @@ invalid options fail open: the original request is forwarded.
 - `classifierAppApiKey` — bearer token for that app. Use
   `$env(CLASSIFIER_APP_API_KEY)`.
 - `classifierModel` — `providerName/model` sent on the classifier request.
+- `modelsByComplexity` — `providerName/model` for each of `low`, `medium`, and
+  `high`. Used for routing when `smartRoutingEnabled` is true.
 
-Omit `intents` and `classifierPrompt` to use the built-in taxonomy (code,
+Omit `intents` and `classifierPrompt` to use the built-in dictionary (code,
 summarization, translation, qa, conversation, classification, creative_writing,
-agentic, document_qa, other) and the built-in system prompt. Include
-`{{intents}}` in a custom prompt to inject the configured intent list.
+agentic, document_qa, other) and the built-in classification prompt.
 
 ## Example
 
@@ -65,30 +59,207 @@ filtering already selected a model. Filtering skips when routing is already set,
 so putting this policy first would also skip allow-list checks on the client's
 original model.
 
-## Read the result from custom code
+## How classification drives routing
+
+Complexity is classified independently of intent, as `low`, `medium`, or `high`.
+Smart Router looks up `modelsByComplexity[complexity]` and applies it only when
+**all** of the following hold:
+
+- `smartRoutingEnabled` is `true`.
+- The classified intent is a known one (not capped as an unknown intent).
+- `modelsByComplexity` has a model configured for that complexity.
+- `profile.confidence >= minConfidenceForRouting` (default `0.5`).
+
+When routing isn't applied, read `smartRouting.reason` from the result (see
+[Using classification results in custom code](#using-classification-results-in-custom-code))
+to see why: `disabled`, `unknown-intent`, `no-model`, `low-confidence`,
+`internal-error`, or `applied`.
+
+### Other advanced options
+
+| Option                    | Default | Purpose                                                                                                                                                                                             |
+| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minConfidenceForRouting` | `0.5`   | Raise it to route only on confident classifications; lower it to route more aggressively. Unknown intents are always capped just below this value, so they never qualify regardless of the setting. |
+| `classifierTimeoutMs`     | `8000`  | How long to wait for the classifier before giving up and forwarding the request unclassified.                                                                                                       |
+| `maxPromptChars`          | `8000`  | Truncates the prompt sent to the classifier, to keep classifier cost and latency bounded on very long prompts.                                                                                      |
+
+## Advanced configuration
+
+Use these options to control what the classifier evaluates and how strongly its
+result influences routing.
+
+### Custom intents
+
+`intents` replaces the built-in dictionary entirely — it's not additive. Provide
+a non-empty list of `{ id, description }` pairs:
+
+```json
+{
+  "intents": [
+    {
+      "id": "billing",
+      "description": "Questions about invoices, payments, or subscription plans."
+    },
+    {
+      "id": "support",
+      "description": "Troubleshooting or how-to questions about the product."
+    }
+  ]
+}
+```
+
+The `id` values become the enum the classifier model must return — the
+classifier calls a strict JSON-schema chat completion, so it can only return one
+of your configured ids. The `description` values are only shown to the
+classifier if your prompt includes `{{intents}}` (see below).
+
+If the classifier returns an `id` outside this list, Smart Router keeps it as an
+"unknown intent" and caps its confidence just below `minConfidenceForRouting`,
+so it's never eligible for routing.
+
+### Custom classifier prompt
+
+`classifierPrompt` replaces the built-in classifier prompt. It accepts either a
+string or an array of lines:
+
+```json
+{
+  "classifierPrompt": [
+    "You are an intent classifier for a billing support bot.",
+    "Return JSON only that matches the schema.",
+    "Intent (pick the single most specific match):",
+    "{{intents}}"
+  ]
+}
+```
+
+Include the literal placeholder `{{intents}}` anywhere in the prompt to have it
+replaced with a `- id: description` line for each configured intent (or the
+built-in ones, if `intents` is also omitted). Pairing a custom `intents` list
+with the built-in `classifierPrompt` (by omitting `classifierPrompt` entirely)
+works out of the box, because the built-in prompt already contains
+`{{intents}}`.
+
+## Using classification results in custom code
+
+`AIGatewaySmartRouter.get(context)` returns the result Smart Router stored on
+the request, or `undefined` if it didn't run (non-AI request, unreadable body,
+or a fail-open error):
 
 ```typescript
 import { AIGatewaySmartRouter } from "@zuplo/runtime";
 
 const result = AIGatewaySmartRouter.get(context);
-if (result?.profile.intent === "code") {
-  // ...
+```
+
+`result` has this shape:
+
+```typescript
+interface AIGatewaySmartRouterResult {
+  profile: {
+    intent: string;
+    complexity: "low" | "medium" | "high";
+    confidence: number;
+    reasons: string[];
+  };
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  classifierModel: string;
+  routing: { model?: string };
+  durationMs: number;
+  promptSource: "user" | "prior-user";
+  promptLength: number;
+  promptTruncated: boolean;
+  unknownIntent: boolean;
+  smartRouting: {
+    enabled: boolean;
+    applied: boolean;
+    reason:
+      | "applied"
+      | "disabled"
+      | "low-confidence"
+      | "no-model"
+      | "internal-error"
+      | "unknown-intent";
+    minConfidence: number;
+  };
 }
 ```
 
-## How prompt text is chosen
+Read it from any policy placed after Smart Router in the chain. Common uses:
+
+- **Branch on intent or complexity** — apply a stricter rate limit, a different
+  DLP policy, or a longer timeout for `high` complexity or an `agentic` intent:
+
+  ```typescript
+  const result = AIGatewaySmartRouter.get(context);
+  if (result?.profile.complexity === "high") {
+    // e.g. apply a stricter rate limit or route to a review queue
+  }
+  ```
+
+- **Layer business logic on top of `modelsByComplexity`** — for example, cap the
+  model for free-tier callers regardless of classified complexity. Read the plan
+  from the caller's API key metadata, not from a raw request header (the caller
+  controls headers and could set or omit them to bypass the cap). The built-in
+  API Key Auth policy puts a key's metadata on `request.user.data` — set `plan`
+  there when you create the key, and it lands on every request that key makes:
+
+  ```typescript
+  import { AIGatewayModelRouting, AIGatewaySmartRouter } from "@zuplo/runtime";
+
+  const result = AIGatewaySmartRouter.get(context);
+  const isFreeTier = request.user?.data.plan === "free";
+  if (result?.profile.complexity === "high" && isFreeTier) {
+    await AIGatewayModelRouting.set(context, {
+      completions: "openai/gpt-4o-mini",
+    });
+  }
+  ```
+
+- **Observe why routing wasn't applied** — log when `smartRouting.reason` is
+  `low-confidence` or `unknown-intent` to tune `minConfidenceForRouting` or the
+  intent taxonomy:
+
+  ```typescript
+  const result = AIGatewaySmartRouter.get(context);
+  if (result && !result.smartRouting.applied) {
+    context.log.info(
+      { reason: result.smartRouting.reason },
+      "Smart routing skipped"
+    );
+  }
+  ```
+
+- **Surface classification for debugging** — add response headers in a
+  non-production environment to see what the classifier returned. This runs in
+  an outbound policy, so return a new `Response` carrying the headers — mutating
+  a cloned `Headers` object alone has no effect on what the caller receives:
+
+  ```typescript
+  const result = AIGatewaySmartRouter.get(context);
+  if (!result) {
+    return response;
+  }
+
+  const headers = new Headers(response.headers);
+  headers.set("x-classified-intent", result.profile.intent);
+  headers.set("x-classified-complexity", result.profile.complexity);
 
-The policy reads the typed body from the route (`getFormat` / `getRequestBody`),
-then takes the last real user text:
+  return new Response(response.body, {
+    headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+  ```
 
-- `/v1/chat/completions` — OpenAI chat `messages[]`, even when the downstream
-  provider is Anthropic or Google (Zuplo translates below the policy chain).
-- `/v1/responses` — OpenAI Responses `input`.
-- `/v1/messages` — native Anthropic `messages[]`.
+## What content is evaluated
 
-Tool follow-up turns (`tool` / `function` roles, `tool_result` blocks,
-`function_call_output` items) are skipped so a prior user message is classified
-instead. Embeddings and other non-AI paths are skipped.
+The policy reads the last user message in order to classify its intent and
+complexity. Embeddings, tool messages and other non-AI paths are skipped.
 
 ## Fail-open behavior
 

package/docs/policies/ai-gateway-smart-router-inbound/intro.md

@@ -1,4 +1,3 @@
 Classifies the last user prompt by calling a dedicated classifier AI Gateway
 app, stores the result on `AIGatewaySmartRouter` for later policies, and
-optionally routes completions by classified complexity. Classifier failures fail
-open so the original request still reaches the model.
+optionally routes completions by classified complexity.

package/docs/policies/ai-gateway-smart-router-inbound/schema.json

@@ -38,7 +38,8 @@
           "required": [
             "classifierAppID",
             "classifierAppApiKey",
-            "classifierModel"
+            "classifierModel",
+            "modelsByComplexity"
           ],
           "examples": [
             {
@@ -57,7 +58,7 @@
             "classifierAppID": {
               "type": "string",
               "title": "Classifier App ID",
-              "description": "The AI Gateway application id whose `/v1/chat/completions` route runs the classifier. The policy calls `/{classifierAppID}/v1/chat/completions` via `context.invokeRoute`.",
+              "description": "The AI Gateway application id used to run the classifier prompt and evaluate the user's request.",
               "examples": ["config_1234"]
             },
             "classifierAppApiKey": {
@@ -69,21 +70,22 @@
             "classifierModel": {
               "type": "string",
               "title": "Classifier Model",
-              "description": "The `providerName/model` reference the classifier chat/completions request should use.",
+              "description": "The model (`providerName/model`) the classifier uses to evaluate the user's request. E.g. `openai/gpt-4o-mini`.",
               "pattern": "^[^/\\s]+/.+$",
               "examples": ["openai/gpt-4o-mini"]
             },
             "smartRoutingEnabled": {
               "type": "boolean",
               "title": "Smart Routing Enabled",
-              "description": "When true, apply model routing from `modelsByComplexity` when confidence is high enough and the intent is known. Classification still runs when false.",
+              "description": "When true, apply model routing based on the models set in `modelsByComplexity` when confidence score meets the `minConfidenceForRouting` threshold. When set to false, classification still runs but model routing is not applied, useful for debugging or testing the classifier prompt.",
               "default": false
             },
             "modelsByComplexity": {
               "type": "object",
               "title": "Models By Complexity",
-              "description": "Optional `providerName/model` routing by classified complexity. Used only when `smartRoutingEnabled` is true.",
+              "description": "Enables which model will be used based on the classifier results (`low`, `medium` and `high`). This configuration is applied only when `smartRoutingEnabled` is true and confidence score meets the `minConfidenceForRouting` threshold.",
               "additionalProperties": false,
+              "required": ["low", "medium", "high"],
               "properties": {
                 "low": {
                   "type": "string",
@@ -111,7 +113,7 @@
             "intents": {
               "type": "array",
               "title": "Intents",
-              "description": "Labels the classifier may assign. Used to build the JSON schema enum and injected into `classifierPrompt` at `{{intents}}`. Omit to use the built-in taxonomy (code, summarization, translation, qa, conversation, classification, creative\\_writing, agentic, document\\_qa, other).",
+              "description": "Dictionary of intents used to classify the user message being evaluated. Omit to use the built-in dictionary (code, summarization, translation, qa, conversation, classification, creative\\_writing, agentic, document\\_qa, other).",
               "minItems": 1,
               "items": {
                 "type": "object",
@@ -121,14 +123,14 @@
                   "id": {
                     "type": "string",
                     "title": "Intent ID",
-                    "description": "Stable intent identifier written into the classifier JSON schema enum.",
+                    "description": "Label used to classify the intent of the user message being evaluated.",
                     "minLength": 1,
                     "examples": ["code"]
                   },
                   "description": {
                     "type": "string",
                     "title": "Intent Description",
-                    "description": "Short description shown to the classifier for this intent.",
+                    "description": "Short description of the intent label.",
                     "examples": [
                       "Write, edit, refactor, debug, or review source code."
                     ]
@@ -138,7 +140,7 @@
             },
             "classifierPrompt": {
               "title": "Classifier Prompt",
-              "description": "System prompt for the classifier. If it includes `{{intents}}`, that placeholder is replaced with the configured intent id/description list. A string or an array of lines (joined with newlines). Omit to use the built-in classifier prompt.",
+              "description": "Prompt used to analyze and classify the user message. Omit to use the built-in classifier prompt.",
               "oneOf": [
                 {
                   "type": "string",
@@ -165,7 +167,7 @@
             "classifierTimeoutMs": {
               "type": "integer",
               "title": "Classifier Timeout (ms)",
-              "description": "How long to wait for the classifier `invokeRoute` call before skipping classification and forwarding the original request.",
+              "description": "Timeout configured for the classifier task. When exceeded, the request is forwarded without classification to the original model.",
               "minimum": 1,
               "maximum": 120000,
               "default": 8000,
@@ -174,7 +176,7 @@
             "maxPromptChars": {
               "type": "integer",
               "title": "Max Prompt Characters",
-              "description": "Maximum characters of user prompt sent to the classifier. Longer prompts are truncated.",
+              "description": "Maximum characters of user message sent to the classifier. Longer messages get truncated.",
               "minimum": 1,
               "default": 8000,
               "x-advanced": true

package/docs/programmable-api/oauth-protected-resource-plugin.mdx

@@ -13,13 +13,16 @@ more details.
 
 ## Usage
 
-This runtime plugin will register the `.well-known/oauth-protected-resource`
-route on your behalf. If you configure an
+This runtime plugin registers the `.well-known/oauth-protected-resource` route
+on your behalf, along with every path beneath it, such as
+`/.well-known/oauth-protected-resource/mcp`. If you configure an
 [OAuth Policy](../articles/oauth-authentication.mdx) on a route with the
-`oAuthResourceMetadataEnabled` option set to `true`, then the OAuth policy will
-automatically add the necessary `WWW-Authenticate` header to 401 responses, with
-the `resource_metadata` parameter set to the URL of the
-`.well-known/oauth-protected-resource` endpoint.
+`oAuthResourceMetadataEnabled` option set to `true`, the policy answers requests
+that carry no bearer token with a 401 response and a `WWW-Authenticate` header.
+The header's `resource_metadata` parameter is the URL of the
+`.well-known/oauth-protected-resource` endpoint for that route. When you set
+`scopesSupported`, the header also carries a `scope` parameter that lists those
+scopes.
 
 ```ts
 import {
@@ -32,6 +35,7 @@ export function runtimeInit(runtime: RuntimeExtensions) {
     new OAuthProtectedResourcePlugin({
       authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
       resourceName: "My MCP OAuth Resource",
+      scopesSupported: ["mcp:access", "offline_access"],
     }),
   );
 }
@@ -44,3 +48,71 @@ a human readable name for the resource.
 Note that the `.well-known/oauth-protected-resource` endpoint explicitly has a
 CORS policy of `anything-goes` since this is a public endpoint that should be
 accessible to anyone to check the server's OAuth configuration.
+
+## Options
+
+Construct the plugin inside `runtimeInit`. The plugin validates its options when
+you construct it, so an invalid value fails at startup with a
+`ConfigurationError` instead of failing a client's first login.
+
+| Option                 | Type       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `authorizationServers` | `string[]` | Canonical issuer URLs of the authorization servers that issue tokens for this resource. Each should comply with [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414). Emitted as `authorization_servers`.                                                                                                                                                                                                                                                                                                                                                                    |
+| `resourceName`         | `string`   | Human-readable name of the resource, intended for display to end users. RFC 9728 recommends setting it. Emitted as `resource_name`.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `scopesSupported`      | `string[]` | Scopes that clients should request when they obtain an access token for this resource. Emitted as `scopes_supported`, and as the `scope` parameter of the 401 `WWW-Authenticate` header by OAuth policies that have `oAuthResourceMetadataEnabled` set. Each entry must be one OAuth scope token ([RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)): printable ASCII with no spaces, double quotes, or backslashes. Use one entry per scope, never a space-delimited string. An empty array is rejected; omit the option to advertise no scopes. |
+
+## Advertising supported scopes
+
+An MCP client has to decide which scopes to request from the authorization
+server. The
+[MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-selection-strategy)
+tells clients to consider these sources in order:
+
+1. **The `scope` parameter of the `WWW-Authenticate` challenge** on the 401
+   response. Clients treat these scopes as authoritative.
+2. **The `scopes_supported` array in the protected resource metadata** document,
+   when the challenge has no `scope` parameter.
+3. **The `scopes_supported` array in the authorization server's own metadata.**
+   The specification doesn't list this source, but some clients fall back to it
+   when the first two are empty. It usually contains every scope the server
+   knows about.
+4. **No `scope` parameter at all.**
+
+Setting `scopesSupported` fills the first two sources with the same list, so no
+client reaches the third. For example, a plugin configured with an Okta
+authorization server, `resourceName: "Acme MCP"`, and
+`scopesSupported: ["mcp:access", "offline_access"]` serves this document at
+`/.well-known/oauth-protected-resource/mcp`:
+
+```json
+{
+  "resource": "https://api.example.com/mcp",
+  "authorization_servers": ["https://acme.okta.com/oauth2/aus1a2b3c"],
+  "resource_name": "Acme MCP",
+  "scopes_supported": ["mcp:access", "offline_access"]
+}
+```
+
+A request to `/mcp` without a bearer token receives:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="mcp:access offline_access"
+```
+
+If you don't set `scopesSupported`, the document has no `scopes_supported` key
+and the header has no `scope` parameter. Requests that carry an invalid or
+expired token receive a 401 without the `WWW-Authenticate` header in either
+case.
+
+:::caution{title="Okta rejects its own default scopes"}
+
+Okta custom authorization servers always publish `device_sso` and
+`interclient_access` in their `scopes_supported` metadata. The **Include in
+public metadata** toggle for those two scopes is disabled, so you can't remove
+them. A client that falls back to that list requests them together with your
+scopes, and Okta rejects the authorization request with
+`illegal_scope_combination` and grants no scopes. Set `scopesSupported` whenever
+Okta is your authorization server.
+
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.7",
+  "version": "7.6.9",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.7",
-    "@zuplo/core": "7.6.7",
-    "@zuplo/runtime": "7.6.7",
-    "@zuplo/test": "7.6.7"
+    "@zuplo/cli": "7.6.9",
+    "@zuplo/core": "7.6.9",
+    "@zuplo/runtime": "7.6.9",
+    "@zuplo/test": "7.6.9"
   }
 }