Preserve Responses prompt-cache controls and service tiers across execution paths

Problem statement / motivation

Enabling storage, continuation, or built-in tools changes a Responses request from raw HTTP pass-through to typed execution. At the reviewed revision, RequestPayload and UpstreamRequest lack prompt_cache_options, prompt_cache_key, prompt_cache_retention, and service_tier. These settings can therefore disappear when a client enables gateway features.

Proposed solution

Implement this bounded Responses follow-up to #314. Add typed request/response settings, explicit upstream capability handling, and preservation through storage and continuation. Cover cache mode and TTL, supported content-part breakpoints, cache keys, and requested/actual service tiers. Preserve the distinction between OpenAI prompt-cache controls and vLLM cache_salt.

Do not implement KV-cache lifetime, cache placement, or processing-tier infrastructure in the gateway. Unsupported settings should fail clearly rather than silently disappear. Keep provider/model validation configurable: Astra restrictions must not become global restrictions on vLLM models.

Acceptance criteria

• Supported controls survive HTTP JSON/SSE, WebSocket execution, storage, and continuation with documented inheritance semantics.
• prompt_cache_options supports the documented implicit/explicit mode and ttl: "30m" contract where the upstream supports it; legacy retention is handled explicitly.
• Existing content-part cache breakpoints survive normalization; no silent fallback from explicit-only caching to implicit caching.
• Requested and returned service tiers are preserved where supported; unsupported regional/tier combinations surface useful errors.
• Capability tests cover Astra's unsupported sampling/logprob settings and reasoning effort values without changing other models' valid requests.
• Usage preservation identifies supported cache-read/write counters from the pinned upstream contract; do not infer cache writes from reads or invent billing data.
• Differential tests compare pass-through and executor behavior, including omitted/null/invalid controls and continuations. Publish the supported/transformed/rejected matrix under #314.

Additional context

Related: #314 (capability contract), #69 (vLLM cache reuse). Tokenization and KV-cache execution remain upstream responsibilities.

Sources: model parameter migration, prompt caching.

Reviewed at cdac36f: implementation. Documentation checked September 18, 2026; pin the implementation-time API/model version when recording conformance.

Start with crates/agentic-server-core/src/types/request_response.rs and the capability contract in #314, then trace HTTP JSON/SSE, WebSocket, storage, and continuation execution paths. Define the supported/transformed/rejected matrix before implementing the typed settings and capability handling. Done means differential and capability tests cover cache controls, service tiers, omitted/null/invalid values, continuations, and model-specific restrictions without silent loss.