feat(plugins): apply plugin upstream headers to provider calls

docs/adr/0012-plugin-system.md

@@ -79,7 +79,8 @@ every phase:
   refusal, opaque), plus `Tools`, `Params`, and the raw body.
 - `Response`: a `Completion` with `Choices` using the same `Part` model.
 - `Stream`: text accumulated so far per choice.
-- `Headers`: inbound (credentials redacted), outbound, and upstream headers.
+- `Headers`: inbound (credentials redacted), outbound, and upstream headers,
+  which the host merges into every provider call of the request.
 - `Values`: a per-request bag shared by every hook of the request.
 
 Edits go through methods (`SetText`, `SetMedia`, `SetToolArguments`,
@@ -359,9 +360,14 @@ Declared in the contract or the spec but not run by this release:
 - `request` and `complete` hook kinds: the interfaces, `Kind` values, and
   load-time validation exist; no runtime calls them. `ext.RequestRewriter`
   remains the request-phase mechanism.
-- `Headers.Upstream` is recorded and logged, not forwarded to providers.
-  Prompt-phase edits to `Headers.Request` apply to the live request (later
+- Prompt-phase edits to `Headers.Request` apply to the live request (later
   plugins, request logging) but are not forwarded to the provider.
+  `Headers.Upstream` was deferred when this ADR was written and no longer is:
+  the host merges it into every provider call of the request — failover
+  attempts, token counting and compaction included — minus the names that
+  carry credentials, frame the connection, describe the body, or select
+  provider features (`#1203`, which updated this section in place). Inference
+  the gateway issues for its own work carries none of them.
 - `RouteRequest.Prompt` is nil; `RouteChoice.Reason` reaches debug logs
   only. Instance-scoped `secret` fields reach a route plugin redacted.
 - `Host.HTTPClient` hands plugins one shared client built from the gateway's

docs/advanced/guardrails.mdx

@@ -454,11 +454,22 @@ remove lines are a bare `Name`. Blank lines and `#` comments are ignored.
 | `response_set` | Replace a header on the response sent to the client. |
 | `response_add` | Append a value to a client response header, keeping existing values. Applied once per request even when the instance runs in both phases. |
 | `response_remove` | Drop a header from the client response, including headers GoModel adds itself (for example `X-Request-Id`). |
-| `upstream_set` | Static headers for the provider call. Recorded but not forwarded in this release. |
+| `upstream_set` | Static headers merged into every provider call of the request that goes through the gateway's HTTP client: failover attempts, token counting and compaction included, Bedrock excluded. Credential headers, the ones that frame the connection or describe the body, `Accept-Encoding`, and `anthropic-beta` are refused; see [Upstream headers](/advanced/plugins#upstream-headers). |
 
 Credential headers (`Authorization`, `X-Api-Key`, `Cookie`, ...) can never be
 edited, and names containing `secret` or `token` cannot be set.
 
+`upstream_set` additionally refuses three groups of names. The ones that frame
+the connection: `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`,
+`Keep-Alive`, `Proxy-Connection`, `Proxy-Authenticate`, `Te`, `Trailer`,
+`Upgrade`, `Expect`. The ones that describe the body the gateway encoded:
+`Content-Type`, `Content-Encoding`. And `Accept-Encoding`, which negotiates
+response compression — setting it turns off the transport's automatic gzip
+decompression, so the gateway would parse compressed bytes. `anthropic-beta` is
+refused on its own: it selects provider features and has to keep the
+`oauth-2025-04-20` flag subscription credentials need. The rest of the
+provider's own headers are not protected: a plugin value replaces them.
+
 #### Example
 
 ```yaml

docs/advanced/plugins.mdx

@@ -284,7 +284,7 @@ of a request:
 | `Prompt` | `*Prompt` | the conversation (`Messages` with stable IDs and typed `Parts`: text, image, audio, file, tool call, tool result, reasoning, refusal, opaque), `Tools`, `Params`, raw body. Edit through `SetText`, `SetMedia`, `SetToolArguments`, `SetToolResult`, `Insert`, `Append`, `Remove`, `SetParam`; `TextTargets(roles...)` lists every text part, tool-result text included, and `SetTargetText` writes one back |
 | `Response` | `*Completion` | the response, `nil` until the response phase: `Choices` with the same `Part` model, `Usage`, raw body. Edit through `SetText`, `ReplaceText`, `SetFinishReason`, `SetToolArguments`; `TextTargets` and `SetTargetText` work as on `Prompt` |
 | `Stream` | `*StreamState` | text accumulated so far per choice and the event count; `nil` for non-streaming requests |
-| `Headers` | `*Headers` | `Request` (inbound, credentials redacted; prompt-phase edits apply to the live request for later plugins and request logging, not to the provider call), `Response` (applied to the client response; a header set to the empty string is removed, including ones the gateway adds such as `X-Request-Id`), `Upstream` (recorded, not forwarded in this release) |
+| `Headers` | `*Headers` | `Request` (inbound, credentials redacted; prompt-phase edits apply to the live request for later plugins and request logging, not to the provider call), `Response` (applied to the client response; a header set to the empty string is removed, including ones the gateway adds such as `X-Request-Id`), `Upstream` (sent with every provider call of the request that goes through the gateway's HTTP client; see [Upstream headers](#upstream-headers)) |
 | `Values` | `Values` | per-request bag shared by every hook of the request; prefix keys with the plugin name |
 
 Edits go through methods, not field assignment, so GoModel re-encodes only
@@ -315,6 +315,67 @@ result is replaced with `SetToolResult`.
 messages the provider cache planner will mark as the cached prefix. Appending
 keeps the cache; editing inside the prefix invalidates it for the session.
 
+### Upstream headers
+
+`Headers.Upstream` puts a header on the provider call itself: a per-request
+routing or billing property the upstream expects, such as Helicone's, or an
+organizational tag a gateway in front of the provider routes on. A provider
+credential does not belong here — the names the gateway treats as credentials
+are refused, and any other value is forwarded to the provider. The host logs
+how many headers a plugin set, never their values. Assign the map in a
+prompt-phase hook, before the provider call runs:
+
+```go
+import "net/http"
+
+func (p *tenantHint) OnPrompt(_ context.Context, x *pluginapi.Exchange) (pluginapi.Decision, error) {
+	x.Headers.Upstream = http.Header{
+		"Helicone-Property-Tenant":  {x.Meta.UserPath},
+		"Helicone-Property-Request": {x.Meta.RequestID},
+	}
+	return pluginapi.Allow(), nil
+}
+```
+
+What the gateway does with them:
+
+- Every provider attempt of the request carries them, failover to another
+  provider included, and so do the token-counting and compaction calls the
+  request makes. Each attempt sends them to the upstream selected for that
+  attempt: a failover can resolve to a different provider and a different base
+  URL, and the headers follow it. Every call that goes through the gateway's
+  HTTP client, that is; Bedrock, which calls the AWS SDK directly, does not carry
+  them.
+- Inference the gateway issues for its own work does not. A guardrail's LLM
+  judge calls the provider through the plugin `Host` on the request context, and
+  that call drops these headers: they describe the client's provider, not the
+  model the gateway picked for the guardrail.
+- These names are refused rather than merged: credential headers
+  (`Authorization`, `Proxy-Authorization`, `x-api-key`, `api-key`,
+  `x-goog-api-key`, `x-anthropic-api-key`, `xi-api-key`, `x-auth-token`,
+  `x-access-token`, `x-gomodel-key`, `Cookie`, `Set-Cookie`), the ones that frame
+  the connection (`Host`, `Content-Length`, `Transfer-Encoding`, `Connection`,
+  `Keep-Alive`, `Proxy-Connection`, `Proxy-Authenticate`, `Te`, `Trailer`,
+  `Upgrade`, `Expect`), the ones that describe the body the gateway encoded
+  (`Content-Type`, `Content-Encoding`), `Accept-Encoding`, which negotiates
+  response compression, and `anthropic-beta`, which selects provider features and
+  has to keep the `oauth-2025-04-20` flag subscription credentials need.
+- Any other name reaches the wire with the plugin's value, replacing a header
+  the request carried and one the provider set for itself. Only the names above
+  are protected; the rest of the provider's headers are not.
+- The host folds a hook's headers into the request state when that phase
+  finishes, so a value written after the provider call has run — from a
+  response-phase hook — no longer affects it. Treat the map you get back from
+  the context as read-only.
+
+<Note>
+  **Upgrading from a release that recorded these headers without sending them.**
+  A plugin that already set `Headers.Upstream` on such a release had its values
+  stored and dropped. After the upgrade they reach the provider, or the proxy in
+  front of it, for the first time: check the upstream accepts them before
+  rolling the upgrade out.
+</Note>
+
 ## Configuration
 
 ### Enabling the plugin system

docs/de/advanced/guardrails.mdx

@@ -482,7 +482,7 @@ Leerzeilen und `#`-Kommentare werden ignoriert.
 | `response_set` | Ersetzt einen Header in der an den Client gesendeten Response. |
 | `response_add` | Hängt einen Wert an einen Header der Client-Response an und behält vorhandene Werte bei. Wird einmal pro Request angewendet, auch wenn die Instanz in beiden Phasen läuft. |
 | `response_remove` | Entfernt einen Header aus der Client-Response, einschließlich Headern, die GoModel selbst hinzufügt (zum Beispiel `X-Request-Id`). |
-| `upstream_set` | Statische Header für den Provider-Aufruf. In diesem Release erfasst, aber nicht weitergeleitet. |
+| `upstream_set` | Statische Header, die in jede Provider-Anfrage des Requests einfließen, die über den HTTP-Client des Gateways läuft: Failover-Versuche, Token-Zählung und Kompaktierung eingeschlossen, Bedrock ausgenommen. Header mit Zugangsdaten, Header, die die Verbindung oder den Body bestimmen, `Accept-Encoding` und `anthropic-beta` werden abgelehnt; siehe [Upstream-Header](/de/advanced/plugins). |
 
 Header mit Zugangsdaten (`Authorization`, `X-Api-Key`, `Cookie`, ...) können nie
 bearbeitet werden, und Namen, die `secret` oder `token` enthalten, können nicht

docs/de/advanced/plugins.mdx

@@ -274,7 +274,7 @@ Jeder Hook erhält einen `*pluginapi.Exchange`, in jeder Phase eines Requests da
 | `Prompt` | `*Prompt` | die Konversation (`Messages` mit stabilen IDs und typisierten `Parts`: Text, Bild, Audio, Datei, Tool Call, Tool-Ergebnis, Reasoning, Refusal, opak), `Tools`, `Params`, Roh-Body. Bearbeitung über `SetText`, `SetMedia`, `SetToolArguments`, `SetToolResult`, `Insert`, `Append`, `Remove`, `SetParam`; `TextTargets(roles...)` listet jeden Textteil auf, einschließlich Text in Tool-Ergebnissen, und `SetTargetText` schreibt einen davon zurück |
 | `Response` | `*Completion` | die Response, `nil` bis zur Phase `response`: `Choices` mit demselben `Part`-Modell, `Usage`, Roh-Body. Bearbeitung über `SetText`, `ReplaceText`, `SetFinishReason`, `SetToolArguments`; `TextTargets` und `SetTargetText` funktionieren wie bei `Prompt` |
 | `Stream` | `*StreamState` | bisher angesammelter Text pro Choice und die Anzahl der Events; `nil` bei Requests ohne Streaming |
-| `Headers` | `*Headers` | `Request` (eingehend, Zugangsdaten geschwärzt; Änderungen in der Phase `prompt` gelten für den laufenden Request bei späteren Plugins und beim Request-Logging, nicht für den Provider-Aufruf), `Response` (wird auf die Client-Response angewendet; ein auf den leeren String gesetzter Header wird entfernt, einschließlich solcher, die das Gateway hinzufügt, wie `X-Request-Id`), `Upstream` (wird festgehalten, in diesem Release aber nicht weitergeleitet) |
+| `Headers` | `*Headers` | `Request` (eingehend, Zugangsdaten geschwärzt; Änderungen in der Phase `prompt` gelten für den laufenden Request bei späteren Plugins und beim Request-Logging, nicht für den Provider-Aufruf), `Response` (wird auf die Client-Response angewendet; ein auf den leeren String gesetzter Header wird entfernt, einschließlich solcher, die das Gateway hinzufügt, wie `X-Request-Id`), `Upstream` (wird mit jeder Provider-Anfrage des Requests gesendet, die über den HTTP-Client des Gateways läuft — Bedrock, das das AWS SDK direkt nutzt, ausgenommen —, einschließlich Failover-Versuchen sowie Aufrufen zur Token-Zählung und Kompaktierung; Header mit Zugangsdaten, Header, die die Verbindung oder den Body bestimmen, `Accept-Encoding` und vom Provider ausgehandelte Header werden abgelehnt; Anfragen, die das Gateway für eigene Zwecke stellt, tragen keine dieser Header) |
 | `Values` | `Values` | Request-bezogener Speicher, den alle Hooks des Requests gemeinsam nutzen; stellen Sie Keys den Plugin-Namen voran |
 
 Änderungen erfolgen über Methoden, nicht über Feldzuweisungen, sodass GoModel nur das neu kodiert,
@@ -303,6 +303,66 @@ ruft es selbst ab. Medien innerhalb eines Tool-Ergebnisses werden mit `SetToolRe
 der Cache-Planer des Providers als gecachtes Präfix markieren wird. Anhängen erhält den Cache;
 Bearbeitungen innerhalb des Präfixes machen ihn für die Session ungültig.
 
+### Upstream-Header
+
+`Headers.Upstream` setzt einen Header auf den Provider-Aufruf selbst: eine
+request-bezogene Routing- oder Abrechnungs-Eigenschaft, die das Upstream erwartet,
+etwa die von Helicone, oder ein organisatorisches Tag, nach dem ein Gateway vor dem
+Provider routet. Zugangsdaten für einen Provider gehören nicht hierher — die Namen,
+die das Gateway als Zugangsdaten behandelt, werden abgelehnt, und jeder andere Wert
+wird an den Provider weitergegeben. Das Host loggt nur, wie viele Header ein Plugin
+gesetzt hat, nie deren Werte. Weisen Sie die Map in einem Hook der Phase `prompt` zu,
+bevor der Provider-Aufruf läuft:
+
+```go
+import "net/http"
+
+func (p *tenantHint) OnPrompt(_ context.Context, x *pluginapi.Exchange) (pluginapi.Decision, error) {
+	x.Headers.Upstream = http.Header{
+		"Helicone-Property-Tenant":  {x.Meta.UserPath},
+		"Helicone-Property-Request": {x.Meta.RequestID},
+	}
+	return pluginapi.Allow(), nil
+}
+```
+
+Was das Gateway damit macht:
+
+- Jeder Provider-Versuch des Requests trägt sie, einschließlich Failover auf einen
+  anderen Provider, ebenso die Aufrufe zur Token-Zählung und Kompaktierung, die der
+  Request auslöst. Jeder Versuch sendet sie an das für diesen Versuch gewählte
+  Upstream: Ein Failover kann auf einen anderen Provider und eine andere Base-URL
+  auflösen, und die Header folgen ihm. Jeder Aufruf, der über den HTTP-Client des
+  Gateways läuft, wohlgemerkt; Bedrock, das das AWS SDK direkt aufruft, trägt sie
+  nicht.
+- Inferenz, die das Gateway für eigene Zwecke stellt, trägt sie nicht. Der LLM-Judge
+  einer Guardrail ruft den Provider über das Plugin-`Host` im Request-Kontext auf,
+  und dieser Aufruf verwirft die Header: Sie beschreiben den Provider des Clients,
+  nicht das Modell, das das Gateway für die Guardrail gewählt hat.
+- Diese Namen werden abgelehnt statt zusammengeführt: Header mit Zugangsdaten
+  (`Authorization`, `Proxy-Authorization`, `x-api-key`, `api-key`, `x-goog-api-key`,
+  `x-anthropic-api-key`, `xi-api-key`, `x-auth-token`, `x-access-token`,
+  `x-gomodel-key`, `Cookie`, `Set-Cookie`), die die Verbindung rahmen (`Host`,
+  `Content-Length`, `Transfer-Encoding`, `Connection`, `Keep-Alive`,
+  `Proxy-Connection`, `Proxy-Authenticate`, `Te`, `Trailer`, `Upgrade`, `Expect`),
+  die den Body beschreiben, den das Gateway kodiert hat (`Content-Type`,
+  `Content-Encoding`), `Accept-Encoding`, das die Kompression der Antwort aushandelt,
+  und `anthropic-beta`, das Provider-Features auswählt und das Flag
+  `oauth-2025-04-20` behalten muss, das Abo-Zugangsdaten brauchen.
+- Jeder andere Name erreicht die Leitung mit dem Wert des Plugins und ersetzt einen
+  Header des Requests sowie einen, den der Provider selbst gesetzt hat. Nur die oben
+  genannten Namen sind geschützt; die übrigen Header des Providers nicht.
+- Das Host faltet die Header eines Hooks in den Request-State, wenn diese Phase
+  endet; ein Wert, der erst nach dem Provider-Aufruf geschrieben wird — aus einem Hook
+  der Phase `response` —, wirkt nicht mehr. Behandeln Sie die Map, die Sie aus dem
+  Kontext erhalten, als schreibgeschützt.
+
+**Upgrade von einem Release, das diese Header festhielt, ohne sie zu senden.** Ein
+Plugin, das `Headers.Upstream` auf einem solchen Release bereits gesetzt hat, bekam
+seine Werte gespeichert und verworfen. Nach dem Upgrade erreichen sie zum ersten Mal
+den Provider oder den Proxy davor: Prüfen Sie, ob das Upstream sie akzeptiert, bevor
+Sie das Upgrade ausrollen.
+
 ## Konfiguration
 
 ### Das Plugin-System aktivieren

docs/pl/advanced/guardrails.mdx

@@ -466,7 +466,7 @@ remove to sama `Name`. Puste linie i komentarze `#` są ignorowane.
 | `response_set` | Zastępuje nagłówek w odpowiedzi wysyłanej do klienta. |
 | `response_add` | Dopisuje wartość do nagłówka odpowiedzi do klienta, zachowując istniejące wartości. Stosowane raz na request, nawet gdy instancja działa w obu fazach. |
 | `response_remove` | Usuwa nagłówek z odpowiedzi do klienta, także nagłówki dodawane przez sam GoModel (na przykład `X-Request-Id`). |
-| `upstream_set` | Statyczne nagłówki dla wywołania providera. W tym wydaniu zapisywane, ale nieprzekazywane. |
+| `upstream_set` | Statyczne nagłówki wchodzące w każde wywołanie providera w ramach requestu, które przechodzi przez klienta HTTP gatewaya: z próbami failover, zliczaniem tokenów i kompakcją, z wyjątkiem Bedrocka. Nagłówki z danymi uwierzytelniającymi, nagłówki określające połączenie lub ciało żądania, `Accept-Encoding` oraz `anthropic-beta` są odrzucane; zobacz [Nagłówki upstream](/pl/advanced/plugins). |
 
 Nagłówków z danymi uwierzytelniającymi (`Authorization`, `X-Api-Key`,
 `Cookie`, ...) nigdy nie można edytować, a nazw zawierających `secret` lub