zuplo 7.6.6 → 7.6.8

package/docs/ai-gateway/custom-policies.mdx

@@ -171,8 +171,9 @@ options exactly.
 
 ## Configure credentials
 
-If a policy needs a credential—say it calls an external moderation API—set it in
-the declaration's options, and let chain entries inherit it:
+If a policy needs a credential—say it calls an external moderation API—store it
+as an [environment variable](../articles/environment-variables.mdx) and
+reference it with `$env(...)` in the declaration's options:
 
 ```json title="config/policies.json"
 {
@@ -182,14 +183,17 @@ the declaration's options, and let chain entries inherit it:
     "export": "default",
     "module": "$import(./modules/my-moderation-policy)",
     "options": {
-      "apiKey": "your-moderation-api-key"
+      "apiKey": "$env(MODERATION_API_KEY)"
     }
   }
 }
 ```
 
 Leave the chain entry's options out so it inherits the declaration's values—an
-entry that sets its own options replaces them completely.
+entry that sets its own options replaces them completely. An entry that does set
+its own options can use `$env(...)` references too, so one declared policy can
+read a different credential or setting per app. See
+[Options and secrets](./policy-chains.mdx#options-and-secrets).
 
 ## Beyond filtering
 

package/docs/ai-gateway/policy-chains.mdx

@@ -90,8 +90,27 @@ an entry with empty options replaces the declared options with an empty object,
 which breaks a policy that has required settings. Omit options entirely to
 inherit.
 
-Keep credentials in the declaration's options and let entries inherit them, so
-the gateway's repository—not app configuration—holds them. See
+Entry options may reference
+[environment variables](../articles/environment-variables.mdx) with
+`$env(VAR_NAME)`, exactly as in `policies.json`. The gateway resolves each
+reference when the chain runs, so a per-app entry can carry its own
+environment-backed value:
+
+```json
+{
+  "name": "my-moderation-policy",
+  "options": {
+    "apiKey": "$env(MODERATION_API_KEY)",
+    "threshold": 0.8
+  }
+}
+```
+
+A reference to an unset variable fails the request with a configuration error
+naming the variable—it never silently resolves to an empty string.
+
+Alternatively, keep credentials in the declaration's options and let entries
+inherit them, so the gateway's repository—not app configuration—holds them. See
 [Configure credentials](./custom-policies.mdx#configure-credentials).
 
 ## Recommended order

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/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -535,9 +535,33 @@ From a chain policy you can:
 
 ## Store secrets safely
 
-Keep credentials and other environment-backed values in the pre-declared
-policy's `handler.options`, then omit `options` from the application chain entry
-to inherit them:
+Application chain options can reference project environment variables. Use a
+standalone reference when the complete option value comes from one variable, or
+embed one or more references in a larger string:
+
+```json
+{
+  "inboundPolicyChain": [
+    {
+      "name": "my-ai-guardrail",
+      "options": {
+        "apiKey": "$env(MY_GUARDRAIL_API_KEY)",
+        "authorization": "Bearer $env(MY_GUARDRAIL_API_KEY)"
+      }
+    }
+  ]
+}
+```
+
+The executor resolves `$env(NAME)` references when it instantiates an enabled
+chain entry. Resolution visits string values recursively through nested objects
+and arrays. Object keys remain literal. If a referenced variable is missing or
+restricted, the executor rejects the configuration with an error that identifies
+the variable and the chain entry; it never substitutes an empty string.
+
+To share the same environment-backed options across applications, keep them in
+the pre-declared policy's `handler.options`, then omit `options` from the
+application chain entry to inherit them:
 
 ```json
 {
@@ -563,9 +587,9 @@ to inherit them:
 }
 ```
 
-Do not place `$env(...)` expressions in application configuration. Environment
-references are resolved when gateway configuration is built, while application
-chains are evaluated when a request arrives.
+Declared `handler.options` use the normal build-time environment resolution.
+Application entry options are resolved at runtime and replace the declaration's
+complete options object; the two objects are not merged.
 
 ## Chain entry reference
 
@@ -578,8 +602,8 @@ Every chain entry supports:
   without running it. Omitted or `true` entries run normally.
 
 Disabled entries are still validated. They must be well-formed, name a declared
-policy, contain no literal `$env(...)` value, and cannot select the
-configuration loader or executor.
+policy, and cannot select the configuration loader or executor. Their options
+are not instantiated, so their environment references are not resolved.
 
 The executor permits repeated entries and cannot infer the behavior of custom or
 wrapper policies. Configuration authors are responsible for avoiding repeated
@@ -606,7 +630,9 @@ Before deploying:
 1. Declare every selectable policy in `config/policies.json`.
 2. Configure application and team policy templates with the policies each app
    may edit or remove.
-3. Put environment-backed values in declared policy options.
+3. Put shared environment-backed values in declared policy options, or use
+   `$env(...)` in application entry option values when each application needs
+   its own complete options object.
 4. Place the configuration loader before the executor on every AI Gateway route
    (or the executor alone when you prefer the combined path). Add AI Gateway
    Authentication to an application's chain for that app only, or before the

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

@@ -24,6 +24,8 @@ 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,
 summarization, translation, qa, conversation, classification, creative_writing,

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

@@ -38,7 +38,8 @@
           "required": [
             "classifierAppID",
             "classifierAppApiKey",
-            "classifierModel"
+            "classifierModel",
+            "modelsByComplexity"
           ],
           "examples": [
             {
@@ -82,8 +83,9 @@
             "modelsByComplexity": {
               "type": "object",
               "title": "Models By Complexity",
-              "description": "Optional `providerName/model` routing by classified complexity. Used only when `smartRoutingEnabled` is true.",
+              "description": "`providerName/model` routing by classified complexity. All of `low`, `medium`, and `high` are required. Used only when `smartRoutingEnabled` is true.",
               "additionalProperties": false,
+              "required": ["low", "medium", "high"],
               "properties": {
                 "low": {
                   "type": "string",

package/package.json

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