Origin / follow-up

Follow-up to #96970 and the same bounded-reader fan-out strategy from #96505. #96970 applied the shared provider JSON cap to ClickClack REST success responses; this PR applies the same source-of-truth reader to Google Gemini TTS success JSON responses.

Summary

• Route Google Gemini TTS success JSON parsing through readProviderJsonResponse.
• Keep the existing Google TTS request construction, retry behavior, voice/model selection, and PCM extraction unchanged.
• Add regression coverage for oversized Gemini TTS success JSON stream cancellation.
• Add loopback HTTP proof that exercises real postJsonRequest, real fetch, and real readProviderJsonResponse for both a normal small response and an oversized success body.

Maintainer-ready fields

• Behavior or issue addressed: Google Gemini TTS success responses crossed the provider HTTP boundary through raw response.json() instead of OpenClaw's shared bounded provider JSON reader.
• Fix classification: Root cause fix
• Root cause: Root cause source: the Google TTS success-response parser bypassed the canonical provider response-size contract because synthesizeGoogleTtsPcmOnce() called raw await res.json() after postJsonRequest returned a successful Response.
• Why this is root-cause fix: The Google TTS PCM extraction path has one success JSON parse point, so moving that parse point onto readProviderJsonResponse restores the response-size invariant before downstream audio payload extraction and retry handling.
• Real environment tested: A deterministic loopback HTTP server was exercised through real postJsonRequest, real fetch, and real readProviderJsonResponse. The proof covers a normal small Google TTS-style JSON envelope and an oversized success JSON stream that closes before the full 18 MiB response is sent.
• Exact steps or command run after this patch: Ran the Google speech provider Vitest target, ran pnpm check:test-types, then ran the loopback proof with pnpm --dir /media/vdb/code/ai/aispace/openclaw-worktrees/pr-96984 exec tsx /media/vdb/code/ai/aispace/openclaw-pr-96984-evidence/google-tts-loopback-proof.ts.
• Evidence after fix: The Google speech provider test file passed with 18 tests; typechecking passed; the loopback proof returned small_status=200, small_pcm_bytes=4, and oversized_error=Google TTS response: JSON response exceeds 16777216 bytes.
• Observed result after fix: The small loopback response parsed normally into the existing inline audio payload shape, while the oversized success response failed at the shared 16 MiB cap and the loopback server observed early stream close at 16,908,288 bytes, before the 18 MiB response completed.
• What was not tested: External Google account setup, model availability, and hosted speech synthesis semantics remain outside this patch; request construction, endpoint trust validation, model/voice selection, PCM extraction, and audio conversion are unchanged.
• Why it matters / User impact: Oversized Google TTS success responses now fail deterministically at the shared provider JSON cap instead of being materialized by native JSON parsing before PCM extraction.
• What did NOT change: Google TTS auth headers, trusted base URL validation, request body shape, retry count, model/voice normalization, PCM extraction, WAV wrapping, Opus transcoding behavior, and persisted runtime data formats are unchanged.
• Architecture / source-of-truth check: The canonical source-of-truth for provider response-size enforcement is openclaw/plugin-sdk/provider-http; this change moves Google TTS success JSON parsing onto that shared contract before downstream typed response projection.
• Target test file: extensions/google/speech-provider.test.ts.
• Scenario locked in: A real Response with a ReadableStream body larger than 16 MiB is returned to the Google TTS success path; the reader rejects at the cap and cancels the stream on both retry attempts.
• Why this is the smallest reliable guardrail: One parse-site change in synthesizeGoogleTtsPcmOnce() covers the only Google TTS success JSON path without touching provider configuration, request generation, audio extraction, or retry policy.
• Risk labels considered: merge-risk: 🚨 compatibility, behavior-change: oversized-provider-response, and auth-provider.
• Risk explanation: The compatibility change is limited to Google TTS success JSON bodies above the shared 16 MiB cap; auth, endpoint trust, schema expectations, and audio conversion behavior are unchanged.
• Why acceptable: Normal Gemini TTS JSON envelopes should be far below 16 MiB, and early rejection matches the provider response-body policy used by fix(openrouter): bound video catalog JSON reads #96505 and fix(clickclack): bound REST success JSON response reads #96970.
• Maintainer-ready confidence: High for the code change and loopback proof; maintainers still need to explicitly accept the 16 MiB compatibility boundary before merge.
• Patch quality notes: Focused three-file diff, no repository evidence files, no unrelated cleanup, RED failure captured raw response.json() behavior, GREEN verification covers target behavior and test typechecking, and loopback proof covers the requested HTTP boundary.

