Skip to content

Commit ea43537

Browse files
fix(sessions): reject resuming a run whose accepted terminal output was not persisted
Replaces the hybrid recovery design with the issue's explicit non-resumable contract. Terminal-output persistence, result reconstruction, string-only settlement, the compaction-specific branch, and the settlement control flow in both runners are all gone. A resumed turn that ends via tool_use_behavior appends its terminal batch after the output guardrails, so the run owns an accepted result for the whole of that fallible append. If it failed, the exception propagated but nothing recorded that the output, its guardrails, and its terminal hooks had already completed, so retrying the state ran the model again and repeated the agent lifecycle hooks for a result the caller had already received. RunState now carries a terminal_unrecoverable marker. It is set once the final output, its output guardrails, and its terminal hooks have completed but before the fallible Session append, serialized on the unreleased 1.17 schema boundary, and cleared only after that append and any post-append maintenance both succeed. While it is set, every resume is rejected with an actionable UserError raised ahead of Session reconciliation, sandbox preparation, and any model, tool, guardrail, or hook work.
1 parent aafce1c commit ea43537

5 files changed

Lines changed: 216 additions & 246 deletions

File tree

‎src/agents/run.py‎

Lines changed: 16 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -65,12 +65,12 @@
6565
apply_resumed_conversation_settings,
6666
attach_usage_to_span,
6767
build_interruption_result,
68-
build_recovered_final_output_result,
6968
build_resumed_stream_debug_extra,
7069
ensure_context_wrapper,
7170
finalize_conversation_tracking,
7271
get_unsent_tool_call_ids_for_interrupted_state,
7372
input_guardrails_triggered,
73+
reject_unrecoverable_terminal_state,
7474
resolve_processed_response,
7575
resolve_resumed_context,
7676
resolve_trace_settings,
@@ -140,15 +140,11 @@
140140
persist_session_items_for_guardrail_trip,
141141
prepare_input_with_session,
142142
reconcile_nested_history_owned_session_item_refs,
143-
record_terminal_checkpoint,
144143
resume_pending_session_write,
145144
resumed_turn_items,
146-
resumed_write_owner,
147145
save_result_to_session,
148146
save_resumed_turn_items,
149147
session_items_for_turn,
150-
settleable_terminal_step,
151-
terminal_state_is_unrecoverable,
152148
update_run_state_after_resume,
153149
)
154150
from .run_internal.tool_use_tracker import (
@@ -597,7 +593,6 @@ async def _run_impl(
597593
run_state: RunState[TContext] | None = (
598594
cast(RunState[TContext], input) if is_resumed_state else None
599595
)
600-
resumed_terminal_step: NextStepFinalOutput | None = None
601596
resolved_reasoning_item_id_policy: ReasoningItemIdPolicy | None = (
602597
run_config.reasoning_item_id_policy
603598
if run_config.reasoning_item_id_policy is not None
@@ -641,16 +636,7 @@ async def _run_impl(
641636
)
642637
context = context_wrapper.context
643638

644-
if terminal_state_is_unrecoverable(run_state):
645-
# Fail closed before any Session, sandbox, guardrail, model, tool, or hook
646-
# work: this run already produced an output that cannot be produced again.
647-
raise UserError(
648-
"This RunState accepted a final output that cannot be restored, so the "
649-
"run cannot be resumed. Start a new run instead of retrying this state."
650-
)
651-
# Capture before reconciling: settling the pending write clears the checkpoint
652-
# that proves the output was accepted before the append failed.
653-
resumed_terminal_step = settleable_terminal_step(run_state)
639+
reject_unrecoverable_terminal_state(run_state)
654640
await resume_pending_session_write(run_state, session, wrapper=context_wrapper)
655641
max_turns = run_state._max_turns
656642
else:
@@ -994,30 +980,6 @@ def _mark_response_hooks_started() -> None:
994980
str | list[TResponseInputItem], original_input
995981
)
996982
run_state = cast(RunState[TContext] | None, run_state)
997-
if run_state is not None and resumed_terminal_step is not None:
998-
# Nothing but the Session append was still owed, and it settled above.
999-
# Finish here so no sandbox, guardrail, model, tool, or hook work runs
1000-
# for an output that was already accepted.
1001-
logger.debug("Settling an accepted terminal output")
1002-
result = build_recovered_final_output_result(
1003-
run_state=run_state,
1004-
final_output=resumed_terminal_step.output,
1005-
result_input=original_input,
1006-
session_items=session_items,
1007-
model_responses=model_responses,
1008-
current_agent=current_agent,
1009-
input_guardrail_results=input_guardrail_results,
1010-
output_guardrail_results=output_guardrail_results,
1011-
tool_input_guardrail_results=tool_input_guardrail_results,
1012-
tool_output_guardrail_results=tool_output_guardrail_results,
1013-
context_wrapper=context_wrapper,
1014-
tool_use_tracker=tool_use_tracker,
1015-
max_turns=max_turns,
1016-
current_turn=current_turn,
1017-
generated_items=generated_items,
1018-
)
1019-
run_state._current_step = None
1020-
return _finalize_result(result)
1021983
resuming_turn = is_resumed_state
1022984
all_input_guardrails = (
1023985
starting_agent.input_guardrails + (run_config.input_guardrails or [])
@@ -1205,7 +1167,7 @@ def _mark_response_hooks_started() -> None:
12051167
):
12061168
run_state._current_turn_persisted_item_count = (
12071169
await save_resumed_turn_items(
1208-
run_state=resumed_write_owner(run_state, session),
1170+
run_state=run_state,
12091171
session=session,
12101172
items=turn_session_items,
12111173
persisted_count=(
@@ -1407,19 +1369,11 @@ def _mark_response_hooks_started() -> None:
14071369
current_agent,
14081370
run_config,
14091371
)
1410-
# Reached only after every output guardrail succeeded, so
1411-
# this append is the post-acceptance one.
1412-
if (
1413-
record_terminal_checkpoint(
1414-
run_state, session, settle_terminal_output=True
1415-
)
1416-
is not None
1417-
):
1418-
# Publish the results before the append can raise so a settled
1419-
# retry reports the original evidence instead of a new one.
1420-
run_state._output_guardrail_results = list(
1421-
output_guardrail_results
1422-
)
1372+
# The output, its guardrails, and its terminal hooks are all
1373+
# complete, so from here until the turn is persisted this run owns
1374+
# a result no resume can reproduce.
1375+
if run_state is not None:
1376+
run_state._terminal_unrecoverable = True
14231377
await save_final_turn_items_after_guardrails(
14241378
session=session,
14251379
run_state=run_state,
@@ -1429,9 +1383,11 @@ def _mark_response_hooks_started() -> None:
14291383
response_id=turn_result.model_response.response_id,
14301384
store=store_setting,
14311385
wrapper=context_wrapper,
1432-
# Reached only after every output guardrail succeeded.
1433-
settle_terminal_output=True,
14341386
)
1387+
# The append and any post-append maintenance both succeeded,
1388+
# so the turn is durable and the state is open again.
1389+
if run_state is not None:
1390+
run_state._terminal_unrecoverable = False
14351391
current_step = getattr(run_state, "_current_step", None)
14361392
approvals_from_state = approvals_from_step(current_step)
14371393
result = RunResult(
@@ -2049,6 +2005,8 @@ async def _save_max_turns_handler_output(
20492005
current_agent,
20502006
run_config,
20512007
)
2008+
if run_state is not None:
2009+
run_state._terminal_unrecoverable = True
20522010
await save_final_turn_items_after_guardrails(
20532011
session=session,
20542012
run_state=run_state,
@@ -2059,6 +2017,8 @@ async def _save_max_turns_handler_output(
20592017
store=store_setting,
20602018
wrapper=context_wrapper,
20612019
)
2020+
if run_state is not None:
2021+
run_state._terminal_unrecoverable = False
20622022

20632023
# Ensure starting_input is not None and not RunState
20642024
final_output_result_input: str | list[TResponseInputItem] = (

‎src/agents/run_internal/agent_runner_helpers.py‎

Lines changed: 17 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
from ..agent import Agent
1111
from ..agent_tool_state import set_agent_tool_state_scope
1212
from ..exceptions import UserError
13-
from ..guardrail import InputGuardrailResult, OutputGuardrailResult
13+
from ..guardrail import InputGuardrailResult
1414
from ..items import ModelResponse, RunItem, ToolApprovalItem, TResponseInputItem
1515
from ..memory import Session
1616
from ..models.openai_agent_registration import add_openai_harness_id_to_metadata
@@ -41,11 +41,7 @@
4141
NextStepRunAgain,
4242
ProcessedResponse,
4343
)
44-
from .session_persistence import (
45-
record_terminal_checkpoint,
46-
save_result_to_session,
47-
save_resumed_turn_items,
48-
)
44+
from .session_persistence import save_result_to_session, save_resumed_turn_items
4945
from .tool_use_tracker import AgentToolUseTracker, serialize_tool_use_tracker
5046
from .turn_preparation import get_model
5147

@@ -55,9 +51,9 @@
5551
"attach_usage_to_span",
5652
"build_generated_items_details",
5753
"build_interruption_result",
58-
"build_recovered_final_output_result",
5954
"build_resumed_stream_debug_extra",
6055
"describe_run_state_step",
56+
"reject_unrecoverable_terminal_state",
6157
"ensure_context_wrapper",
6258
"finalize_conversation_tracking",
6359
"get_unsent_tool_call_ids_for_interrupted_state",
@@ -496,53 +492,20 @@ def build_interruption_result(
496492
return result
497493

498494

499-
def build_recovered_final_output_result(
500-
*,
501-
run_state: RunState,
502-
final_output: Any,
503-
result_input: str | list[TResponseInputItem],
504-
session_items: list[RunItem],
505-
model_responses: list[ModelResponse],
506-
current_agent: Agent[Any],
507-
input_guardrail_results: list[InputGuardrailResult],
508-
output_guardrail_results: list[OutputGuardrailResult],
509-
tool_input_guardrail_results: list[ToolInputGuardrailResult],
510-
tool_output_guardrail_results: list[ToolOutputGuardrailResult],
511-
context_wrapper: RunContextWrapper[TContext],
512-
tool_use_tracker: AgentToolUseTracker,
513-
max_turns: int | None,
514-
current_turn: int,
515-
generated_items: list[RunItem],
516-
) -> RunResult:
517-
"""Create a RunResult for a terminal output accepted before a Session append failed."""
518-
identity_root_agent = (
519-
run_state._starting_agent if run_state._starting_agent is not None else current_agent
520-
)
521-
result = RunResult(
522-
input=result_input,
523-
new_items=session_items,
524-
raw_responses=model_responses,
525-
final_output=final_output,
526-
_last_agent=current_agent,
527-
input_guardrail_results=input_guardrail_results,
528-
output_guardrail_results=output_guardrail_results,
529-
tool_input_guardrail_results=tool_input_guardrail_results,
530-
tool_output_guardrail_results=tool_output_guardrail_results,
531-
context_wrapper=context_wrapper,
532-
interruptions=[],
533-
_tool_use_tracker_snapshot=serialize_tool_use_tracker(
534-
tool_use_tracker,
535-
starting_agent=identity_root_agent,
536-
),
537-
max_turns=max_turns,
538-
)
539-
result._current_turn = current_turn
540-
result._model_input_items = list(generated_items)
541-
result._replay_from_model_input_items = list(generated_items) != list(session_items)
542-
result._current_turn_persisted_item_count = run_state._current_turn_persisted_item_count
543-
result._trace_state = run_state._trace_state
544-
result._original_input = copy_input_items(result_input)
545-
return result
495+
def reject_unrecoverable_terminal_state(run_state: RunState | None) -> None:
496+
"""Fail closed when a previous run already produced a final output that cannot be reproduced.
497+
498+
The marker is set once that output, its guardrails, and its terminal hooks have completed,
499+
and is cleared only once the turn is fully persisted. In between, the run owns a result no
500+
resume can settle, so resuming would repeat the model call and the lifecycle hooks for an
501+
output the caller already received. Raised before any Session, sandbox, model, tool,
502+
guardrail, or hook work so the rejection has no side effects of its own.
503+
"""
504+
if run_state is not None and run_state._terminal_unrecoverable:
505+
raise UserError(
506+
"This RunState already produced a final output whose Session write did not "
507+
"complete, so it cannot be resumed. Start a new run instead."
508+
)
546509

547510

548511
def append_model_response_if_new(
@@ -619,19 +582,12 @@ async def save_final_turn_items_after_guardrails(
619582
reasoning_item_id_policy: ReasoningItemIdPolicy | None = None,
620583
store: bool | None = None,
621584
wrapper: RunContextWrapper[Any] | None = None,
622-
settle_terminal_output: bool = False,
623585
) -> int:
624586
"""Persist deferred final-turn items without skipping a partially persisted resumed turn."""
625587
if not session_persistence_enabled or not items:
626588
return 0
627589
if input_guardrails_triggered(input_guardrail_results):
628590
return 0
629-
# An accepted terminal output is appended after the output guardrails, so this is the last
630-
# fallible step of the run. Only the caller that saw every guardrail succeed opts in to
631-
# checkpointing it, and the checkpoint records whether a resume may settle it or must reject.
632-
terminal_write_state = record_terminal_checkpoint(
633-
run_state, session, settle_terminal_output=settle_terminal_output
634-
)
635591
if run_state is not None and run_state._current_turn_persisted_item_count > 0:
636592
run_state._current_turn_persisted_item_count = await save_resumed_turn_items(
637593
session=session,
@@ -641,7 +597,6 @@ async def save_final_turn_items_after_guardrails(
641597
reasoning_item_id_policy=run_state._reasoning_item_id_policy,
642598
store=store,
643599
wrapper=wrapper,
644-
run_state=terminal_write_state,
645600
)
646601
return run_state._current_turn_persisted_item_count
647602
return await save_result_to_session(
@@ -653,7 +608,6 @@ async def save_final_turn_items_after_guardrails(
653608
reasoning_item_id_policy=reasoning_item_id_policy,
654609
store=store,
655610
wrapper=wrapper,
656-
resumed_write_state=terminal_write_state,
657611
)
658612

659613

0 commit comments

Comments
 (0)