fix(savings): key a Responses conversation on its thread, not the shared session (#4440)

## Description

`savings_conversation_key` picks `session_id` before `thread_id`. Codex
sends both, flat in `client_metadata`
(`codex-rs/core/src/responses_metadata.rs`, `client_metadata()`), and
its `session_id` is the root thread's id on every request of the
session: the auto-review guardian and spawned subagents carry the root's
`session_id` with their own `thread_id`. All of them land on one key.

`ConversationSavings.novel()` stores each request's running total under
that key, so a guardian request (total 0) resets the root's total, and
the root's next turn books its whole history as new again. With the
guardian running every few turns, a Codex conversation is booked several
times over.

This changes the precedence so a `thread_id` wins over a `session_id`
beside it, at the top level and in `client_metadata`/`metadata`. A body
with only one of the two keys keys exactly as before.

It matters for #4238 too: `prefix_key` in `headroom/proxy/savings.py`
builds on `savings_conversation_key`, so a subagent that shares the
root's model, tools and instructions would still share its baseline.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/conversation_savings.py`: `thread_id` before
`session_id` in both lookup orders; docstring says why.
- `tests/test_proxy/test_conversation_savings.py`: the Codex shape
(shared `session_id`, distinct `thread_id`) yields one key per thread; a
guardian request between two root turns no longer makes the root re-book
its history (`[1000, 0, 200]` instead of `[1000, 0, 1200]`).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ uv run --frozen --extra dev pytest tests/test_openai_codex_ws_lifecycle.py tests/test_output_savings.py tests/test_codex_project_context.py tests/test_savings_items.py tests/test_proxy/test_conversation_savings.py -q
327 passed, 1 warning in 12.64s

# the two new tests against the old lookup order
$ git checkout upstream/main -- headroom/proxy/conversation_savings.py && pytest tests/test_proxy/test_conversation_savings.py -q
2 failed, 20 passed

$ uvx ruff check / ruff format --check (changed files)
All checks passed! / 2 files already formatted
```

## Real Behavior Proof

- Environment: macOS, headroom-ai 0.41.0 as installed by Headroom
Desktop, Codex CLI 0.156.1 over HTTP SSE, real `~/.codex/sessions`
rollouts and a real `~/.headroom/savings_events.jsonl`.
- Exact command / steps: replayed two real Codex sessions request by
request through `_compress_openai_responses_payload` with Kompress warm,
fed each request's running total to `ConversationSavings.novel()` under
per-thread keys vs one session key with a guardian request interleaved,
and compared against the fresh content each request added.
- Observed result: per-thread keys book 16.1% and 11.5% of new input;
with a guardian request after every 5th turn the same sessions book 58%
and 69%. The local ledger on one machine showed a root conversation
re-booking about 45.5k tokens after each guardian call.
- Not tested: the WebSocket path end to end (same lookup order; turns
carrying `previous_response_id` already book per request), and `mypy
headroom`.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Stable.
- Stable/default behavior changed: Yes, Codex savings totals drop to
once per thread; nothing else reads the key.
- Kill switch / disable path: Not applicable.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

Not applicable.

## Additional Notes

- Id-less Codex bodies still key to `None` and book per request; a
fallback key for them is a separate change.
- Related: #4238 (savings redesign), #3480 (the per-conversation
ledger).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4440"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
gglucass
2026-10-24 08:44:03 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 217b658845
commit 11f743dd90
2 changed files with 36 additions and 2 deletions
+6 -2
View File
@@ -75,6 +75,10 @@ def savings_conversation_key(body: Any, *, session_id: str | None = None) -> str
top-level ``conversation_id``/``session_id``/``thread_id``, one of
those inside ``metadata``/``client_metadata``, or a transport-scoped
``session_id`` the caller vouches for (a WebSocket, a session header).
A ``thread_id`` wins over a ``session_id`` beside it: Codex sends both,
and its ``session_id`` is the root thread's on every request of the
session, so a guardian or subagent request would otherwise reset the
root's running total and make its next turn re-book its history.
Two things are deliberately NOT accepted. The holdout key's fallbacks
(the instructions prefix, the literal ``responses``): two independent
conversations with the same instructions would share a running total
@@ -101,7 +105,7 @@ def savings_conversation_key(body: Any, *, session_id: str | None = None) -> str
return None
identity = ""
for key in ("conversation_id", "session_id", "thread_id"):
for key in ("conversation_id", "thread_id", "session_id"):
value = _explicit_id(body.get(key))
if value:
identity = f"{key}:{value}"
@@ -114,8 +118,8 @@ def savings_conversation_key(body: Any, *, session_id: str | None = None) -> str
for key in (
"conversation_id",
"conversation_key",
"session_id",
"thread_id",
"session_id",
"codex_session_id",
):
value = _explicit_id(container.get(key))
@@ -322,6 +322,36 @@ def test_explicit_ids_and_caller_vouched_sessions() -> None:
)
def _codex_body(text: str, thread_id: str, *, session_id: str = "root-thread") -> dict[str, Any]:
"""Codex's shape: both ids flat in ``client_metadata``, the session id
being the root thread's id on every request of the session."""
return _responses_body(text, client_metadata={"session_id": session_id, "thread_id": thread_id})
def test_a_thread_id_wins_over_the_session_beside_it() -> None:
root = savings_conversation_key(_codex_body("fix it", "root-thread"))
guardian = savings_conversation_key(_codex_body("review this", "guardian-thread"))
subagent = savings_conversation_key(_codex_body("explore", "subagent-thread"))
assert None not in (root, guardian, subagent)
assert len({root, guardian, subagent}) == 3
top = _responses_body("x", session_id="s-1", thread_id="t-1")
assert savings_conversation_key(top) == savings_conversation_key(
_responses_body("y", thread_id="t-1")
)
def test_a_side_thread_in_the_session_does_not_re_book_the_root() -> None:
"""Root turns at running totals 1000 then 1200, with the guardian's
request (total 0) in between. Keyed on the shared session the guardian
reset the total and the root booked 1000 + 0 + 1200; keyed per thread
the root books 1000 + 200."""
ledger = ConversationSavings()
root = savings_conversation_key(_codex_body("fix it", "root-thread"))
guardian = savings_conversation_key(_codex_body("review this", "guardian-thread"))
booked = [ledger.novel(root, 1000), ledger.novel(guardian, 0), ledger.novel(root, 1200)]
assert booked == [1000, 0, 200]
def test_server_side_state_means_incremental_input() -> None:
"""With ``previous_response_id`` or a ``conversation`` the provider holds
the history and each payload is a fresh increment: its ``tokens_saved``