feat(core): add pinFirstUserTurn compaction option for prefix cache stability

[azhen073]

Issue for this PR

N/A — incremental improvement, no issue filed.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Adds a pinFirstUserTurn compaction option. When enabled, the first user message is kept verbatim during compaction instead of being summarized. This keeps the prompt prefix stable across turns, which helps providers with prefix caching (DeepSeek, OpenAI, etc.) reuse cached computation.

The change is tiny (~30 lines, 4 files) and defaults to false, so existing users are unaffected.

Related: #31867 improves DeepSeek cache from the system prompt side (date injection), this one improves it from the compaction side (first user turn protection). They complement each other.

How did you verify your code works?

Reviewed the logic manually:

• V2 select(): the backwards walk now stops before the first user message index when pinFirstUserTurn is set, ensuring it lands in recent instead of head. The index calculation properly accounts for compaction messages being filtered out and serialized messages that evaluate to empty being skipped.
• V1 select(): the first user turn is prepended to the recent turns list when not already included by tail_turns.
• Both paths: default false means no change to current behavior.

I haven't been able to run tests — building requires downloading platform-specific Bun dependencies which timed out in my environment. Happy to run them if a maintainer can suggest a simpler test path.

Screenshots / recordings

N/A — not a UI change.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

• Not all checklist items are checked. Please confirm you have tested locally and have not included unrelated changes.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Potential Duplicate/Related PRs Found:

1. feat: improve deepseek prompt cache reuse #31867 — feat: improve deepseek prompt cache reuse

   • Directly related to your PR's goal of maximizing prompt cache hit rates for DeepSeek. May already address similar functionality or have overlapping approach.

2. fix(cache): improve Anthropic prompt cache hit rate with system split and tool stability #14743 — fix(cache): improve Anthropic prompt cache hit rate with system split and tool stability

   • Addresses prompt cache optimization for another provider (Anthropic). Could have related compaction or prefix-caching logic.

3. fix(session): preserve model message cache snapshots #31613 — fix(session): preserve model message cache snapshots

   • May relate to cache preservation during session operations, potentially overlapping with prefix cache stability concerns.

These are worth reviewing to ensure your new pinFirstUserTurn option doesn't duplicate or conflict with existing cache optimization strategies.

[github-actions]

This pull request has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new pull request that follows our guidelines.