What Problem This Solves

Google TTS already uses the shared provider HTTP request path, but its successful Gemini response body was still parsed with raw native JSON parsing. This left the success response path outside the bounded-reader guardrail used for provider JSON responses elsewhere.

Root Cause

The Google TTS implementation bounded provider errors through the shared HTTP stack but parsed successful JSON locally with await res.json(). That split the response-body contract: unsuccessful responses were normalized through shared helpers, while successful TTS JSON bypassed the shared size cap before audio payload extraction.

Why it matters / User impact

A too-large Gemini TTS success response can otherwise be buffered by native JSON parsing before OpenClaw has a chance to reject it. The patch makes the failure deterministic and closes the body stream once the shared cap is exceeded.

What did NOT change

• Google TTS model and voice defaults are unchanged.
• Google trusted base URL validation and request header construction are unchanged.
• PCM extraction, WAV wrapping, Opus transcoding, and retry count are unchanged.
• No new Google-specific response-size constant was introduced.
• No persisted runtime data model or migration path changes were introduced; the helper change is limited to provider test mocks.

Architecture / source-of-truth check

OpenClaw already owns provider response-size enforcement in openclaw/plugin-sdk/provider-http. Google TTS now uses that shared reader for successful Gemini JSON responses instead of maintaining a local native JSON parse path.

Target test file

extensions/google/speech-provider.test.ts

Scenario locked in

The regression returns a real Response with a ReadableStream body of 16 * 1024 * 1024 + 1 bytes to the Google TTS success path. The json() method is a sentinel: the test fails on the old code when the sentinel is called, and passes after the code reads the stream through the bounded reader.

Evidence

RED observation against the raw response.json() implementation:

AssertionError: expected [Function] to throw error including 'Google TTS response: JSON response ex…' but got 'unbounded json reader was used'

Expected: "Google TTS response: JSON response exceeds 16777216 bytes"
Received: "unbounded json reader was used"

GREEN target test:

Test Files  1 passed (1)
Tests  18 passed (18)

Test typecheck:

$ pnpm tsgo:test
$ pnpm tsgo:core:test && pnpm tsgo:extensions:test
$ node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo
$ node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.extensions.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/extensions-test.tsbuildinfo

Loopback HTTP proof

The follow-up proof uses a local loopback HTTP server and sends requests through real postJsonRequest with real fetch, then parses the returned Response through real readProviderJsonResponse.

The small path returns a Google TTS-style JSON envelope with inline PCM audio data. The oversized path streams an 18 MiB success response and records where the server sees the client close the connection.

Command:

pnpm --dir /media/vdb/code/ai/aispace/openclaw-worktrees/pr-96984 exec tsx /media/vdb/code/ai/aispace/openclaw-pr-96984-evidence/google-tts-loopback-proof.ts

Observed output:

small_status=200
small_mime=audio/L16;codec=pcm;rate=24000
small_pcm_bytes=4
oversized_error=Google TTS response: JSON response exceeds 16777216 bytes
oversized_closed_bytes=16908288
oversized_exceeded_cap=true
oversized_closed_before_full_response=true
small_requests=1
oversized_requests=1

This directly covers the requested loopback proof: normal small response parsing succeeds, the oversized success body fails with the bounded-reader error, and the server observes early close before the full 18 MiB response is sent.

Real behavior proof

The unit regression exercises the actual Google speech provider code path after postJsonRequest returns a successful Response. The follow-up loopback proof additionally exercises the real HTTP request boundary through postJsonRequest, real fetch, and readProviderJsonResponse.

Google TTS response: JSON response exceeds 16777216 bytes
cancelCount = 2
release calls = 2

small_status=200
small_pcm_bytes=4
oversized_closed_before_full_response=true

Review findings addressed

