zuplo 7.2.3 → 7.2.4

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

@@ -0,0 +1,442 @@
+# AI Gateway Configuration Executor
+
+The AI Gateway Configuration Executor loads each application's configuration
+(when auth or `ai-gateway-configuration-loader-v2-inbound` has not already) and
+runs its ordered inbound policy chain. Configuration comes from route-level
+`ai-gateway-auth-v2-inbound` or the configuration loader when either already
+ran, otherwise from the route's `app_id` path parameter via Gateway Service.
+Applications can still require API keys later by including
+`ai-gateway-auth-v2-inbound` in their own `inboundPolicyChain`.
+
+Prefer placing the dedicated configuration loader before this executor on the
+route. When the loader is omitted, this executor still loads configuration
+itself before running the chain.
+
+The gateway owner remains in control:
+
+- Every selectable policy must be declared in `config/policies.json`.
+- Application and team policy templates determine which entries applications may
+  edit or remove before the resulting chain reaches the gateway.
+
+## How application chains behave
+
+| Application configuration              | Result                               |
+| -------------------------------------- | ------------------------------------ |
+| No application configuration           | No application-selected policies run |
+| `inboundPolicyChain` is absent or `[]` | No application-selected policies run |
+| `inboundPolicyChain` contains entries  | Entries run in the listed order      |
+| An entry has `enabled: false`          | That entry is skipped                |
+
+If a policy returns a response, that response is sent immediately and later
+entries do not run. If a chain is invalid, the request fails closed with an
+error that identifies the entry to fix.
+
+This inbound executor does not run `outboundPolicyChain`. That field is reserved
+for an outbound configuration executor on the response pipeline.
+
+## Build an AI Gateway from scratch
+
+### 1. Declare the policies
+
+Add the optional configuration loader, the executor, and every policy an
+application may select to `config/policies.json`. Optionally declare AI Gateway
+Authentication when applications or routes will authenticate with application
+API keys.
+
+The following example allows applications to select model filtering and semantic
+caching. It does not assign either policy automatically; each application
+chooses the policies it needs in its `inboundPolicyChain`:
+
+```json
+{
+  "policies": [
+    {
+      "name": "ai-gateway-auth-v2-inbound",
+      "policyType": "ai-gateway-auth-v2",
+      "handler": {
+        "export": "AIGatewayAuthV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "cacheTtlSeconds": 60
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-configuration-loader-v2-inbound",
+      "policyType": "ai-gateway-configuration-loader-v2",
+      "handler": {
+        "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "cacheTtlSeconds": 60
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-configuration-executor-v2-inbound",
+      "policyType": "ai-gateway-configuration-executor-v2",
+      "handler": {
+        "export": "AIGatewayConfigurationExecutorV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "cacheTtlSeconds": 60
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-metering-v2-inbound",
+      "policyType": "ai-gateway-metering-v2",
+      "handler": {
+        "export": "AIGatewayMeteringV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {}
+      }
+    },
+    {
+      "name": "ai-gateway-model-filtering-v2-inbound",
+      "policyType": "ai-gateway-model-filtering-v2",
+      "handler": {
+        "export": "AIGatewayModelFilteringV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "models": {
+            "completions": {
+              "allowList": ["openai/gpt-5-mini", "anthropic/claude-sonnet-4-6"]
+            }
+          }
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-fallback-model-v2-inbound",
+      "policyType": "ai-gateway-fallback-model-v2",
+      "handler": {
+        "export": "AIGatewayFallbackModelV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "models": {
+            "completions": {
+              "fallback": "anthropic/claude-sonnet-4-6"
+            }
+          },
+          "fallbackTimeoutSeconds": 60
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-semantic-cache-v2-inbound",
+      "policyType": "ai-gateway-semantic-cache-v2",
+      "handler": {
+        "export": "AIGatewaySemanticCacheV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "semanticTolerance": 0.4,
+          "expirationSecondsTtl": 3600
+        }
+      }
+    }
+  ]
+}
+```
+
+Chain entries use declaration names, not policy types. The executor rejects
+undeclared policies and prevents direct or transitive re-entry into the
+configuration loader or executor. Use application and team policy templates to
+control which declared policies an application may edit or remove.
+
+### 2. Add the loader and executor to the route
+
+Place the loader before the executor on each AI Gateway route. The loader loads
+configuration from the route's `app_id` path parameter (or reuses the channel
+when route-level auth already ran); the executor then runs that application's
+`inboundPolicyChain`. The AI Gateway handler runs after the selected inbound
+chain:
+
+```json
+{
+  "x-zuplo-route": {
+    "corsPolicy": "none",
+    "handler": {
+      "export": "aiGatewayHandlerV2",
+      "module": "$import(@zuplo/runtime)",
+      "options": {}
+    },
+    "policies": {
+      "inbound": [
+        "ai-gateway-configuration-loader-v2-inbound",
+        "ai-gateway-configuration-executor-v2-inbound"
+      ]
+    }
+  }
+}
+```
+
+Routes that list only the executor keep working — the executor loads
+configuration when the channel is empty.
+
+Authentication is optional and placement controls its scope:
+
+- **App-level** — add `ai-gateway-auth-v2-inbound` to an application's
+  `inboundPolicyChain`. Only that application requires an API key.
+- **Route-level** — add `ai-gateway-auth-v2-inbound` on the route **before** the
+  loader (or before the executor on executor-only routes). That requires an API
+  key for every application on the route.
+
+Use the same placement on each AI Gateway operation that should support
+application-selected chains.
+
+### 3. Set an application's policy chain
+
+An application can inherit the options from `policies.json`. Include
+`ai-gateway-auth-v2-inbound` when this application should require an API key:
+
+```json
+{
+  "inboundPolicyChain": [
+    {
+      "name": "ai-gateway-auth-v2-inbound"
+    },
+    {
+      "name": "ai-gateway-model-filtering-v2-inbound"
+    },
+    {
+      "name": "ai-gateway-fallback-model-v2-inbound"
+    },
+    {
+      "name": "ai-gateway-metering-v2-inbound",
+      "options": {
+        "limits": {
+          "requests": {
+            "daily": {
+              "enabled": true,
+              "limit": 1000
+            }
+          }
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-semantic-cache-v2-inbound"
+    }
+  ]
+}
+```
+
+Place authentication first when the app requires a key, then model filtering,
+fallback-model, and metering so metering can activate the resolved quota
+fallback. Put policies that may short-circuit, such as semantic cache, after
+metering so those requests still count toward request limits.
+
+An application can also provide a complete options object for an entry:
+
+```json
+{
+  "inboundPolicyChain": [
+    {
+      "name": "ai-gateway-model-filtering-v2-inbound",
+      "options": {
+        "models": {
+          "completions": {
+            "allowList": ["anthropic/claude-sonnet-4-6"]
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+Entry options replace the declaration's entire options object; fields are not
+merged. Omit `options` to inherit the complete `handler.options` value from
+`policies.json`.
+
+An entry may also carry portal/template ACL metadata in `permissions`. The
+executor accepts this field and ignores it when running the chain; unknown keys
+under `permissions` fail closed:
+
+```json
+{
+  "inboundPolicyChain": [
+    {
+      "name": "ai-gateway-model-filtering-v2-inbound",
+      "permissions": {
+        "canEdit": true,
+        "canRemove": false
+      },
+      "options": {
+        "models": {
+          "completions": {
+            "allowList": ["anthropic/claude-sonnet-4-6"]
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+| `permissions` field | Meaning (portal/templates)                           |
+| ------------------- | ---------------------------------------------------- |
+| `canEdit`           | Whether the application may edit the entry's options |
+| `canRemove`         | Whether the application may remove the entry         |
+
+Omit `permissions`, or either flag, when the portal does not need to record that
+constraint on the stored chain.
+
+## Write a custom policy for the chain
+
+A chain entry can run any declared custom policy. The policy uses the standard
+inbound policy signature and receives its options from the chain entry (or the
+declaration, when the entry omits `options`). Entry-owned options are
+deep-copied for each invocation, so mutating them is safe. Inherited declaration
+options are passed through unchanged to match static route behavior; do not
+mutate them.
+
+```ts
+import {
+  AIGatewayModelRouting,
+  AIGatewayModels,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+interface CheapestModelOptions {
+  providers?: string[];
+}
+
+export default async function cheapestModel(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: CheapestModelOptions
+): Promise<ZuploRequest | Response> {
+  // The authenticated application: sub is the application name, data its
+  // metadata.
+  context.log.info(`Routing for application ${request.user?.sub}`);
+
+  // Read the live provider and model catalog. Credentials are never returned.
+  const allowed = options.providers ?? ["openai", "anthropic"];
+  const candidates = (await AIGatewayModels.load(context))
+    .filter(({ providerName }) => allowed.includes(providerName.toLowerCase()))
+    .flatMap((provider) =>
+      provider.models.map((model) => ({
+        providerName: provider.providerName,
+        model,
+      }))
+    )
+    .filter(
+      ({ model }) =>
+        model.capability === "completions" && model.status === "active"
+    )
+    .sort(
+      (left, right) =>
+        left.model.inputCostPerToken +
+        left.model.outputCostPerToken -
+        (right.model.inputCostPerToken + right.model.outputCostPerToken)
+    );
+
+  const cheapest = candidates[0];
+  if (!cheapest) {
+    // Returning a Response short-circuits the chain and answers the request.
+    return new Response("No eligible model", { status: 503 });
+  }
+
+  // Select the model the gateway calls for this request.
+  await AIGatewayModelRouting.set(context, {
+    completions: `${cheapest.providerName}/${cheapest.model.model}`,
+  });
+  return request;
+}
+```
+
+From a chain policy you can:
+
+- **Read the calling application** from `request.user`: `sub` is the application
+  name and `data` its metadata.
+- **Read the model catalog** with `AIGatewayModels.load(context)`.
+- **Choose the model for the request** with
+  `AIGatewayModelRouting.set(context, routing)`, and read the current selection
+  with `AIGatewayModelRouting.get(context)`.
+- **Block or answer the request** by returning a `Response`; later chain entries
+  do not run.
+- **Receive settings** through the chain entry's `options`, exactly like the
+  built-in policies.
+
+## 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:
+
+```json
+{
+  "name": "my-ai-guardrail",
+  "policyType": "custom-code-inbound",
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/my-ai-guardrail)",
+    "options": {
+      "apiKey": "$env(MY_GUARDRAIL_API_KEY)"
+    }
+  }
+}
+```
+
+```json
+{
+  "inboundPolicyChain": [
+    {
+      "name": "my-ai-guardrail"
+    }
+  ]
+}
+```
+
+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.
+
+## Chain entry reference
+
+Every chain entry supports:
+
+- `name` (required): Name of a declaration in `policies.json`.
+- `options` (optional): Complete replacement options for this invocation. Omit
+  it to inherit the declaration's options.
+- `enabled` (optional): Set to `false` to keep an entry in the configuration
+  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.
+
+The executor permits repeated entries and cannot infer the behavior of custom or
+wrapper policies. Configuration authors are responsible for avoiding repeated
+invocation when a policy is not safe to run more than once.
+
+## Empty chains
+
+An application without an `inboundPolicyChain`, or with an explicit empty array,
+runs no application-selected policies:
+
+```json
+{
+  "inboundPolicyChain": []
+}
+```
+
+Ensure the loaded configuration supplies every policy required for the request,
+or attach required policies directly to the route.
+
+## Configuration checklist
+
+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.
+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
+   loader on the route to require keys for every app.
+5. Ensure every application chain includes the policies required for that route.

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

@@ -0,0 +1,14 @@
+The AI Gateway Configuration Executor loads each application's configuration
+(when auth or the configuration loader has not already) and runs an ordered
+inbound policy chain assembled from policies declared by the gateway.
+Applications may also include authentication in their own chain. This makes it
+possible to offer different routing, caching, guardrail, metering, and tracing
+behavior from one AI Gateway deployment.
+
+Prefer placing `ai-gateway-configuration-loader-v2-inbound` before this executor
+on the route so loading and chain execution stay separate. When the loader is
+omitted, this executor still loads configuration itself.
+
+The gateway owner decides which policy declarations are available, while
+application and team templates control which entries an application may edit or
+remove. Each request carries the resulting chain and policy options.

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-configuration-executor-v2-inbound.json",
+  "type": "object",
+  "title": "AI Gateway Configuration Executor",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": true,
+  "policyType": "ai-gateway-configuration-executor-v2",
+  "products": ["ai-gateway"],
+  "description": "Loads the app configuration for the request (when auth or the configuration loader has not already) and runs the inbound policy chain from that configuration.\n\nPlace this policy on AI Gateway routes after optional authentication and optional `ai-gateway-configuration-loader-v2-inbound`. When either of those already populated the app-configuration channel, this policy reuses it. Otherwise it loads the configuration with the route's `app_id` path parameter. Applications select from policies pre-declared by the gateway. Applications without a `inboundPolicyChain`, or with an empty chain, run no application-selected policies. Entry options replace the declaration's options as a complete object; omit them to inherit the declaration, including environment-backed credentials. Each occurrence receives a private deep copy of its entry options, so a policy mutating its options cannot corrupt the cached app configuration.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AIGatewayConfigurationExecutorV2InboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "x-zuplo-policy-type": "ai-gateway-configuration-executor-v2",
+          "title": "AIGatewayConfigurationExecutorV2InboundPolicyOptions",
+          "type": "object",
+          "description": "Options for loading each application's AI Gateway configuration and running its inbound policy chain.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "cacheTtlSeconds": {
+              "type": "number",
+              "default": 10,
+              "minimum": 2,
+              "description": "The time in seconds to cache app configurations loaded by app\\_id. Defaults to 10 seconds when omitted. Higher values decrease latency; lower values pick up portal changes sooner. Cached results remain valid until the cache expires even if the configuration changes in the portal. This cache is only used when neither ai-gateway-auth-v2-inbound nor ai-gateway-configuration-loader-v2-inbound already loaded the configuration for the request."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AIGatewayConfigurationExecutorV2InboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheTtlSeconds": 10
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,105 @@
+# AI Gateway Configuration Loader
+
+The AI Gateway Configuration Loader loads each application's configuration into
+the request-scoped app-configuration channel. Configuration comes from
+route-level `ai-gateway-auth-v2-inbound` when that policy already ran, otherwise
+from the route's `app_id` path parameter via Gateway Service.
+
+This policy does **not** run `inboundPolicyChain`. Pair it with
+`ai-gateway-configuration-executor-v2-inbound` when applications select policies
+dynamically. If you omit this loader, the executor still loads configuration
+before running the chain.
+
+Applications can still require API keys later by including
+`ai-gateway-auth-v2-inbound` in their own `inboundPolicyChain`.
+
+## Build an AI Gateway from scratch
+
+### 1. Declare the policies
+
+Add the loader, the executor, and every policy an application may select to
+`config/policies.json`:
+
+```json
+{
+  "policies": [
+    {
+      "name": "ai-gateway-configuration-loader-v2-inbound",
+      "policyType": "ai-gateway-configuration-loader-v2",
+      "handler": {
+        "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "cacheTtlSeconds": 60
+        }
+      }
+    },
+    {
+      "name": "ai-gateway-configuration-executor-v2-inbound",
+      "policyType": "ai-gateway-configuration-executor-v2",
+      "handler": {
+        "export": "AIGatewayConfigurationExecutorV2InboundPolicy",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "cacheTtlSeconds": 60
+        }
+      }
+    }
+  ]
+}
+```
+
+`cacheTtlSeconds` sets how long a loaded app configuration is cached by
+`app_id`. It defaults to 10 seconds and accepts any value of 2 seconds or more —
+raise it to cut Gateway Service calls, lower it to pick up portal changes
+sooner. The AI Gateway project template ships 5 seconds.
+
+Neither the loader nor the executor may appear in an application's
+`inboundPolicyChain`. The executor rejects those entries fail-closed.
+
+### 2. Add the loader and executor to the route
+
+Place the loader before the executor on each AI Gateway route:
+
+```json
+{
+  "x-zuplo-route": {
+    "corsPolicy": "none",
+    "handler": {
+      "export": "aiGatewayHandlerV2",
+      "module": "$import(@zuplo/runtime)",
+      "options": {}
+    },
+    "policies": {
+      "inbound": [
+        "ai-gateway-configuration-loader-v2-inbound",
+        "ai-gateway-configuration-executor-v2-inbound"
+      ]
+    }
+  }
+}
+```
+
+Authentication is optional and placement controls its scope:
+
+- **App-level** — add `ai-gateway-auth-v2-inbound` to an application's
+  `inboundPolicyChain`. Only that application requires an API key.
+- **Route-level** — add `ai-gateway-auth-v2-inbound` on the route **before** the
+  loader. That requires an API key for every application on the route.
+
+### Executor-only routes
+
+Routes that list only `ai-gateway-configuration-executor-v2-inbound` keep
+working. The executor loads configuration when the channel is empty, then runs
+the chain. Use the dedicated loader when you want other route policies between
+load and chain execution, or a clearer separation of concerns.
+
+## Configuration checklist
+
+Before deploying:
+
+1. Declare the loader (optional but recommended), the executor, and every
+   selectable policy in `config/policies.json`.
+2. Put the loader before the executor on every AI Gateway route — or put only
+   the executor when you prefer the combined path.
+3. Do not add the loader or executor to any application's `inboundPolicyChain`.

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

@@ -0,0 +1,6 @@
+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.

package/docs/policies/ai-gateway-configuration-loader-v2-inbound/schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://cdn.zuplo.com/policies/runtime/schemas/ai-gateway-configuration-loader-v2-inbound.json",
+  "type": "object",
+  "title": "AI Gateway Configuration Loader",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "requiresAI": true,
+  "policyType": "ai-gateway-configuration-loader-v2",
+  "products": ["ai-gateway"],
+  "description": "Loads the AI Gateway app configuration for the request into the request-scoped channel and does nothing else.\n\nPlace this policy on AI Gateway routes before `ai-gateway-configuration-executor-v2-inbound` when you want configuration loading separated from chain execution. When `ai-gateway-auth-v2-inbound` already populated the channel, this policy reuses it. Otherwise it loads the configuration with the route's `app_id` path parameter.\n\nIf this policy is omitted, the configuration executor still loads configuration itself before running the application chain.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "AIGatewayConfigurationLoaderV2InboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "x-zuplo-policy-type": "ai-gateway-configuration-loader-v2",
+          "title": "AIGatewayConfigurationLoaderV2InboundPolicyOptions",
+          "type": "object",
+          "description": "Options for loading each application's AI Gateway configuration into the request-scoped channel.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "cacheTtlSeconds": {
+              "type": "number",
+              "default": 10,
+              "minimum": 2,
+              "description": "The time in seconds to cache app configurations loaded by app\\_id. Defaults to 10 seconds when omitted. Higher values decrease latency; lower values pick up portal changes sooner. Cached results remain valid until the cache expires even if the configuration changes in the portal. When ai-gateway-auth-v2-inbound already loaded the configuration for the request, this cache is not used."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "cacheTtlSeconds": 10
+          }
+        }
+      ]
+    }
+  }
+}