Summary

resolveCacheRetention in the embedded runner wrapper silently dropped an explicit user-provided cacheRetention for any provider that was neither in the anthropic family nor google-eligible. That meant openai-completions providers with prefix-caching backends (oMLX, llama.cpp, etc.) — the ones documented to opt in via compat.supportsPromptCacheKey: true — never received the user's chosen retention. The wrapper omitted it, so the transport could not propagate prompt_cache_retention: "24h" for long-retention setups, and the explicit user intent was lost on the way to buildOpenAICompletionsParams.

Now any explicit "none" | "short" | "long" is honored regardless of provider family. Legacy cacheControlTtl ("5m"/"1h") aliasing stays scoped to anthropic/google families where it was previously meaningful — that path was already gated by the family check.

Fixes #81281.

Verification

• CI=true pnpm test src/agents/pi-embedded-runner/prompt-cache-retention.test.ts — 6 passed (added regression coverage for openai-completions explicit long/short/none and for the undefined fallback that keeps embedded-wrapper behavior unchanged).
• Reviewed adjacent src/agents/openai-transport-stream.test.ts suite (165 passing); the single pre-existing flake on the unrelated yields to aborts during bursty Responses streams test reproduces on origin/main without these changes and is not touched by this PR.

Test plan

• Maintainer live-trace a Docker/oMLX openai-completions run with compat.supportsPromptCacheKey: true and cacheRetention: "long" to confirm prompt_cache_key and prompt_cache_retention: "24h" reach the outgoing payload end-to-end.

Real behavior proof

Behavior addressed: resolveCacheRetention in src/agents/pi-embedded-runner/prompt-cache-retention.ts silently dropped an explicit cacheRetention: "long" | "short" | "none" whenever the provider was not in the anthropic family and not google-eligible. openai-completions providers that opt into prompt caching via compat.supportsPromptCacheKey: true therefore lost the user's intent before it reached buildOpenAICompletionsParams, so the outgoing payload never carried prompt_cache_retention: "24h" for long retention (issue #81281).

Real environment tested: branch fix/81281-openai-prompt-cache-key at HEAD cb0503e19e checked out against this OpenClaw working copy, plus a verbatim re-implementation of the origin/main resolver (HEAD aef93881af) to drive a before/after comparison through node directly against the on-branch module.

Exact steps or command run after this patch:

$ node node_modules/.bin/tsx demo-81281-compare.mjs

The demo imports the on-branch resolveCacheRetention and a pure-JS port of the origin/main body (preserving the original if (!family && !googleEligible) return undefined; early return that caused the bug), then exercises the openai-completions opt-in scenario plus regression guards.

Evidence after fix: live node stdout against the on-branch source (HEAD cb0503e19e):

== openai-completions provider, user sets cacheRetention=long (issue #81281) ==
origin/main behavior: {}
this branch behavior: {"resolved":"long"}

== regression check: undefined cacheRetention on openai-completions stays undefined ==
this branch: {}

== regression check: anthropic family unchanged ==
this branch: {"resolved":"long"}

== regression check: legacy cacheControlTtl='1h' on openai-completions no longer maps to 'long' ==
origin/main: {}
this branch: {}

({} is JSON.stringify({ resolved: undefined }) — the resolved key is omitted when the function returns undefined. The first block is the actual fix: a user-set cacheRetention: "long" against an openai-completions provider that previously resolved to undefined now resolves to "long", which is the value buildOpenAICompletionsParams needs in order to emit prompt_cache_retention: "24h" downstream.)

Observed result after fix: an openai-completions provider with compat.supportsPromptCacheKey: true and cacheRetention: "long" now receives the resolved "long" from the embedded-runner wrapper instead of undefined. The downstream transport at src/agents/openai-transport-stream.ts:1717 and :3009 already maps that value onto prompt_cache_retention in the outgoing OpenAI-completions payload (see commit cb0503e19e). Anthropic-family and google-eligible callers still receive the same value they did on origin/main; the legacy cacheControlTtl: "1h" shortcut remains gated to those families so callers without compat.supportsPromptCacheKey are unchanged.

What was not tested: end-to-end traffic against a live oMLX or llama.cpp openai-completions backend with prompt caching enabled. The transport-side payload emission is covered by the existing src/agents/openai-transport-stream.test.ts suite (165 passing on this branch). A maintainer-side oMLX/llama.cpp live trace would be the natural next step and is what the Test plan TODO above flags.