zuplo 7.9.14 → 7.9.15

package/docs/dev-portal/zudoku/guides/environment-variables.md

@@ -97,3 +97,78 @@ in `vite-env.d.ts`. A helpful explanation can be found on
 [this StackOverflow reply](https://stackoverflow.com/a/51114250).
 
 :::
+
+## Environment Variables in Zuplo
+
+Set Dev Portal variables in the Zuplo Portal under **Settings** >
+[**Environment Variables**](https://portal.zuplo.com/+/account/project/settings/environment-variables),
+the same place you set gateway variables. For the Dev Portal:
+
+- Only variables whose names start with `ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_` are
+  available. Both prefixes work the same way.
+- Only configuration variables are available. Zuplo never sends secret variables
+  to the Dev Portal build, even if their names have a public prefix.
+- Values are read when the portal is built and are embedded in the published
+  site. Redeploy the environment after you change a value.
+
+For how Dev Portal variables differ from gateway variables, see
+[Configuring Environment Variables](/docs/articles/environment-variables#gateway-and-developer-portal-variables).
+
+### Zuplo Build Variables
+
+When Zuplo builds your Dev Portal, it sets the following variables. You don't
+need to create them.
+
+| Variable                 | Value                                                                                                                                                              |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ZUPLO_ENVIRONMENT_TYPE` | The environment being built: `PRODUCTION`, `PREVIEW`, or `WORKING_COPY`.                                                                                           |
+| `ZUPLO_SERVER_URL`       | The default URL of the API gateway deployed with this Dev Portal, for example `https://my-project-main-1234abc.zuplo.app`. Custom domains don't change this value. |
+| `ZUPLO_BUILD_ID`         | A unique ID (UUID) for the build.                                                                                                                                  |
+
+Read these variables with `import.meta.env` in your custom components and
+plugins:
+
+```tsx
+export const EnvironmentBadge = () => (
+  <span>{import.meta.env.ZUPLO_ENVIRONMENT_TYPE}</span>
+);
+```
+
+`ZUPLO_ENVIRONMENT_TYPE` in the Dev Portal build uses different values than the
+`ZUPLO_ENVIRONMENT_TYPE` and `ZUPLO_ENVIRONMENT_STAGE` variables available to
+your gateway. See
+[System Environment Variables](/docs/programmable-api/environment#system-environment-variables)
+for the gateway values.
+
+### Check the Environment in `zudoku.config.tsx`
+
+The configuration file runs twice: once in Node.js when the build starts, and
+again as part of the built site, which renders your pages and `<head>` tags. In
+the built site, `process.env` only resolves variables that start with
+`ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_`, so `process.env.ZUPLO_ENVIRONMENT_TYPE` is
+`undefined` there. Read `import.meta.env` first and fall back to `process.env`
+to get the same value in both places:
+
+```tsx title="zudoku.config.tsx"
+const environmentType =
+  import.meta.env?.ZUPLO_ENVIRONMENT_TYPE ?? process.env.ZUPLO_ENVIRONMENT_TYPE;
+
+const isProduction = environmentType === "PRODUCTION";
+```
+
+The build logs a warning that `process.env.ZUPLO_ENVIRONMENT_TYPE` isn't
+prefixed with `ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_`. You can ignore it.
+
+To avoid the warning, create a `ZUPLO_PUBLIC_` variable with a different value
+for each environment instead. Both approaches include the value in the
+client-side bundle, so use them only for values that aren't secret.
+
+### Local Development
+
+Locally, put `ZUPLO_PUBLIC_` and `ZUDOKU_PUBLIC_` variables in a `.env` file in
+your Dev Portal folder, as described in [Local Env Files](#local-env-files).
+Variables you set in the Zuplo Portal aren't available locally.
+
+`zuplo dev` sets `ZUPLO_SERVER_URL` to your local gateway, for example
+`http://localhost:9000`. `ZUPLO_ENVIRONMENT_TYPE` is never `PRODUCTION` locally,
+so `isProduction` in the previous example is `false`.

package/docs/dev-portal/zudoku-partials/guides/environment-variables.partial.md

@@ -0,0 +1,74 @@
+## Environment Variables in Zuplo
+
+Set Dev Portal variables in the Zuplo Portal under **Settings** >
+[**Environment Variables**](https://portal.zuplo.com/+/account/project/settings/environment-variables),
+the same place you set gateway variables. For the Dev Portal:
+
+- Only variables whose names start with `ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_` are
+  available. Both prefixes work the same way.
+- Only configuration variables are available. Zuplo never sends secret variables
+  to the Dev Portal build, even if their names have a public prefix.
+- Values are read when the portal is built and are embedded in the published
+  site. Redeploy the environment after you change a value.
+
+For how Dev Portal variables differ from gateway variables, see
+[Configuring Environment Variables](/docs/articles/environment-variables#gateway-and-developer-portal-variables).
+
+### Zuplo Build Variables
+
+When Zuplo builds your Dev Portal, it sets the following variables. You don't
+need to create them.
+
+| Variable                 | Value                                                                                                                                                              |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ZUPLO_ENVIRONMENT_TYPE` | The environment being built: `PRODUCTION`, `PREVIEW`, or `WORKING_COPY`.                                                                                           |
+| `ZUPLO_SERVER_URL`       | The default URL of the API gateway deployed with this Dev Portal, for example `https://my-project-main-1234abc.zuplo.app`. Custom domains don't change this value. |
+| `ZUPLO_BUILD_ID`         | A unique ID (UUID) for the build.                                                                                                                                  |
+
+Read these variables with `import.meta.env` in your custom components and
+plugins:
+
+```tsx
+export const EnvironmentBadge = () => (
+  <span>{import.meta.env.ZUPLO_ENVIRONMENT_TYPE}</span>
+);
+```
+
+`ZUPLO_ENVIRONMENT_TYPE` in the Dev Portal build uses different values than the
+`ZUPLO_ENVIRONMENT_TYPE` and `ZUPLO_ENVIRONMENT_STAGE` variables available to
+your gateway. See
+[System Environment Variables](/docs/programmable-api/environment#system-environment-variables)
+for the gateway values.
+
+### Check the Environment in `zudoku.config.tsx`
+
+The configuration file runs twice: once in Node.js when the build starts, and
+again as part of the built site, which renders your pages and `<head>` tags. In
+the built site, `process.env` only resolves variables that start with
+`ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_`, so `process.env.ZUPLO_ENVIRONMENT_TYPE` is
+`undefined` there. Read `import.meta.env` first and fall back to `process.env`
+to get the same value in both places:
+
+```tsx title="zudoku.config.tsx"
+const environmentType =
+  import.meta.env?.ZUPLO_ENVIRONMENT_TYPE ?? process.env.ZUPLO_ENVIRONMENT_TYPE;
+
+const isProduction = environmentType === "PRODUCTION";
+```
+
+The build logs a warning that `process.env.ZUPLO_ENVIRONMENT_TYPE` isn't
+prefixed with `ZUPLO_PUBLIC_` or `ZUDOKU_PUBLIC_`. You can ignore it.
+
+To avoid the warning, create a `ZUPLO_PUBLIC_` variable with a different value
+for each environment instead. Both approaches include the value in the
+client-side bundle, so use them only for values that aren't secret.
+
+### Local Development
+
+Locally, put `ZUPLO_PUBLIC_` and `ZUDOKU_PUBLIC_` variables in a `.env` file in
+your Dev Portal folder, as described in [Local Env Files](#local-env-files).
+Variables you set in the Zuplo Portal aren't available locally.
+
+`zuplo dev` sets `ZUPLO_SERVER_URL` to your local gateway, for example
+`http://localhost:9000`. `ZUPLO_ENVIRONMENT_TYPE` is never `PRODUCTION` locally,
+so `isProduction` in the previous example is `false`.

package/docs/handlers/mcp-server.mdx

@@ -512,6 +512,78 @@ example, in Cursor:
 }
 ```
 
+## Keep REST routes private
+
+Every operation an MCP server exposes is still a route on your gateway, and
+clients can reach that route directly over HTTP. To make the routes reachable
+only through the MCP server, add the
+[Internal Only policy](../policies/internal-only-inbound.mdx) to every route the
+server exposes.
+
+The MCP Server handler calls each route with `context.invokeRoute`, which the
+Internal Only policy accepts. The policy rejects every request that arrives over
+the network. Set `status` to `404` so a direct call gets the same response as a
+route that doesn't exist:
+
+```json title="config/policies.json"
+{
+  "name": "internal-only-inbound",
+  "policyType": "internal-only-inbound",
+  "handler": {
+    "export": "InternalOnlyInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "status": 404
+    }
+  }
+}
+```
+
+Put the policy first in the inbound policies of each route, so nothing else runs
+for a rejected request:
+
+```json title="config/routes.oas.json"
+"/orders/{orderId}": {
+  "get": {
+    "operationId": "get-order",
+    "x-internal": true,
+    "parameters": [
+      {
+        "name": "orderId",
+        "in": "path",
+        "required": true,
+        "schema": { "type": "string" }
+      }
+    ],
+    "x-zuplo-route": {
+      "corsPolicy": "none",
+      "handler": {
+        "export": "urlForwardHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": { "baseUrl": "https://orders.example.com" }
+      },
+      "policies": {
+        "inbound": ["internal-only-inbound"]
+      }
+    }
+  }
+}
+```
+
+When you hide a route:
+
+- **Authenticate callers on the MCP server route.** The Internal Only policy
+  checks where a request comes from, not who sent it. The MCP server forwards
+  the client's request headers to each route, so a route can keep its own
+  authentication policy after this one.
+- **Set `corsPolicy` to `none`.** Preflight `OPTIONS` requests skip inbound
+  policies, so a route with a CORS policy still answers them.
+- **Mark the route [`x-internal`](../articles/openapi.mdx#x-internal)** to keep
+  it out of your developer portal.
+- **A custom [not-found handler](../programmable-api/not-found-handler.mdx)**
+  answers paths that don't exist with your own response, so a hidden route's
+  `404` no longer matches it.
+
 ## Testing
 
 ### MCP Inspector

package/docs/mcp-server/overview.mdx

@@ -69,6 +69,13 @@ Expose only the operations your clients need. Apply authentication and access
 controls to those operations, use rate limits to control usage, and configure
 [audit logging](../articles/audit-logging.mdx) to record calls.
 
+Each operation the server exposes is also a REST route that clients can reach
+directly over HTTP. To serve those operations only through the MCP server, add
+the [Internal Only policy](../policies/internal-only-inbound.mdx) to each route,
+with `"status": 404` so a direct call gets the same response as a route that
+doesn't exist. See
+[Keep REST routes private](../handlers/mcp-server.mdx#keep-rest-routes-private).
+
 <span id="learn-more" />
 
 ## Next steps

package/docs/mcp-server/tools.mdx

@@ -364,6 +364,70 @@ MCP tool configuration error: invalid toolInputStyle "Flat" on operation "create
 If your MCP server still uses the deprecated `files` option, set
 `toolInputStyle` in the operation's `x-zuplo-mcp-tool` extension instead.
 
+## Track tool calls with runtime hooks
+
+When the MCP Server handler invokes an API route for a tool, the global runtime
+hooks run for both the client request and the internal route invocation. Each
+invocation has its own request and context:
+
+| Value                   | Client request                           | Internal tool invocation                                                        |
+| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |
+| Method and path         | `POST /mcp`, or your configured MCP path | The API route's method and path, such as `GET /weather/current?location=Boston` |
+| Body                    | The MCP JSON-RPC envelope                | The tool arguments mapped to the API request body, if the route uses one        |
+| `context.route`         | The MCP route                            | The tool's API route                                                            |
+| `context.parentContext` | `undefined`                              | The context of the MCP request that invoked the route                           |
+
+Path and query arguments become URL parameters, and declared header arguments
+become request headers. A `GET` tool invocation has no request body.
+
+Use
+[`context.parentContext`](../programmable-api/zuplo-context.mdx#parentcontext)
+to distinguish client requests from internal invocations. It identifies any
+internal route invocation, including calls made with `context.invokeRoute` in
+your own code.
+
+To log only the API route invocations for MCP tools, add this global request
+hook in `modules/zuplo.runtime.ts`:
+
+```ts
+import { RuntimeExtensions, ZuploMcpSdk } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addRequestHook((request, context) => {
+    const toolCall = new ZuploMcpSdk(context).getRawCallToolRequest();
+
+    if (context.parentContext && toolCall) {
+      context.log.info({
+        toolName: toolCall.params.name,
+        method: request.method,
+        path: new URL(request.url).pathname,
+        requestId: context.requestId,
+        contextId: context.contextId,
+      });
+    }
+
+    return request;
+  });
+}
+```
+
+This logs a tool's API route invocation without also counting the outer `/mcp`
+request. To count only client requests instead, filter for
+`context.parentContext === undefined`. The SDK helper reads the current context
+and its immediate parent; see
+[MCP metadata in runtime hooks](../programmable-api/mcp-sdk.mdx#mcp-metadata-in-runtime-hooks)
+for timing and nested-call details.
+
+By default, the internal invocation shares the parent's `requestId` and has its
+own `contextId`. Use `requestId` to group related events and `contextId` to
+identify each execution. See
+[Request/Response Hooks](../programmable-api/hooks.mdx#internal-route-invocations)
+for hook behavior and response logging.
+
+This extra hook execution applies when a tool invokes a Zuplo API route.
+[Proxying to an upstream MCP server](../mcp-gateway/code-config/mcp-proxy-handler.mdx)
+doesn't create an internal API route invocation for each tool call.
+
 ## Testing MCP Tools
 
 ### List Available Tools
@@ -525,6 +589,14 @@ provided by the AI client _before_ your handler is ever called. Input validation
 is an important part of MCP, so ensure you have strong validation in your
 OpenAPI JSON schemas!
 
+### Keep Tool Routes Private
+
+A tool's route is also a REST endpoint that clients can reach directly. If AI
+clients should reach the operation only through the MCP server, add the
+[Internal Only policy](../policies/internal-only-inbound.mdx) to the route with
+`"status": 404`. See
+[Keep REST routes private](../handlers/mcp-server.mdx#keep-rest-routes-private).
+
 ### Custom Tools
 
 For complex workflows that don't map 1:1 to a single API route, or require

package/docs/policies/_index.md

@@ -41,7 +41,6 @@
 | data-loss-prevention-outbound | Data Loss Prevention | Scans the upstream response body for sensitive data — PII, secrets, and financial identifiers — using an extensible catalog of built-in recognizers plus any custom patterns, and takes a configurable action when a match is found.  The action is one of `mask` (redact matches before returning the response), `block` (replace the response with a `422` listing the detected entity names only), or `log` (record a warning and return unchanged). Only text content types are inspected; binary bodies pass through untouched, and the body is read from a clone so the client still receives the original stream. | api-gateway |
 | data-loss-prevention-inbound | Data Loss Prevention | Scans the incoming request body for sensitive data — PII, secrets, and financial identifiers — using an extensible catalog of built-in recognizers plus any custom patterns, and takes a configurable action when a match is found.  The action is one of `mask` (redact matches before forwarding the request), `block` (reject with a `422` listing the detected entity names only), or `log` (record a warning and forward unchanged). Only text content types are inspected; binary bodies pass through untouched, and the body is read from a clone so the upstream still receives the original stream. | api-gateway |
 | ai-gateway-dlp-inbound | Data Loss Prevention (DLP) | Data Loss Prevention (DLP) Inbound Policy for the AI Gateway | ai-gateway |
-| ai-gateway-internal-only-inbound | Ensure Gateway Internal Invocation Only | Accepts only requests that this gateway made itself with `context.invokeRoute`, and rejects every request that arrived over the network with `403 Forbidden`.  Use it in place of AI Gateway Authentication on an application that is only ever called by other routes and policies on the same gateway, such as the classifier application behind the Smart Router or Prompt Injection Protection policies. Those calls never leave the gateway, so an API key on them protects nothing. This policy asserts the one thing that matters: the request originated inside the deployment.  The check reads `context.parentContext`, which the runtime sets only on the child context that `context.invokeRoute` creates. A client cannot supply it through a header, the URL, or the body. The policy has no options, makes no network calls, reads no body, and leaves `request.user` unset. | ai-gateway |
 | firebase-jwt-inbound | Firebase JWT Auth | Authenticate users using Firebase issued JWT tokens. | api-gateway |
 | formdata-to-json-inbound | Form Data to JSON | Converts form data in the incoming request to JSON. | api-gateway |
 | ai-gateway-galileo-tracing-inbound | Galileo Tracing | Galileo Tracing Inbound Policy | ai-gateway |
@@ -52,6 +51,7 @@
 | graphql-disable-introspection-inbound | GraphQL Disable Introspection | Policy that disables GraphQL introspection queries in production. Introspection allows clients to discover the schema, which can be a security risk as it exposes your entire API structure. | api-gateway |
 | graphql-introspection-filter-outbound | GraphQL Introspection Filter | Filters GraphQL introspection responses to exclude specific types and fields.  This policy intercepts GraphQL introspection query responses and removes configured types and fields from the schema. Useful for hiding internal types or sensitive fields from the public schema. | api-gateway |
 | http-deprecation-outbound | HTTP Deprecation | Sets HTTP deprecation headers on the outgoing response following the IETF HTTP Deprecation Header standard. Supports the Deprecation, Sunset, and Link headers. | api-gateway |
+| internal-only-inbound | Internal Only | Accepts only requests that this gateway made itself with `context.invokeRoute`, and rejects every request that arrived over the network.  Use it on a route that only other routes, handlers, and policies on the same gateway call: a REST endpoint that an MCP server exposes as a tool, or the classifier application behind the Smart Router or Prompt Injection Protection policies. Those calls never leave the gateway, so an API key on them protects nothing. This policy asserts the one thing that matters: the request originated inside the deployment.  The check reads `context.parentContext`, which the runtime sets only on the child context that `context.invokeRoute` creates. A client cannot supply it through a header, the URL, or the body. The policy makes no network calls, reads no body, and leaves `request.user` unset.  A rejected request gets a `403 Forbidden` problem response with no `detail` by default, so the caller learns nothing about how the gateway works; the reason goes to the request log. Set `status` to answer with another client error, such as `404` to hide the route or `401`, `statusText` to change the status text, and `detail` to add a message. | api-gateway, ai-gateway |
 | ip-address-restriction-inbound | IP Address Restriction | Restricts which client IP addresses can call a route using an allow list, a deny list, or both. Entries are individual IP addresses or CIDR ranges, in IPv4 or IPv6. | api-gateway |
 | validate-json-schema-inbound | JSON Body Validation (deprecated) | Validates the body of an incoming request based on a JSON schema. | api-gateway |
 | open-id-jwt-auth-inbound | JWT Auth | The Open ID JWT Authentication policy allows you to authenticate incoming requests using an Open ID compliant bearer token. | api-gateway |

package/docs/policies/ai-gateway-auth-inbound/doc.md

@@ -93,8 +93,8 @@ configuration from the route's `app_id` path parameter instead.
 > the application from the URL and accepts the request without an application
 > key. Only leave authentication out when another control restricts access:
 > network isolation, or the
-> [Ensure Gateway Internal Invocation Only](/docs/policies/ai-gateway-internal-only-inbound)
-> policy for an application that is only called from inside the gateway with
+> [Internal Only](/docs/policies/internal-only-inbound) policy for an
+> application that is only called from inside the gateway with
 > `context.invokeRoute`. Team policy templates can include a locked auth entry
 > so new applications require keys by default.
 

package/docs/policies/ai-gateway-configuration-executor-inbound/doc.md

@@ -205,9 +205,9 @@ Authentication is optional and placement controls its scope:
   key for every application on the route.
 - **Internal applications** — for an application that is only called from inside
   the gateway with `context.invokeRoute`, add
-  [Ensure Gateway Internal Invocation Only](/docs/policies/ai-gateway-internal-only-inbound)
-  to its `inboundPolicyChain` instead of authentication. It rejects every
-  request that arrives over the network and needs no API key.
+  [Internal Only](/docs/policies/internal-only-inbound) to its
+  `inboundPolicyChain` instead of authentication. It rejects every request that
+  arrives over the network and needs no API key.
 
 Use the same placement on each AI Gateway operation that should support
 application-selected chains.

package/docs/policies/ai-gateway-prompt-injection/doc.md

@@ -50,8 +50,7 @@ classification inherits the app's provider credentials, model routing,
 fallbacks, and quotas, and provider keys stay on one app. In this mode:
 
 - `apiKey` is optional. The invocation never leaves the gateway, so give the
-  classifier app the
-  [Ensure Gateway Internal Invocation Only](/docs/policies/ai-gateway-internal-only-inbound)
+  classifier app the [Internal Only](/docs/policies/internal-only-inbound)
   policy — it accepts requests this gateway made itself and rejects everything
   that arrives over the network — and omit `apiKey` entirely. Set it only when
   the classifier app authenticates callers with API keys; it is then sent as

package/docs/policies/ai-gateway-prompt-injection/schema.json

@@ -39,13 +39,13 @@
             "apiKey": {
               "type": "string",
               "title": "API Key",
-              "description": "Credential used to run the classifier. Without `appId` this is the API key for the OpenAI-compatible service at `baseUrl`, and it is required. With `appId` it is optional: omit it when the classifier app runs the Ensure Gateway Internal Invocation Only policy, which authorizes the in-process invocation itself, and set it only when that app authenticates callers with API keys, in which case it is sent as `Authorization: Bearer`.",
+              "description": "Credential used to run the classifier. Without `appId` this is the API key for the OpenAI-compatible service at `baseUrl`, and it is required. With `appId` it is optional: omit it when the classifier app runs the Internal Only policy, which authorizes the in-process invocation itself, and set it only when that app authenticates callers with API keys, in which case it is sent as `Authorization: Bearer`.",
               "examples": ["$env(OPENAI_API_KEY)"]
             },
             "appId": {
               "type": "string",
               "title": "Classifier App ID",
-              "description": "Run the classifier on another AI Gateway app instead of calling an external API directly. The gateway invokes that app in-process — no outbound HTTP hop — so the classifier inherits its provider credentials, model routing, fallbacks and quotas, and provider keys stay on one app. Give that app the Ensure Gateway Internal Invocation Only policy and `apiKey` is not needed at all. When set, `model` must name a routed model as `provider/model` and `baseUrl` must not be set. The target app must not itself run this policy: it would be asked to classify its own classification request, which is rejected as a configuration error rather than silently skipped. Omit to call `baseUrl` directly.",
+              "description": "Run the classifier on another AI Gateway app instead of calling an external API directly. The gateway invokes that app in-process — no outbound HTTP hop — so the classifier inherits its provider credentials, model routing, fallbacks and quotas, and provider keys stay on one app. Give that app the Internal Only policy and `apiKey` is not needed at all. When set, `model` must name a routed model as `provider/model` and `baseUrl` must not be set. The target app must not itself run this policy: it would be asked to classify its own classification request, which is rejected as a configuration error rather than silently skipped. Omit to call `baseUrl` directly.",
               "examples": ["$env(CLASSIFIER_APP_ID)"],
               "x-show-example": false
             },

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

@@ -23,16 +23,21 @@ agentic, document_qa, other) and the built-in classification prompt.
 
 ## Choose a classifier
 
-| Classifier                   | Set               | Use it when                                                                                                                                               |
-| ---------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `classifier.app`             | `appId`, `model`  | You want the classifier to use one of your providers, through an AI Gateway app in this project. The call stays in-process.                               |
-| `classifier.chatCompletions` | `apiKey`, `model` | You want to call an OpenAI-compatible model directly with its own key, without a second AI Gateway app.                                                   |
-| `classifier.jev`             | `apiKey`          | You want a model built for classification. Jev, from TypeSafe, answers typed questions instead of generating text. TypeSafe and OpenRouter both serve it. |
+| Classifier                                | Set               | Use it when                                                                                                                                                                                 |
+| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `classifier.app`                          | `appId`, `model`  | You want the classifier to use one of your providers, through an AI Gateway app in this project. The call stays in-process. Set `adapter: "systemOne"` for Jev and other System One models. |
+| `classifier.chatCompletions` (deprecated) | `apiKey`, `model` | You need to call an OpenAI-compatible endpoint directly with its own key, without a second AI Gateway app.                                                                                  |
+| `classifier.jev` (deprecated)             | `apiKey`          | You need to call Jev, from TypeSafe, directly with its own key. TypeSafe and OpenRouter both serve it.                                                                                      |
 
 The three are mutually exclusive. Setting more than one is rejected with a
 `ConfigurationError` rather than guessed at, because routing on a classifier you
 didn't mean to use would look like it was working.
 
+Use `classifier.app` for new configurations. The direct `chatCompletions` and
+`jev` sections are deprecated: they bypass the classifier app's policy chain,
+budgets, and analytics, and new classifier features are added only to
+`classifier.app`.
+
 ### AI Gateway app
 
 ```json
@@ -44,8 +49,9 @@ didn't mean to use would look like it was working.
 }
 ```
 
-- `appId` — the AI Gateway app whose Chat Completions endpoint runs the
-  classifier.
+- `appId` — the AI Gateway app that runs the classifier.
+- `adapter` — optional: `chatCompletions` (default) or `systemOne`. Selects
+  `/v1/chat/completions` or `/v1/systemone` on that app.
 - `model` — the `providerName/model` that app routes the classifier request to.
 - `apiKey` — optional. See
   [Authenticating the classifier app](#authenticating-the-classifier-app).
@@ -55,7 +61,35 @@ policy runs on. The classifier request never leaves the gateway, so that
 application needs no API key checked at all — put the Ensure Gateway Internal
 Invocation Only policy on it in place of API Key Authentication.
 
-### Chat Completions API
+For Jev registered with your gateway, use the same app path with System One:
+
+```json
+"classifier": {
+  "app": {
+    "appId": "$env(CLASSIFIER_APP_ID)",
+    "adapter": "systemOne",
+    "model": "jev/jev-latest"
+  }
+}
+```
+
+Replace `jev` with your configured provider name. The classifier app resolves
+the provider assignment and owns upstream credentials, routing, DB pricing,
+budget checks, token metering, and analytics. No direct provider key, base URL,
+or pricing configuration is needed in Smart Router. Its result still includes
+the classifier's usage and cost; it does not emit duplicate analytics under the
+calling app.
+
+Smart Router sends its intent and complexity questions to the app and interprets
+the returned System One answers. Omit `classifierPrompt` for this adapter. Keep
+Smart Router off the classifier app's own chain. System One is not a chat-shaped
+request, so choose policies compatible with that endpoint; existing guardrails
+that cannot inspect its shape still reject it according to their configuration.
+
+Prefer this app configuration for registered gateway providers. The direct
+sections below are deprecated and remain only for existing configurations.
+
+### Chat Completions API (deprecated)
 
 ```json
 "classifier": {
@@ -79,7 +113,7 @@ pointing `baseUrl` at the app's URL. `classifier.app` invokes the app
 in-process, and it rejects a classifier app that would call back into this
 policy.
 
-### Jev
+### Jev (deprecated)
 
 ```json
 "classifier": {
@@ -125,23 +159,29 @@ routing applies only when Jev is sure of both. Jev writes no reasons, so
 `profile.reasons` is empty.
 
 Jev takes no system prompt, so setting `classifierPrompt` with `classifier.jev`
-is rejected with a `ConfigurationError`.
+is rejected with a `ConfigurationError`. The same restriction applies to
+`classifier.app.adapter: "systemOne"`.
 
 `chatCompletions` and `jev` call a service outside the gateway with the key you
 configure, and send it the prompt. When that service answers with an error, the
 policy logs the status and its most likely cause but not the response body,
 which can echo the request back, prompt included.
 
+To migrate a direct section, register the provider with the gateway, create a
+classifier app for it, and replace the section with `classifier.app`. Use
+`adapter: "systemOne"` to replace `classifier.jev`. Existing `classifier.app`
+configurations continue to default to Chat Completions when `adapter` is
+omitted. `systemOne` uses the existing Jev request and response contract; it
+does not add support for arbitrary decision APIs.
+
 ## Authenticating the classifier app
 
 The classifier call is made with `context.invokeRoute` and never leaves the
 gateway, so there is no network hop to protect. Give the classifier application
-the
-[Ensure Gateway Internal Invocation Only](/docs/policies/ai-gateway-internal-only-inbound)
-policy instead of AI Gateway Authentication: it accepts requests this gateway
-made itself and rejects everything that arrives over the network. Then omit
-`classifier.app.apiKey` — nothing is sent, and there is no key to rotate or
-leak.
+the [Internal Only](/docs/policies/internal-only-inbound) policy instead of AI
+Gateway Authentication: it accepts requests this gateway made itself and rejects
+everything that arrives over the network. Then omit `classifier.app.apiKey` —
+nothing is sent, and there is no key to rotate or leak.
 
 Set `classifier.app.apiKey` only when the classifier application authenticates
 callers with API keys. It is sent as `Authorization: Bearer`, typically from
@@ -271,9 +311,9 @@ 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).
 
-With `classifier.jev`, the `id` values are the options of Jev's intent question,
-and every `description` is shown to Jev with its option. There is no prompt, so
-`{{intents}}` doesn't apply.
+With `classifier.jev` or `classifier.app.adapter: "systemOne"`, the `id` values
+are the options of Jev's intent question, and every `description` is shown to
+Jev with its option. There is no prompt, so `{{intents}}` doesn't apply.
 
 If the classifier returns an `id` outside this list, Smart Router keeps it as an
 "unknown intent" and caps its confidence just below `minConfidenceForRouting`,
@@ -282,8 +322,10 @@ so it's never eligible for routing.
 ### Custom classifier prompt
 
 `classifierPrompt` replaces the built-in classifier prompt for `classifier.app`
-and `classifier.chatCompletions`. Jev takes no prompt, so it can't be combined
-with `classifier.jev`. It accepts either a string or an array of lines:
+(its default or `chatCompletions` adapter) and `classifier.chatCompletions`.
+`classifier.app.adapter: "systemOne"` and `classifier.jev` take no prompt, so
+combining `classifierPrompt` with either is a configuration error. It accepts
+either a string or an array of lines:
 
 ```json
 {
@@ -326,11 +368,23 @@ interface AIGatewaySmartRouterResult {
     reasons: string[];
   };
   usage: {
-    promptTokens: number;
-    completionTokens: number;
+    inputTokens: number;
+    outputTokens: number;
     totalTokens: number;
+    breakdown?: {
+      uncachedInputTokens: number;
+      cacheReadInputTokens?: number;
+      cacheWriteInput?: Array<{ tokens: number; cacheTtl?: "5m" | "1h" }>;
+      visibleOutputTokens: number;
+      reasoningOutputTokens?: number;
+    };
   };
   classifierModel: string;
+  cost?: {
+    costUsd: number;
+    source: "provider" | "catalog" | "unpriced";
+    accuracy: "exact" | "estimated" | "unpriced";
+  };
   routing: { model?: string };
   durationMs: number;
   promptSource: "user" | "prior-user";
@@ -352,10 +406,11 @@ interface AIGatewaySmartRouterResult {
 }
 ```
 
-With `classifier.jev`, `classifierModel` is the versioned model that answered,
-in the host's naming: `jev-1.13.0` on TypeSafe, or `typesafe/jev-1.13-20260917`
-on OpenRouter. `usage` reports the input and output tokens that the Jev API
-returns as `promptTokens` and `completionTokens`.
+With `classifier.jev` or `classifier.app.adapter: "systemOne"`,
+`classifierModel` is the versioned model that answered, in the host's naming:
+`jev-1.13.0` on TypeSafe, or `typesafe/jev-1.13-20260917` on OpenRouter. `usage`
+reports the input and output tokens that the Jev API returns as `inputTokens`
+and `outputTokens`.
 
 Read it from any policy placed after Smart Router in the chain. Common uses:
 
@@ -441,10 +496,11 @@ These misconfigurations throw a `ConfigurationError` instead, which fails the
 request with a `500` that names the problem. Failing open on them would look
 like smart routing quietly doing nothing:
 
-- More than one section in `classifier`.
+- More than one section in `classifier` (`app`, `chatCompletions`, and `jev`).
 - A deprecated `classifierAppID`, `classifierModel`, or `classifierAppApiKey`
   next to `classifier`.
-- `classifierPrompt` with `classifier.jev`.
+- `classifierPrompt` with `classifier.app.adapter: "systemOne"` or
+  `classifier.jev`.
 - A `classifier.app.appId` that names this app.
 - A classifier app that runs this policy or Akamai AI Firewall.
 
@@ -454,3 +510,30 @@ does not parse, so there is no prompt to classify, and letting it continue would
 present your routing as in effect when it was not. The policy answers a
 `400 ValidationException` in the AWS error envelope, naming the policy. Remove
 the policy from that route to use Bedrock Runtime through it.
+
+### Classifier cost reporting
+
+Use `classifier.app` for DB-backed pricing, metering, analytics and budgets.
+After classification, `AIGatewaySmartRouter.get(context)` exposes token usage
+and cost from the invoked gateway's accounting headers, including its accounted
+input, output, and total tokens and cost accuracy. Smart Router does not
+recompute usage from the provider response for app classifiers. Missing or
+invalid token headers produce zero counts; missing cost headers produce
+`source: "unpriced"`. Responses from older gateways without cost accuracy retain
+a conservative estimate for catalog costs.
+
+Deprecated direct classifiers retain token usage and any validated
+provider-reported cost in the Smart Router result, but do not look up DB prices,
+send gateway analytics, or increment budget meters. If the provider does not
+report a valid cost, the result is `unpriced`; its numeric zero does not mean
+the call was free. No additional pricing configuration is supported for direct
+calls.
+
+App classifier results also include `usage.breakdown` when the gateway has
+canonical accounting detail. It exposes uncached input, cache-read input,
+cache-write input (with TTL when known), visible output, and reasoning output.
+These disjoint categories are already included in `inputTokens` and
+`outputTokens`; do not add them to the totals again. Unreported detail remains
+absent, while an explicitly reported zero is preserved. Missing or malformed
+breakdown headers do not discard aggregate token counts or cost. Smart Router
+does not derive these categories from the provider body or infer cache TTLs.