diff --git a/tests/agent/test_context_engine_on_turn_complete_usage.py b/tests/agent/test_context_engine_on_turn_complete_usage.py index 6a80b001bba1..b962c983c450 100644 --- a/tests/agent/test_context_engine_on_turn_complete_usage.py +++ b/tests/agent/test_context_engine_on_turn_complete_usage.py @@ -106,3 +106,50 @@ def test_finalize_turn_forwards_none_when_no_response_usage(): captured = agent.context_compressor.captured assert captured.get("seen") is True assert captured["usage"] is None + + +def test_finalization_seam_observes_interrupted_turn_with_none_usage(): + """Pins the documented coverage contract for on_turn_complete(). + + on_turn_complete() fires from the turn-finalization seam and reports + ``usage=None`` on a finalized turn that never reached a provider response + (e.g. interrupt), forwarding the ``interrupted`` flag. This is the testable + (positive) half of the contract. + + The negative half — abnormal early-return paths in ``run_conversation`` + (content-policy block, provider terminal failure, etc.) bypass finalization + and therefore do NOT emit the hook — is documented as best-effort coverage. + It is intentionally not pinned here: exercising those inline early returns + requires a full ``run_conversation`` harness, and unifying all terminal + paths behind one seam is a separate follow-up. + """ + from agent.turn_finalizer import finalize_turn + + agent = _agent_with_engine() + if hasattr(agent, "_last_turn_usage"): + delattr(agent, "_last_turn_usage") # never reached a provider response + + finalize_turn( + agent, + final_response="interrupted mid-turn", + api_call_count=1, + interrupted=True, + failed=False, + messages=[ + {"role": "user", "content": "do a thing"}, + {"role": "assistant", "content": "partial"}, + ], + conversation_history=None, + effective_task_id="task-1", + turn_id="turn-int", + user_message="do a thing", + original_user_message="do a thing", + _should_review_memory=False, + _turn_exit_reason="interrupt", + ) + + captured = agent.context_compressor.captured + assert captured.get("seen") is True + assert captured["usage"] is None + assert captured["kwargs"]["interrupted"] is True + assert captured["kwargs"]["turn_id"] == "turn-int" diff --git a/website/docs/developer-guide/context-engine-plugin.md b/website/docs/developer-guide/context-engine-plugin.md index c0f2dacfa3ea..5e4e941bafa4 100644 --- a/website/docs/developer-guide/context-engine-plugin.md +++ b/website/docs/developer-guide/context-engine-plugin.md @@ -132,7 +132,7 @@ Contract: - **No-op by default, fail-open.** Both default to `return None`. A missing hook, an exception, or an invalid return value leaves the request untouched — so a failing engine is never worse than not installing one. - **`select_context()` is request-only.** The returned list replaces the messages for a single provider call; persisted history is never written. Returning `None`, `[]`, a non-list, or a list containing non-dicts all fall open to the unmodified request. - **Ordering / cache stability.** The hook runs **before** prompt cache-control and every request sanitizer, so (a) a replacement still passes the same validation as any request, and (b) the no-op default leaves the request byte-identical — prompt-cache behaviour is unchanged for non-implementing engines. An engine that replaces the list changes only its own cache prefix. Evaluated per provider request (re-runs on retries). -- **`on_turn_complete()`** is post-turn observation only; treat `messages` as read-only. +- **`on_turn_complete()`** is post-turn observation only; treat `messages` as read-only. **Coverage is best-effort:** it fires from the standard turn-finalization seam. Some abnormal early-return paths in the loop (e.g. a content-policy block or a provider terminal failure) persist and return without routing through finalization, so they do not currently emit this hook — treat it as a best-effort observation for completed turns, not a guaranteed callback for every early exit. Unifying all terminal paths behind one finalization seam is a separate follow-up. ## Engine tools