PR #60757: fix(google): add direct cachedContent support

• Repository: openclaw/openclaw
• Author: vincentkoc
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/60757

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: OpenClaw's direct Google Generative AI transport could not send an explicit cachedContent handle, so prebuilt Gemini context caches could not be targeted from model-level runs.
• Why it matters: recent cache work covered Google cache reporting, but the direct Google model path still lacked the request seam needed for explicit cache reuse.
• What changed: add cachedContent to the direct Google transport request builder, pass it through Google model extra params, add targeted regression coverage, and keep a user-facing changelog note for the direct cache support.
• What did NOT change (scope boundary): no Gemini CLI parsing/reporting changes, no cache lifecycle APIs, and no change to Google's automatic cache-read accounting math.

AI-assisted: Codex. Testing: focused local smokes plus formatting check.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #60801
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the direct Google request builder and extra-params stream wrapper had no cachedContent seam, so explicit Google context cache handles were dropped before the model request was serialized.
• Missing detection / guardrail: no regression test covered config-to-transport pass-through for Google cachedContent.
• Contributing context (if known): recent cache/status work made the missing Google explicit-cache seam more visible because reporting existed without the corresponding model-level control surface.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/google-transport-stream.test.ts, src/agents/pi-embedded-runner/extra-params.google.test.ts
• Scenario the test should lock in: Google cachedContent survives both direct transport request building and model extra-param pass-through.
• Why this is the smallest reliable guardrail: the regression lives at the request-shaping seam, so focused transport tests catch it without requiring live Google runs.
• Existing test that already covers this (if any): none for explicit Google cachedContent.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Direct Google Generative AI requests can now send an explicit cachedContent handle via model extra params.

Diagram (if applicable)

Before:
[Google extra params cachedContent] -> [no transport seam] -> [cache handle dropped]

After:
[Google extra params cachedContent] -> [transport option + request field] -> [cachedContent sent]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local worktree
• Model/provider: Google Generative AI transport
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.models["google/gemini-2.5-pro"].params.cachedContent = "cachedContents/test-cache"

Steps

1. Configure cachedContent in Google model extra params.
2. Build a direct Google request through the transport path.
3. Inspect the serialized payload or wrapped stream options.

Expected

• Direct Google payload includes cachedContent.

Actual

• Before this patch, direct Google payloads dropped cachedContent entirely.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Notes:

• Local smoke checks passed for buildGoogleGenerativeAiParams and applyExtraParamsToAgent.
• pnpm exec oxfmt --check passed on all touched files.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: direct Google payload includes cachedContent; Google extra params pass cachedContent through to the stream options; formatting check passed.
• Edge cases checked: trimming empty cachedContent values before request injection.
• What you did not verify: full Vitest completion locally, broader end-to-end Google runs.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: provider-specific cachedContent pass-through could accidentally forward empty or whitespace-only handles.
  • Mitigation: trim and require a non-empty string before injecting the request field.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/google-transport-stream.test.ts (modified, +29/-0)
• src/agents/google-transport-stream.ts (modified, +5/-0)
• src/agents/pi-embedded-runner/extra-params.google.test.ts (modified, +67/-0)
• src/agents/pi-embedded-runner/extra-params.test-support.ts (modified, +2/-0)
• src/agents/pi-embedded-runner/extra-params.ts (modified, +29/-0)