zuplo 7.13.2 → 7.13.3

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -146,11 +146,10 @@ const { text } = await generateText({
 
 ### xAI
 
-Call `xai.chat(...)` rather than `xai(...)`. The bare callable targets xAI's
-Responses API, and xAI's models do not serve `/v1/responses` through the
-gateway—an xAI model sent there returns a `400`. The endpoint is
-capability-gated per model rather than restricted to one provider, so which
-models reach it is the matrix in [AI Providers](../providers.mdx).
+Use either `xai(...)` or `xai.chat(...)`. The bare callable targets xAI's
+Responses API (`/v1/responses`), and `xai.chat(...)` targets
+`/v1/chat/completions`. Use `xai(...)` for xAI's server-side tools, such as
+`web_search` and `x_search`, because xAI runs them only on the Responses API.
 
 ```typescript
 import { createXai } from "@ai-sdk/xai";

package/docs/ai-gateway/providers.mdx

@@ -46,7 +46,7 @@ The following capabilities are supported across providers:
 | Anthropic                  | ✅               | ❌         | ❌        | ✅       |
 | Google                     | ✅               | ✅         | ❌        | ❌       |
 | Mistral                    | ✅               | ✅         | ❌        | ❌       |
-| xAI                        | ✅               | ✅         | ❌        | ❌       |
+| xAI                        | ✅               | ✅         | ✅        | ❌       |
 | Azure AI                   | ✅               | ✅         | ✅        | ✅       |
 | Bedrock Mantle             | ✅               | ❌         | ✅        | ✅       |
 | Bedrock Runtime            | ❌               | ❌         | ❌        | ❌       |

package/docs/ai-gateway/universal-api.mdx

@@ -70,7 +70,7 @@ clients that can't set a model still work.
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/v1/chat/completions` | Chat completions for every provider                                                                                                                                                             |
 | `/v1/embeddings`       | Embeddings for the providers marked in the [capability matrix](./providers.mdx#supported-providers)                                                                                             |
-| `/v1/responses`        | OpenAI Responses API: OpenAI, and the OpenAI-compatible models that serve it on [Azure AI](./azure-ai.mdx), [Bedrock Mantle](./bedrock-mantle.mdx) and [OpenRouter](./openrouter.mdx)           |
+| `/v1/responses`        | OpenAI Responses API: OpenAI, xAI, and the OpenAI-compatible models that serve it on [Azure AI](./azure-ai.mdx), [Bedrock Mantle](./bedrock-mantle.mdx) and [OpenRouter](./openrouter.mdx)      |
 | `/v1/messages`         | Anthropic Messages API: Anthropic, and the Claude models of [Azure AI](./azure-ai.mdx), [Bedrock Mantle](./bedrock-mantle.mdx), [Vertex AI](./vertex-ai.mdx) and [OpenRouter](./openrouter.mdx) |
 
 Jev is the exception: it serves TypeSafe's System One API on `/v1/systemone`,

package/docs/articles/version-support-policy.mdx

@@ -17,11 +17,75 @@ support window applies.
 
 ## At a glance
 
-| Surface                                            | What controls compatibility                   | Support window                                           |
-| -------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------- |
-| Gateway runtime                                    | The `compatibilityDate` in your `zuplo.jsonc` | Indefinite. Existing compatibility dates keep working.   |
-| Specification-based features (MCP, OAuth, OpenAPI) | The upstream specification's own lifecycle    | Tracks the specification. Old revisions eventually drop. |
-| Developer Portal                                   | The `zudoku` package version in your project  | Current version only. Fixes aren't backported.           |
+| Surface                                            | What controls compatibility                   | Support window                                            |
+| -------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------- |
+| Gateway runtime                                    | The `compatibilityDate` in your `zuplo.jsonc` | At least 12 months per compatibility date, likely longer. |
+| Specification-based features (MCP, OAuth, OpenAPI) | The upstream specification's own lifecycle    | Tracks the specification. Old revisions eventually drop.  |
+| Developer Portal                                   | The `zudoku` package version in your project  | Current version only. Fixes aren't backported.            |
+
+## What counts as a breaking change
+
+The compatibility promise focuses on the parts of Zuplo that a production API
+depends on. Other parts of the platform, such as diagnostics and tooling, keep
+improving between releases.
+
+### Breaking changes
+
+Zuplo treats these as breaking and gates them behind a compatibility date:
+
+- **Request handling.** A change that materially affects how the gateway handles
+  a request: which policies and handlers run and in what order, the status code,
+  headers, or body a client receives, how a request is routed, validated,
+  authenticated, rate limited, or forwarded.
+- **Exported code APIs.** The documented, public exports of `@zuplo/runtime`
+  that custom code imports, such as
+  [`ZuploRequest`](../programmable-api/zuplo-request.mdx),
+  [`ZuploContext`](../programmable-api/zuplo-context.mdx), and
+  [`HttpProblems`](../programmable-api/http-problems.mdx). Removing an export,
+  changing a signature, or changing what a documented API returns is breaking.
+- **Configuration.** A change that makes a valid `zuplo.jsonc`, route file, or
+  policy configuration fail to build, or that changes what an existing option
+  does. Stricter validation of invalid configuration is covered separately
+  below.
+
+### Not breaking changes
+
+These can change from release to release without a compatibility date. Tests and
+integrations hold up best when they don't depend on them:
+
+- **Error messages.** The human-readable text of errors throughout Zuplo, in
+  runtime responses, build and deployment output, and the CLI, can be reworded,
+  expanded, or localized. For example, the `title` and `detail` fields of a
+  [Problem Details](../programmable-api/http-problems.mdx) response can change.
+  Match on stable identifiers such as the status code and the problem `type`
+  instead.
+- **Additive changes.** New APIs, new policies, new optional configuration
+  properties, new response headers, and new fields in a response body or a
+  Problem Details object. Clients and tests should ignore fields and headers
+  they don't recognize.
+- **Logs, traces, and metrics.** Log messages and their wording, which
+  operations emit logs or spans, span names and attributes, and which metrics
+  and analytics Zuplo collects all change over time. New log entries appear and
+  existing ones change, so avoid parsing log text to drive automation.
+- **Local development.** The [local development](./local-development.mdx)
+  experience, including `zuplo dev`, the local Route Designer, and locally
+  mocked or emulated services, changes as the tooling improves. Behavior in
+  local development can differ from a deployed gateway. Treat a
+  [preview environment](./branch-based-deployments.mdx) as the source of truth
+  for production behavior.
+- **Undocumented behavior and internal APIs.** Anything not described in the
+  documentation: exports not documented as public, imports from internal paths
+  of a Zuplo package, internal headers, and incidental behavior such as the
+  order of headers or the exact timing of a request.
+- **Performance.** Latency, memory use, and throughput improve or shift between
+  releases. [Platform limits](./limits.mdx) are documented separately.
+- **Stricter build validation.** Zuplo continues to add checks that catch
+  invalid configuration and code at build time instead of at request time. For
+  example, a policy that's misconfigured so that it fails on every request might
+  build and deploy today, then fail the build after a new check ships. Catching
+  these problems before deployment keeps them out of production, though it means
+  a project that built before can occasionally need a fix to build again. The
+  build error explains what's wrong and how to fix it.
 
 ## Gateway runtime
 
@@ -51,8 +115,9 @@ raising the date in `zuplo.jsonc`:
 ```
 
 New projects default to a recent compatibility date. Existing projects stay on
-the date they set until someone changes it, and Zuplo doesn't retire old
-compatibility dates on a schedule.
+the date they set until someone changes it. Zuplo supports each compatibility
+date for at least 12 months after it's released, and likely much longer. To
+date, Zuplo hasn't retired any compatibility date.
 
 Every compatibility date and the behavior it changes is documented in
 [Compatibility Dates](../programmable-api/compatibility-dates.mdx). Each entry
@@ -66,18 +131,98 @@ that deployment, and merge once it passes.
 
 :::
 
-### Security exceptions
+### Compatibility flags
 
-Security is the exception to the compatibility promise. To close a vulnerability
-or protect customer traffic, Zuplo may change runtime behavior without gating
-the change behind a compatibility date, including in ways that break existing
-projects.
+Each behavior change in the runtime is implemented as a compatibility flag. A
+compatibility date is a named set of flags: setting a date turns on every flag
+that shipped with that date or an earlier one. Flags only ever turn new behavior
+on. A project can't use a flag to turn off a behavior that its compatibility
+date includes.
+
+Zuplo occasionally ships a flag before it belongs to any compatibility date, to
+resolve a specific customer issue or bug ahead of the next date. A project can
+turn on such a flag with `compatibilityFlags` in `zuplo.jsonc`.
+
+:::warning
+
+Compatibility flags aren't documented or supported, and because they're
+unstable, they aren't recommended for production projects.
+
+:::
+
+Until a flag becomes part of a compatibility date, it's considered unstable:
+
+- **Its behavior can change** between releases while the change is refined.
+- **It can be removed.** When a flag's behavior becomes standard or moves to
+  another flag, listing the old flag fails the build with a message explaining
+  what to use instead.
+- **Stability guarantees apply to compatibility dates only.** While a project
+  sets any `compatibilityFlags`, the guarantees on this page don't apply to it,
+  even when the flags it sets are already part of its compatibility date.
+
+When a flag becomes part of a compatibility date, raise the date and remove the
+flag from `zuplo.jsonc`. Setting the date is the supported way to get the
+behavior.
+
+## Exceptions to the compatibility promise
+
+Zuplo works to avoid breaking changes, and gates every change it can behind a
+compatibility date. In three situations, a change may need to ship outside a
+compatibility date. Even then, Zuplo keeps the change as small as possible and
+lets affected customers know.
+
+### Security
+
+Protecting customer traffic comes first. To close a vulnerability, Zuplo may
+change runtime behavior without a compatibility date, even when the fix affects
+how some existing projects behave.
 
 Zuplo scopes these changes as narrowly as the vulnerability allows and
 communicates them as directly as responsible disclosure permits. For Zuplo's
 security practices and how to report a vulnerability, see
 [Security](./security.mdx).
 
+### Protocol correctness
+
+Some parts of the gateway implement specifications Zuplo doesn't control — most
+visibly the Model Context Protocol (MCP), along with OAuth, OpenID Connect,
+OpenAPI, JSON Schema, and HTTP itself. Zuplo aims to implement these
+specifications correctly, because correct behavior is what keeps the gateway
+working with the clients and servers customers depend on.
+
+These features follow the lifecycle of the specification:
+
+- **Specification revisions.** When a specification deprecates or removes a
+  revision, Zuplo eventually ends support for that revision in line with the
+  specification's deprecation policy.
+- **Specification changes.** When a specification changes in a way that can't be
+  both backward compatible and compliant, Zuplo follows the specification.
+- **Conformance fixes.** From time to time, Zuplo finds a bug or behavior that's
+  inconsistent with a specification. Zuplo fixes these so the gateway behaves as
+  the specification describes.
+
+Where a protocol change can be gated, Zuplo gates it. The MCP Gateway, for
+example, requires a compatibility date of `2026-03-01` or later — see
+[MCP Gateway compatibility dates](../mcp-gateway/code-config/compatibility-dates.mdx).
+
+### Official SDK dependencies
+
+Some features are built on an official SDK for a protocol rather than a Zuplo
+implementation. For example, the [MCP Server](../mcp-server/overview.mdx) and
+[MCP Gateway](../mcp-gateway/overview.mdx) use the official MCP SDK for parts of
+their protocol handling.
+
+When Zuplo updates an SDK to pick up a new protocol revision, a security fix, or
+a bug fix, behavior that comes from the SDK can change with it. SDK-driven
+changes follow the SDK's own release cycle rather than Zuplo's compatibility
+dates, and Zuplo calls out notable ones in the
+[changelog](https://zuplo.com/changelog).
+
+MCP is evolving quickly, so the MCP Gateway and MCP Server track new protocol
+revisions and SDK releases as they publish. Testing MCP integrations against a
+preview environment before each production deployment is the best way to catch a
+change early.
+
 ## Changes take effect when you deploy
 
 Zuplo doesn't rebuild or redeploy a running gateway on your behalf. A new
@@ -99,31 +244,6 @@ recommends a comprehensive test suite that gates every deployment. The
 preview environments, and in CI/CD. See [Testing Your API](./testing.mdx) for
 the recommended setup.
 
-## Specification-based features
-
-Some parts of the gateway implement specifications Zuplo doesn't control — most
-visibly the Model Context Protocol (MCP), along with OAuth, OpenAPI, and related
-standards. These features follow the lifecycle of the specification rather than
-Zuplo's own compatibility policy.
-
-Two consequences:
-
-- When a specification deprecates or removes a revision, Zuplo eventually ends
-  support for that revision in line with the specification's deprecation policy.
-- When a specification changes such that remaining backward compatible would
-  mean falling out of compliance, Zuplo implements the breaking change. A
-  non-compliant implementation breaks interoperability with the clients and
-  servers customers need to work with, which is the larger break.
-
-MCP moves fastest here. The [MCP Gateway](../mcp-gateway/overview.mdx) and
-[MCP Server](../mcp-server/overview.mdx) track protocol revisions as the
-specification publishes them, and support for older revisions ends on the
-specification's schedule.
-
-Where a spec-driven change can be gated, Zuplo gates it. The MCP Gateway, for
-example, requires a compatibility date of `2026-03-01` or later — see
-[MCP Gateway compatibility dates](../mcp-gateway/code-config/compatibility-dates.mdx).
-
 ## Developer Portal
 
 The Developer Portal is a web application built on [Zudoku](https://zudoku.dev),
@@ -158,8 +278,8 @@ that need more than a dependency bump.
 
 When Zuplo introduces a breaking change:
 
-- **Notice comes first.** Zuplo publishes breaking changes in advance through
-  the [changelog](https://zuplo.com/changelog) and documentation, and contacts
+- **Changes are communicated.** Zuplo announces breaking changes through the
+  [changelog](https://zuplo.com/changelog) and documentation, and contacts
   affected customers directly where the impact is identifiable.
 - **Compatibility dates carry the change where possible.** Gating a runtime
   change behind a compatibility date leaves the timing of adoption to you.
@@ -169,8 +289,9 @@ When Zuplo introduces a breaking change:
   plan work directly with the Zuplo team on upgrade planning, testing, and
   rollout. See [Support](./support.mdx).
 
-Security changes are the exception and may ship with short notice, or none, when
-advance disclosure would put customers at risk.
+For security, protocol, and SDK changes, the timing of notice depends on the
+situation, such as responsible disclosure for a vulnerability. See
+[Exceptions to the compatibility promise](#exceptions-to-the-compatibility-promise).
 
 ## Related resources
 
@@ -179,6 +300,8 @@ advance disclosure would put customers at risk.
 - [Project Configuration (`zuplo.jsonc`)](../programmable-api/zuplo-json.mdx) —
   where the compatibility date is set
 - [Testing Your API](./testing.mdx) — local, preview, and CI/CD testing
+- [Problem Details Helper](../programmable-api/http-problems.mdx) — the error
+  format to assert on in tests
 - [Branch-Based Deployments](./branch-based-deployments.mdx) — how branches map
   to environments
 - [Updating Versions](../dev-portal/updating.mdx) — upgrading the Developer

package/docs/policies/mcp-capability-filter-inbound/doc.md

@@ -1,10 +1,47 @@
 ## Overview
 
 The `mcp-capability-filter-inbound` policy curates the MCP capabilities exposed
-by a proxied upstream server. It filters successful JSON-RPC list responses and
-blocks direct JSON-RPC access to hidden tools, prompts, and resources before the
+by a proxied upstream server. It filters successful JSON-RPC list responses,
+whether the upstream answers with JSON or with a `text/event-stream`, and blocks
+direct JSON-RPC access to hidden tools, prompts, and resources before the
 request is forwarded upstream.
 
+Direct access is checked on `tools/call` and `prompts/get` (by `params.name`),
+on `resources/read`, `resources/subscribe` and `resources/unsubscribe` (by
+`params.uri`), and on `completion/complete`: a `ref/prompt` reference's `name`
+against `prompts`, a `ref/resource` reference's `uri` against `resources` and
+`resourceTemplates` (either configured list may allow it, since the URI can be a
+concrete resource or a template). A URI with a template expression (`{name}`) is
+never a concrete resource, so it passes while `resourceTemplates` is omitted,
+whatever `resources` lists. A completion whose `ref` has any other shape (an
+unknown or missing `type`, no `ref`) is refused while `prompts`, `resources` or
+`resourceTemplates` is configured.
+
+A call to a hidden capability is not forwarded. It is answered exactly as MCP
+answers a capability that does not exist, so a client cannot tell the two apart:
+
+| Request                                       | Answer                                                                              |
+| --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `tools/call` of a hidden tool                 | `-32602`, `Tool "<name>" not found`                                                 |
+| `prompts/get` of a hidden prompt              | `-32602`, `Prompt "<name>" not found`                                               |
+| `resources/read`, `subscribe`, `unsubscribe`  | `-32002`, `Resource not found`, with `data.uri`                                     |
+| `completion/complete` of a hidden reference   | `-32602`, `Prompt "<name>" not found` or `Resource template "<uri>" not found`      |
+| Any of these without a string `name` or `uri` | `-32602`, for example `Invalid params for tools/call: params.name must be a string` |
+
+A method the policy checks or filters spelled another way, in another case or
+with surrounding spaces (`Tools/Call`, ` tools/list`), is answered `-32601`
+(`Method not found`): it is no MCP method, and an upstream that matched it
+leniently would run it unchecked.
+
+A resource URI is allowed when `resources` lists it, or when it matches a
+template that `resourceTemplates` allows, as the MCP SDK matches templates. With
+the configuration below, `stripe://customers/cus_1` is readable from the
+`stripe://customers/{id}` template, and a URI from any other template, such as
+`stripe://invoices/in_1`, is refused. When you omit `resources`, a URI passes
+unless it matches only templates hidden from the caller: the policy cannot tell
+a concrete resource from a URI of a template it does not know, so configure
+`resources` too when reads of unlisted templates must be refused.
+
 Omit a capability option to pass that capability type through unchanged. Set an
 option to an empty array to expose none of that capability type. Matching is
 case-sensitive and exact.
@@ -184,9 +221,143 @@ export default async function resolveCapabilities(
 }
 ```
 
+## Requests and responses the filter cannot read
+
+The policy fails closed. It never forwards something it could not check:
+
+| Case                                                                                                          | Result                                   |
+| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Body is not JSON (`Content-Type` other than JSON), on any HTTP method                                         | `415` problem+json, not forwarded        |
+| Body over 10 MiB                                                                                              | `413` problem+json, not forwarded        |
+| Body is JSON-typed but does not parse, or cannot be read (the upload failed)                                  | `400`, `-32700`, not forwarded           |
+| Body is JSON but not a JSON-RPC message                                                                       | `400`, `-32600` (its `id` when valid)    |
+| Batch with a member that is not a JSON-RPC 2.0 object (no or another `jsonrpc`, a nested array, a scalar)     | `400`, one `-32600`, not forwarded       |
+| A `method` that is not a string (an array, number, `null` or object), alone or in a batch                     | `400`, one `-32600`, not forwarded       |
+| A non-ASCII key in a message, its `params` or `params.ref` (Go folds `paramſ` into `params`)                  | `400`, `-32600`, not forwarded           |
+| `jsonrpc`/`method`/`id`/`params`, `params.name`/`uri`/`ref` or `ref.type`/`name`/`uri` twice, in any case     | `400`, `-32600`, not forwarded           |
+| A message key in another case (`Method`), or `params.Name`/`URI`/`Ref` or `ref.Name`/… on a direct call       | `400`, `-32600`, not forwarded           |
+| A direct call whose `params` is not an object, or has no string name or URI                                   | `-32602`, not forwarded                  |
+| A method the policy checks or filters, in another case or with spaces (`Tools/Call`, ` tools/list`)           | `-32601`, not forwarded                  |
+| A refused call sent as a notification (no `id`)                                                               | `400`, `-32600`, no `id`, not forwarded  |
+| A refused call whose `id` is not a string or an integer (`1.5`, `null`)                                       | `400`, `-32600`, no `id`, not forwarded  |
+| Access-control resolver throws or returns no value                                                            | `-32603` for each request that needed it |
+| List reply the policy cannot parse, or with no or unknown media type                                          | `-32603` instead of the reply            |
+| List reply in a content-coding the runtime does not decode (`deflate`, `zstd`)                                | `-32603` instead of the reply            |
+| List reply that is not a JSON-RPC result, error, notification or request                                      | `-32603` instead of the reply            |
+| List result whose `result` is not an object, or whose list (`tools`, `prompts`, …) is missing or not an array | `-32603` instead of the reply            |
+| List result whose `nextCursor` is not a string (or `null`)                                                    | `-32603` instead of the reply            |
+| A JSON-RPC array answering a single (non-batch) request                                                       | `-32603` instead of the reply            |
+| Result holding a filtered list (`tools`, `prompts`, …) that its request did not list                          | `-32603` instead of the reply            |
+| Batch reply array: a member that is any of the `-32603` cases above, or whose `id` matches no request         | Member dropped (see below)               |
+| SSE list reply: an event whose `data` is not JSON, or whose message is any of the `-32603` cases above        | Event dropped                            |
+| SSE list reply: an event with an unknown field, an `event` other than `message`, or a malformed `id`/`retry`  | Event dropped                            |
+| SSE list reply: an event over 10 MiB, or a final event without a closing blank line                           | Event dropped                            |
+| SSE list reply: a comment with text                                                                           | Text removed (`:` kept)                  |
+| A list item without a string name or URI                                                                      | Item dropped                             |
+
+The key checks guard against an upstream that reads JSON keys case-insensitively
+(as Go's `encoding/json` does) or keeps the first of two duplicates. Non-ASCII
+keys and the repeated keys above are refused on every message, notifications
+included, whatever its method: `{"params":{"name":1,"Name":2}}` is a `400` even
+on `notifications/initialized`. A single case variant in `params` or
+`params.ref` (`Name`, `URI`, `Ref`) is refused only on a direct call; keys
+nested deeper, such as `params.arguments.Name`, are not checked.
+
+A request without a body, or with an empty one, passes through whatever its HTTP
+method (`GET`, a `DELETE` that ends a session, an empty `POST`). The policy
+reads a body it cannot parse only as far as its answer needs: one that is not
+JSON up to its first non-blank character, a JSON one up to the 10 MiB limit. A
+non-2xx reply passes through with its status and headers (a problem details or
+OAuth error body, an empty body, one that is not JSON or is still compressed),
+unless it is a JSON reply with a `result` or a batch, which is filtered.
+
+A list reply the policy cannot read is replaced by a JSON-RPC `-32603` error for
+the list request, with its `id` (an array of errors for a batch), sent as
+`application/json` with HTTP `200`; the error carries none of the reply. Every
+reply the policy does not forward (a replaced reply, a dropped event or batch
+member) is logged as a warning, without any of its content.
+
+A request with a list method the policy filters is sent upstream with
+`Accept-Encoding: gzip, br`, replacing the client's value, so the upstream
+answers in a content-coding the runtime decodes. Other requests keep the
+client's `Accept-Encoding`.
+
+When the policy drops an SSE list reply, the client is not left waiting. Each
+list request whose reply was dropped gets a JSON-RPC error event instead, with
+none of the dropped content:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32603,
+    "message": "The MCP capability filter could not read the upstream's list response, so it was not forwarded."
+  }
+}
+```
+
+The error is sent at once when the dropped reply's `id` shows which request it
+answered, and otherwise when the upstream stream ends, for each request still
+unanswered. A request that is not a list request gets a different message (see
+[Batch Requests](#batch-requests)). Once no request is waiting, the stream ends.
+Other events in the stream (progress notifications, server requests, error
+replies, events with only an `id` of letters, digits and `._~:/+=-`, `retry` or
+`event: message`) pass through unchanged. So does an event without a payload (no
+`data`, or an empty one), such as the priming event a 2025-11-25 server sends
+first to make its stream resumable: its `id` is kept, and nothing is logged.
+
+The policy adds an error only after it dropped something. When the upstream
+stream ends cleanly without answering a request, and nothing was dropped, the
+policy adds nothing: answering that request is the handler's job.
+`McpProxyHandler` sends a `-32603` error for each unanswered request itself
+(before this policy sees the stream), so behind it the client still gets an
+answer.
+
 ## Batch Requests
 
-For JSON-RPC batch requests, list responses are filtered per response item when
-the item id can be matched to the original list request. If any batch item
-directly calls a hidden tool, prompt, or resource, the policy blocks the whole
-batch with a not-found JSON-RPC error response.
+For JSON-RPC batch requests, list responses are filtered per response item,
+matched to the original list request by id. A reply id matches a request of the
+same type first (`1` to `1`), and otherwise a request with the same text (`"1"`
+for `1`). A batch may hold ids that differ only in type (`1` and `"1"`): a reply
+goes to the request whose id it matches exactly. A result whose id matches no
+request in the batch fails closed, including one whose id is that of a client
+result or error in the batch: that reply is dropped. Ids can be re-typed in more
+ways than the policy can tell apart (`1.0`, `"01"`, `-0`, numbers past 2^53), so
+a result that holds a list the policy filters (`tools`, `prompts`, `resources`,
+`resourceTemplates`) fails closed the same way unless it answers the request
+that listed it.
+
+A batch reply array, as a JSON body or in an SSE event, is checked member by
+member, so one bad member does not lose its siblings' replies (a tool call in
+the batch may already have run). Each member that is safe is sent. A member the
+policy cannot read is replaced by a JSON-RPC `-32603` error for the request it
+answers, or dropped when its `id` matches no request still waiting. When a
+member was dropped, every request left without a reply gets the error too: in a
+JSON reply at once, appended to the array; on a stream when it ends. A JSON
+batch reply that is not an array gets a `-32603` for every request.
+
+When the stream drops an event that might have held a reply, every request still
+waiting at the end of the stream gets a JSON-RPC `-32603` error. For a request
+that is not a list request, the message says the filter did not forward the
+reply and the request may already have run, so the client does not assume a
+retry is safe:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "error": {
+    "code": -32603,
+    "message": "The MCP capability filter did not forward the upstream's reply to this request. The request may already have run."
+  }
+}
+```
+
+If any batch item directly calls a hidden tool, prompt, or resource, the policy
+refuses the whole batch and forwards none of it. It answers with an array that
+has one error per request in the batch: the not-found error for the hidden call,
+and for each other request a `-32603` that says it was not forwarded because
+another request in its batch was refused. Notifications in the batch get
+nothing. On protocol version 2025-06-18 and later, which have no batches, the
+answer is one `400` with `-32600` and no `id`.

package/docs/policies/mcp-capability-filter-inbound/schema.json

@@ -26,7 +26,7 @@
           "description": "The name of the exported type"
         },
         "module": {
-          "const": "$import(@zuplo/runtime)",
+          "const": "$import(@zuplo/runtime/mcp-gateway)",
           "description": "The module containing the policy"
         },
         "options": {
@@ -330,7 +330,7 @@
       "examples": [
         {
           "export": "McpCapabilityFilterInboundPolicy",
-          "module": "$import(@zuplo/runtime)",
+          "module": "$import(@zuplo/runtime/mcp-gateway)",
           "options": {
             "accessControl": {
               "groupClaim": "groups",

package/docs/policies/mcp-token-exchange-inbound/doc.md

@@ -20,13 +20,14 @@ The policy does not perform the normal upstream fetch and does not pass hidden
 context to the handler. The route should use `McpProxyHandler` with a
 deterministic upstream MCP URL configured on the handler. `McpProxyHandler`
 handles GET stream probes and delegates POST forwarding to Zuplo's
-`urlRewriteHandler`. The policy only installs a response hook for MCP OAuth
-retry/connect-required cases.
+`urlRewriteHandler`. When the upstream answers `401`, `McpProxyHandler`
+refreshes the upstream credential and retries the request once, before any
+outbound policy or response hook sees the response. If the refresh needs the
+user to reconnect, the handler returns the connect-required JSON-RPC error
+instead.
 
 Projects using this policy must run with a compatibility date that enables
-chained response hooks, currently `2026-03-01` or later. The retry hook must
-receive the latest response in the policy chain so later response hooks cannot
-accidentally replace an upstream OAuth retry or connect-required response.
+chained response hooks, currently `2026-03-01` or later.
 
 ## Configuration
 

package/docs/policies/mcp-token-exchange-inbound/schema.json

@@ -26,7 +26,7 @@
           "description": "The name of the exported type"
         },
         "module": {
-          "const": "$import(@zuplo/runtime)",
+          "const": "$import(@zuplo/runtime/mcp-gateway)",
           "description": "The module containing the policy"
         },
         "options": {
@@ -424,7 +424,7 @@
       "examples": [
         {
           "export": "McpTokenExchangeInboundPolicy",
-          "module": "$import(@zuplo/runtime)",
+          "module": "$import(@zuplo/runtime/mcp-gateway)",
           "options": {
             "displayName": "Linear",
             "id": "linear",

package/package.json

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