Summary

• Problem: #59054 fixed the cache boundary on several transport builders, but three request paths still bypassed that shaping: compaction, OpenAI WS HTTP fallback, and later turns reusing a previously wrapped session stream.
• Why it matters: those paths could still leak <!-- OPENCLAW_CACHE_BOUNDARY --> into provider-visible prompt text or skip the intended Anthropic/OpenAI cache shaping, which risks cache misses and divergent prompt bytes across turns.
• What changed: moved embedded stream resolution into a shared helper, rebuilt each turn from the session's original base stream, routed compaction through the same stream/extra-param/transport stack as normal turns, and made OpenAI WS HTTP fallback use the boundary-aware HTTP builder instead of raw streamSimple.
• What did NOT change (scope boundary): no new provider-specific cache policy was added for custom plugin streams beyond boundary stripping; no live-cache assertions or pricing logic changed.

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 fix(agents): split system prompt cache prefix by transport #59054
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: cache-boundary logic was added at transport-builder seams, but some agent request paths still bypassed those seams and talked to provider streams directly.
• Missing detection / guardrail: there was no regression coverage for compaction transport shaping, WebSocket HTTP fallback shaping, or stale wrapped session streams after model/provider changes.
• Contributing context (if known): #59054 merged before these follow-up path divergences were fully enumerated.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Seam / integration test
  • Unit test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • src/agents/pi-embedded-runner/run/attempt.test.ts
  • src/agents/pi-embedded-runner/compact.hooks.test.ts
  • src/agents/openai-ws-stream.test.ts
• Scenario the test should lock in: default turns rebuild from the session's original base stream, compaction goes through the shared transport/extra-param stack, and WS fallback uses the boundary-aware HTTP builder instead of raw streamSimple.
• Why this is the smallest reliable guardrail: the bug is in orchestration seams between session setup and provider request shaping, not in the individual transport builders themselves.
• Existing test that already covers this (if any): transport-specific stripping tests already existed for OpenAI/Google/Anthropic builders.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Provider-visible system prompts no longer diverge across compaction, WS fallback, and later-turn stream reuse paths.
• Anthropic/OpenAI cache shaping is now consistent across those paths.

Diagram (if applicable)

Before:
[embedded turn/compaction/ws fallback] -> [path-specific stream fn] -> [raw provider request]

After:
[embedded turn/compaction/ws fallback] -> [shared stream resolution] -> [boundary-aware transport shaping] -> [provider request]

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm worktree
• Model/provider: OpenAI Responses, OpenAI WS fallback, Anthropic-family, provider-owned streams
• Integration/channel (if any): N/A
• Relevant config (redacted): default embedded-agent transport paths

Steps

1. Build an embedded system prompt containing the internal cache boundary.
2. Exercise compaction, WebSocket fallback, or later-turn session stream reuse.
3. Inspect the provider-facing stream/payload context.

Expected

• Provider-visible prompt text does not contain the internal boundary marker.
• Shared transport shaping is reused across all affected paths.

Actual

• Some paths bypassed the shared shaping layer and could emit raw boundary text or stale transport behavior.

Evidence

Attach at least one:

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

Human Verification (required)

• Verified scenarios: manual code-path audit against Claude Code / Codex cache patterns; diff review of all request-entry seams; regression tests added for stale stream reuse, compaction shaping, and WS fallback builder selection.
• Edge cases checked: provider-owned createStreamFn, default streamSimple fallback, WS fallback, compaction, later-turn stream wrapper reuse.
• What you did not verify: live provider cache hit-rate runs; full pnpm build and targeted Vitest were non-reporting in this environment during the final pass.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: session stream resolution now caches the original base stream per session object.
  • Mitigation: cache is a WeakMap, only used to rebuild from the original base stream, and is resettable in tests.
• Risk: compaction now uses more of the normal embedded turn setup path.
  • Mitigation: scope stays limited to stream resolution, extra params, and transport override; compaction-specific behavior remains unchanged otherwise.