zuplo 7.8.24 → 7.9.2

package/docs/policies/{ai-gateway-model-filtering-v2-inbound → ai-gateway-model-filtering-inbound}/doc.md

@@ -60,8 +60,10 @@ These Responses API operations do not have a request body:
 - `DELETE /v1/responses/:responseId`
 
 Because they cannot supply `model`, they require routing to be selected before
-the handler runs. Configure a `completions.allowList` in Model Filtering so its
-first entry supplies the default, or use a custom inbound policy that calls
+the handler runs. Attach AI Gateway Model Override with a
+`models.completions.default` model, configure a `completions.allowList` in Model
+Filtering so its first entry supplies the default, or use a custom inbound
+policy that calls
 `AIGatewayModelRouting.set(context, { completions: "providerName/model" })`.
 Without preselected routing, the handler returns an OpenAI-compatible 400
 `invalid_request_error` with this configuration guidance.
@@ -105,10 +107,10 @@ capability to add.
 
 ```json
 {
-  "name": "ai-gateway-model-filtering-v2-inbound",
-  "policyType": "ai-gateway-model-filtering-v2",
+  "name": "ai-gateway-model-filtering-inbound",
+  "policyType": "ai-gateway-model-filtering",
   "handler": {
-    "export": "AIGatewayModelFilteringV2InboundPolicy",
+    "export": "AIGatewayModelFilteringInboundPolicy",
     "module": "$import(@zuplo/runtime)",
     "options": {
       "models": {

package/docs/policies/{ai-gateway-model-filtering-v2-inbound → ai-gateway-model-filtering-inbound}/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-model-filtering-v2-inbound.json",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-model-filtering-inbound.json",
   "type": "object",
   "title": "AI Gateway Model Filtering",
   "isDeprecated": false,
@@ -10,7 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
-  "policyType": "ai-gateway-model-filtering-v2",
+  "policyType": "ai-gateway-model-filtering",
   "products": ["ai-gateway"],
   "description": "Matches AI Gateway requests against curated allow lists or open block lists, then stores the winning model reference for the route handler.",
   "deprecatedMessage": "",
@@ -22,7 +22,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "AIGatewayModelFilteringV2InboundPolicy",
+          "const": "AIGatewayModelFilteringInboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -30,9 +30,8 @@
           "description": "The module containing the policy"
         },
         "options": {
-          "x-zuplo-policy-type": "ai-gateway-model-filtering-v2",
           "type": "object",
-          "title": "AIGatewayModelFilteringV2InboundPolicyOptions",
+          "title": "AIGatewayModelFilteringInboundPolicyOptions",
           "description": "Options for allowing or blocking providerName/model references for each AI Gateway capability.",
           "additionalProperties": false,
           "required": ["models"],
@@ -146,7 +145,7 @@
       },
       "examples": [
         {
-          "export": "AIGatewayModelFilteringV2InboundPolicy",
+          "export": "AIGatewayModelFilteringInboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
             "models": {

package/docs/policies/ai-gateway-model-override-inbound/doc.md

@@ -0,0 +1,154 @@
+Use this policy when the gateway operator, not the client, decides which model
+an AI Gateway route uses. Each capability picks one mode:
+
+- `force` sends every request to the configured model. A model in the request
+  body is ignored.
+- `default` supplies the configured model only when the request omits `model`. A
+  request that selects a model keeps its selection.
+
+`providerName` is the Provider Name configured in the Zuplo Portal. The text
+after the first slash is the provider-specific model ID, so model IDs may
+contain additional slashes.
+
+## Choosing a mode
+
+Use `force` to:
+
+- Pin a route to one vetted model regardless of client input.
+- Repoint existing traffic at a new model without a client release.
+- Expose a stable route like `/fast/v1/chat/completions` whose model you swap
+  server-side.
+
+Use `default` to:
+
+- Let clients omit `model` while keeping full choice for clients that send one.
+- Give Responses management operations (`GET`/`DELETE /v1/responses/*`), which
+  have no request body, the routing they require.
+
+## Policy order
+
+Place Model Override first among the model-selection policies:
+
+```text
+Model Override -> Model Filtering -> Fallback Model -> AI Gateway handler
+```
+
+- A selection made by an earlier policy is never overwritten. When this policy
+  sets the selection, AI Gateway Model Filtering leaves it unchanged, so a
+  forced model does not also need an allow-list entry.
+- In `default` mode, a request that selects its own model passes through
+  unchanged, and Model Filtering or the handler validates it as usual. The
+  default never masks an invalid request model; a malformed value is still
+  rejected downstream with a 400 response.
+- AI Gateway Fallback Model placed after this policy enriches the selection with
+  `fallback` and `quotaFallback` models. Keep fallback fields in that policy;
+  this one accepts plain `providerName/model` strings only.
+- A custom inbound policy placed before this one stays authoritative. For
+  example, an experiment policy can select routing for a fraction of traffic and
+  let `force` catch the rest.
+
+## Options
+
+`models` must contain `completions`, `embeddings`, or both. Each capability sets
+exactly one of:
+
+- `force` - the model every request uses.
+- `default` - the model used only when the request omits `model`.
+
+Values are plain `providerName/model` strings. Unsupported fields and malformed
+references are rejected as configuration errors naming the field. If the policy
+is attached but the route's capability has no rule, the policy passes the
+request through unchanged.
+
+## Force example
+
+```json
+{
+  "name": "ai-gateway-model-override-inbound",
+  "policyType": "ai-gateway-model-override",
+  "handler": {
+    "export": "AIGatewayModelOverrideInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "models": {
+        "completions": {
+          "force": "openai/gpt-5"
+        }
+      }
+    }
+  }
+}
+```
+
+## Default example
+
+```json
+{
+  "models": {
+    "completions": {
+      "default": "anthropic/claude-haiku-4-5"
+    },
+    "embeddings": {
+      "default": "openai/text-embedding-3-small"
+    }
+  }
+}
+```
+
+## Request behavior
+
+| Situation                                          | `force`                          | `default`                                       |
+| -------------------------------------------------- | -------------------------------- | ----------------------------------------------- |
+| Request omits `model`                              | Configured model is selected.    | Configured model is selected.                   |
+| Request selects a model                            | Configured model replaces it.    | The request's model continues downstream.       |
+| Request model is malformed                         | Configured model is selected.    | Passed through; rejected downstream with a 400. |
+| Bodyless request (Responses management operations) | Configured model is selected.    | Configured model is selected.                   |
+| An earlier policy already selected routing         | Skipped; earlier selection wins. | Skipped; earlier selection wins.                |
+| Route capability has no rule                       | Passed through unchanged.        | Passed through unchanged.                       |
+
+When the policy selects the configured model, the same routing validation used
+everywhere else applies: the Provider Name must be configured, the model must be
+available for the route's capability, and the Provider Assignment must have
+usable credentials. A configured model that fails this validation is reported as
+this policy's configuration error, naming the exact option such as
+`options.models.completions.force`.
+
+## Native routes
+
+`/v1/responses` requires a Provider Name backed by OpenAI, and `/v1/messages`
+requires one backed by Anthropic. A configured model that selects an
+incompatible provider type is a configuration error on every request it applies
+to, so the policy reports it as one, naming the option to fix.
+
+## Observability
+
+Responses report the model that actually served the request in their `model`
+field, so a client can always see that an override applied. The policy also
+writes a debug-level log entry with `requestedModel` and `forcedModel` when a
+forced model replaces a request's differing selection.
+
+## Write your own override policy
+
+Everything this policy does is built on the public
+`AIGatewayModelRouting.set(context, routing)` primitive. Use a custom inbound
+policy instead when the override depends on request data, for example routing by
+header:
+
+```typescript
+import {
+  AIGatewayModelRouting,
+  type ZuploContext,
+  type ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function overrideModel(
+  request: ZuploRequest,
+  context: ZuploContext
+) {
+  const tier = request.headers.get("x-plan-tier");
+  await AIGatewayModelRouting.set(context, {
+    completions: tier === "pro" ? "openai/gpt-5" : "openai/gpt-5-mini",
+  });
+  return request;
+}
+```

package/docs/policies/ai-gateway-model-override-inbound/intro.md

@@ -0,0 +1,5 @@
+AI Gateway Model Override pins the model an AI Gateway route uses. Set `force`
+to send every request to one model no matter what the client selects, or
+`default` to supply a model only when the request omits one. Place it before AI
+Gateway Model Filtering and AI Gateway Fallback Model; a selection made by an
+earlier policy is never overwritten.

package/docs/policies/ai-gateway-model-override-inbound/schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-model-override-inbound.json",
+  "type": "object",
+  "title": "AI Gateway Model Override",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": true,
+  "isHidden": false,
+  "requiresAI": true,
+  "policyType": "ai-gateway-model-override",
+  "products": ["ai-gateway"],
+  "description": "Forces one model for every request, or supplies a default model when a request omits one, then stores that selection for the AI Gateway handler.\n\nAn earlier policy's model selection is never overwritten, so a custom routing policy placed before this one stays authoritative.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AIGatewayModelOverrideInboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "title": "AIGatewayModelOverrideInboundPolicyOptions",
+          "description": "Options for forcing one model or supplying a default model for each AI Gateway capability.",
+          "additionalProperties": false,
+          "required": ["models"],
+          "properties": {
+            "models": {
+              "type": "object",
+              "title": "Models",
+              "description": "Override rules grouped by AI Gateway capability.",
+              "additionalProperties": false,
+              "minProperties": 1,
+              "properties": {
+                "completions": {
+                  "title": "Completions Override",
+                  "description": "Rule for chat completions, Responses, and Anthropic Messages requests.",
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["force"],
+                      "properties": {
+                        "force": {
+                          "title": "Forced Model",
+                          "description": "The model every request uses; a request-selected model is ignored.",
+                          "type": "string",
+                          "pattern": "^[^/\\s]+/.+$"
+                        }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["default"],
+                      "properties": {
+                        "default": {
+                          "title": "Default Model",
+                          "description": "The model used only when a request does not select one.",
+                          "type": "string",
+                          "pattern": "^[^/\\s]+/.+$"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "embeddings": {
+                  "title": "Embeddings Override",
+                  "description": "Rule for embedding requests.",
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["force"],
+                      "properties": {
+                        "force": {
+                          "title": "Forced Model",
+                          "description": "The model every request uses; a request-selected model is ignored.",
+                          "type": "string",
+                          "pattern": "^[^/\\s]+/.+$"
+                        }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["default"],
+                      "properties": {
+                        "default": {
+                          "title": "Default Model",
+                          "description": "The model used only when a request does not select one.",
+                          "type": "string",
+                          "pattern": "^[^/\\s]+/.+$"
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AIGatewayModelOverrideInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "models": {}
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/{comet-opik-tracing-v2-inbound → ai-gateway-opik-tracing-inbound}/doc.md

@@ -21,10 +21,10 @@ chain that should emit traces:
 
 ```json
 {
-  "name": "comet-opik-tracing-v2-inbound",
-  "policyType": "comet-opik-tracing-v2",
+  "name": "ai-gateway-opik-tracing-inbound",
+  "policyType": "ai-gateway-opik-tracing",
   "handler": {
-    "export": "CometOpikTracingV2InboundPolicy",
+    "export": "AIGatewayOpikTracingInboundPolicy",
     "module": "$import(@zuplo/runtime)",
     "options": {
       "apiKey": "$env(COMET_OPIK_API_KEY)",

package/docs/policies/{comet-opik-tracing-v2-inbound → ai-gateway-opik-tracing-inbound}/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/comet-opik-tracing-v2-inbound.json",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-opik-tracing-inbound.json",
   "type": "object",
   "title": "Comet Opik Tracing",
   "isDeprecated": false,
@@ -10,7 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
-  "policyType": "comet-opik-tracing-v2",
+  "policyType": "ai-gateway-opik-tracing",
   "products": ["ai-gateway"],
   "description": "Comet Opik Tracing Inbound Policy",
   "deprecatedMessage": "",
@@ -22,7 +22,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "CometOpikTracingV2InboundPolicy",
+          "const": "AIGatewayOpikTracingInboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -30,8 +30,7 @@
           "description": "The module containing the policy"
         },
         "options": {
-          "x-zuplo-policy-type": "comet-opik-tracing-v2",
-          "title": "Comet Opik Tracing",
+          "title": "AIGatewayOpikTracingInboundPolicyOptions",
           "description": "Track AI Gateway requests and responses using Comet Opik's LLM observability platform.",
           "type": "object",
           "examples": [
@@ -88,7 +87,7 @@
       },
       "examples": [
         {
-          "export": "CometOpikTracingV2InboundPolicy",
+          "export": "AIGatewayOpikTracingInboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
             "apiKey": "$env(COMET_OPIK_API_KEY)",

package/docs/policies/{ai-gateway-semantic-cache-v2-inbound → ai-gateway-semantic-cache-inbound}/schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-semantic-cache-v2-inbound.json",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-semantic-cache-inbound.json",
   "type": "object",
   "title": "AI Gateway Semantic Cache",
   "isDeprecated": false,
@@ -10,7 +10,7 @@
   "isBeta": false,
   "isHidden": false,
   "requiresAI": true,
-  "policyType": "ai-gateway-semantic-cache-v2",
+  "policyType": "ai-gateway-semantic-cache",
   "products": ["ai-gateway"],
   "description": "AI Gateway Semantic Cache policy. This inbound policy looks up the semantic cache on entry and, on a miss, registers a response-sending hook to write the upstream response back into the cache.\n\nCaching parameters (semanticTolerance, expirationSecondsTtl, namespace, recentMessageCount) come from the policy options, and presence in the route's chain is what enables it. An id from the authenticated app configuration always provides the cache namespace so application-supplied options cannot cross tenant partitions. The cache key covers the system prompt plus the last `recentMessageCount` messages (default 1) — applied when storing and when matching — so multi-turn conversations can hit entries cached from earlier, shorter ones.\n\nCache outcomes are reported on the response via the RFC 9211 `Cache-Status` header under the cache name `zp-aigw-sem-cache` (hit: `zp-aigw-sem-cache; hit; detail=\"similarity=0.93\"`; miss: `zp-aigw-sem-cache; fwd=miss; stored`). Responses also include the `x-ai-gateway-cache: HIT|MISS` and `x-ai-gateway-cache-similarity` headers.",
   "deprecatedMessage": "",
@@ -22,7 +22,7 @@
       "required": ["export", "module", "options"],
       "properties": {
         "export": {
-          "const": "AIGatewaySemanticCacheV2InboundPolicy",
+          "const": "AIGatewaySemanticCacheInboundPolicy",
           "description": "The name of the exported type"
         },
         "module": {
@@ -30,7 +30,6 @@
           "description": "The module containing the policy"
         },
         "options": {
-          "x-zuplo-policy-type": "ai-gateway-semantic-cache-v2",
           "type": "object",
           "title": "AIGatewaySemanticCacheInboundPolicyOptions",
           "description": "Options for the AI Gateway Semantic Cache policy. Configured inline in policies.json; the policy reads nothing from the AI Gateway configuration to decide whether to cache.",
@@ -106,7 +105,7 @@
       },
       "examples": [
         {
-          "export": "AIGatewaySemanticCacheV2InboundPolicy",
+          "export": "AIGatewaySemanticCacheInboundPolicy",
           "module": "$import(@zuplo/runtime)",
           "options": {
             "semanticTolerance": 0.2,

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

@@ -53,8 +53,8 @@ within one app, or between two — is never mistaken for smart routing that is
 simply doing nothing.
 
 The classifier application must not run
-[Akamai AI Firewall](/docs/policies/akamai-ai-firewall-v2-inbound) either. That
-firewall would inspect the internal classification call as if it were a
+[Akamai AI Firewall](/docs/policies/ai-gateway-akamai-firewall-inbound) either.
+That firewall would inspect the internal classification call as if it were a
 completion request — scanning the classifier's system prompt and JSON-only
 response for injection/malicious-content patterns — and a resulting denial makes
 Smart Router fail open, indistinguishable from smart routing quietly doing

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

@@ -30,7 +30,6 @@
           "description": "The module containing the policy"
         },
         "options": {
-          "x-zuplo-policy-type": "ai-gateway-smart-router",
           "type": "object",
           "title": "AIGatewaySmartRouterInboundPolicyOptions",
           "description": "Options for the Smart Router policy: classify the last user prompt with a dedicated classifier AI Gateway app, then optionally route by complexity.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.8.24",
+  "version": "7.9.2",
   "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.8.24",
-    "@zuplo/core": "7.8.24",
-    "@zuplo/runtime": "7.8.24",
-    "@zuplo/test": "7.8.24"
+    "@zuplo/cli": "7.9.2",
+    "@zuplo/core": "7.9.2",
+    "@zuplo/runtime": "7.9.2",
+    "@zuplo/test": "7.9.2"
   }
 }

package/docs/policies/ai-gateway-configuration-loader-v2-inbound/intro.md

@@ -1,6 +0,0 @@
-The AI Gateway Configuration Loader loads each application's configuration into
-the request-scoped channel — reusing the channel from route-level
-`ai-gateway-auth-v2-inbound` when present, otherwise fetching by path `app_id`.
-It does not run the application's policy chain; place
-`ai-gateway-configuration-executor-v2-inbound` after it for that. When this
-loader is omitted, the executor still loads configuration itself.