• RF-001 — fixed: Added loopback HTTP proof that shows both normal small Google TTS-style response parsing and oversized success JSON early close through real postJsonRequest, real fetch, and real readProviderJsonResponse.
• RF-002 — fixed: The proof now crosses the HTTP boundary through a loopback server instead of stopping at a mocked postJsonRequest unit boundary.
• RF-003 — fixed: The loopback output includes small_status=200, small_pcm_bytes=4, oversized_error=Google TTS response: JSON response exceeds 16777216 bytes, and oversized_closed_before_full_response=true.
• RF-004 — maintainer-decision: Existing Google TTS success JSON bodies above the shared 16 MiB cap will now fail early. This is the intentional hardening boundary of the patch and should be explicitly accepted by maintainers before merge.
• RF-005 — maintainer-decision: The remaining non-code item is maintainer acceptance of the compatibility boundary; the contributor-side proof gap has been addressed with the loopback output above.

External environment disclosure

No external Google account, API credential, or hosted Google TTS synthesis call was used for this follow-up. The completed verification uses the reviewer-requested loopback option and exercises the provider HTTP request path locally through real postJsonRequest, real fetch, and real readProviderJsonResponse.

Verification

pnpm --dir /media/vdb/code/ai/aispace/openclaw-worktrees/followup-96970 exec vitest --config test/vitest/vitest.extension-providers.config.ts run extensions/google/speech-provider.test.ts
pnpm --dir /media/vdb/code/ai/aispace/openclaw-worktrees/followup-96970 check:test-types
pnpm --dir /media/vdb/code/ai/aispace/openclaw-worktrees/pr-96984 exec tsx /media/vdb/code/ai/aispace/openclaw-pr-96984-evidence/google-tts-loopback-proof.ts

Regression Test Plan

• Target test file: extensions/google/speech-provider.test.ts.
• Scenario locked in: oversized Gemini TTS success JSON response body crosses the 16 MiB cap.
• Why this is the smallest reliable guardrail: the test targets the single Google TTS success parse site and verifies both stream cancellation and retry cleanup without changing request construction.

Merge risk

• Detected category: auth-provider, because the changed production file is the Google provider implementation.
• Compatibility: Existing Google TTS success JSON bodies above the shared 16 MiB cap now fail early instead of being buffered by native JSON parsing; maintainers should explicitly accept this boundary.
• Unchanged behavior: Existing auth headers, trusted base URL validation, request payloads, response schema expectations, retry count, and audio conversion behavior are unchanged.
• Related open PR scan: Alix-007 open PR comparison found no extensions/google/speech-provider.ts overlap; fix(speech): bound TTS response reads #96874 covers Volcengine/Xiaomi TTS, fix(vydra): bound control response reads #96875 covers Vydra speech, and fix(feishu,browser,msteams,azure-speech,bedrock-mantle,googlechat,huggingface,perplexity): bound JSON response reads #96620 covers GoogleChat/Azure Speech rather than Google Gemini TTS.
• Out-of-scope boundary: This PR does not change Google account setup, provider configuration defaults, endpoint allowlists, model selection, voice selection, speech synthesis semantics, or audio transcoding.

Risk labels considered

• merge-risk: 🚨 compatibility
• behavior-change: oversized-provider-response
• auth-provider detected and explained above

Risk explanation

The only intended behavior change is that Google TTS success JSON bodies over the shared provider cap now fail early with a bounded-reader error. Existing valid responses continue into the same extractGoogleSpeechPcm path.

Why acceptable

The patch aligns Google TTS with OpenClaw's shared provider response-body boundary and keeps the change at the only success JSON parse point. The proof covers both the oversized boundary and a normal small response over loopback HTTP, and existing speech-provider tests continue to pass.

Maintainer-ready confidence

High for contributor-side readiness. The root cause is localized, the diff is small, related open PR overlap was checked, fresh CI is green on commit 9ce6c78521924393bfc72560f5a1a3cb9f6dbf9a, and loopback HTTP proof now covers the requested real boundary. The remaining merge decision is maintainer acceptance of the 16 MiB compatibility boundary.

Patch quality notes

• No unrelated formatting, docs, lockfile, or runtime config changes.
• The shared test helper now exports readProviderJsonResponse so existing provider tests can exercise production code that imports the shared reader.
• The test verifies the old raw-JSON path failed before the fix and the bounded-reader path cancels streams after the fix.
• The loopback proof verifies small-response parsing and oversized-response early close through the provider HTTP boundary.

Competition / linked PR analysis

This PR is intentionally separate from #96970: #96970 covers ClickClack REST success JSON reads, while this PR covers Google Gemini TTS success JSON reads. Related open PR scan found no competing Google Gemini TTS bounded-reader PR.