8181 "save_result_to_session" ,
8282 "save_resumed_turn_items" ,
8383 "resume_pending_session_write" ,
84+ "record_terminal_checkpoint" ,
8485 "resumed_write_owner" ,
85- "terminal_checkpoint_owner " ,
86- "recoverable_terminal_step " ,
86+ "settleable_terminal_step " ,
87+ "terminal_state_is_unrecoverable " ,
8788 "update_run_state_after_resume" ,
8889 "rewind_session_items" ,
8990 "wait_for_session_cleanup" ,
@@ -723,44 +724,83 @@ async def save_result_to_session(
723724 return saved_run_items_count
724725
725726
726- def terminal_checkpoint_owner (
727+ class TerminalOutputUnrecoverable :
728+ """Marker for a terminal output accepted before a Session append that cannot be restored.
729+
730+ The value itself is never persisted, so a state carrying this marker is resumable only in
731+ the sense that it can be rejected: the run already produced its output and already ran its
732+ terminal hooks, and neither can be reproduced without repeating them.
733+ """
734+
735+ __slots__ = ()
736+
737+ def __repr__ (self ) -> str :
738+ return "<terminal output unrecoverable>"
739+
740+ def __copy__ (self ) -> TerminalOutputUnrecoverable :
741+ return self
742+
743+ def __deepcopy__ (self , memo : dict [int , Any ]) -> TerminalOutputUnrecoverable :
744+ return self
745+
746+
747+ TERMINAL_OUTPUT_UNRECOVERABLE = TerminalOutputUnrecoverable ()
748+
749+
750+ def _terminal_output_is_restorable (output : Any , session : Session | None ) -> bool :
751+ """Return whether an accepted terminal output can be settled on a later resume.
752+
753+ Two things have to survive to the next resume for that to be safe:
754+
755+ - the output itself. Only a plain string round-trips through the RunState codec unchanged;
756+ richer values fall back to ``json.dumps(..., default=str)`` and would change type.
757+ - the rest of the batch's persistence. A compaction-aware Session also records a deferred
758+ compaction, which the checkpoint does not carry and the replay would skip.
759+ """
760+ if type (output ) is not str :
761+ return False
762+ return not is_openai_responses_compaction_aware_session (session )
763+
764+
765+ def record_terminal_checkpoint (
727766 run_state : RunState [Any , Any ] | None ,
728767 session : Session | None ,
729768 * ,
730769 settle_terminal_output : bool ,
731770) -> RunState [Any , Any ] | None :
732- """Return the state that may own a deferred terminal append.
733-
734- A later resume settles this batch by replaying the append alone, so the checkpoint may only
735- be armed when the append really is all that is left of the run:
736-
737- - ``settle_terminal_output`` says every output guardrail completed. Only the successful
738- finalize path can state that, so callers opt in instead of it being inferred from the step:
739- a guardrail that raised must surface on the next resume rather than be settled away.
740- - the accepted output is a plain string. Richer values fall back to
741- ``json.dumps(..., default=str)`` and would change type across the codec, so they keep the
742- existing non-resumable behavior.
743- - the Session owes no post-append maintenance. A compaction-aware Session also records a
744- deferred compaction for the batch, which the checkpoint does not carry, so settling one
745- would drop maintenance the first attempt would have performed.
771+ """Record how an accepted terminal output may be resumed, and return the state that owns it.
772+
773+ Every post-acceptance terminal append gets a checkpoint, so no accepted output can be
774+ silently replayed by a later resume. What differs is what the checkpoint promises: a
775+ restorable output is kept so the resume can settle it, and anything else is replaced by
776+ ``TERMINAL_OUTPUT_UNRECOVERABLE`` so the resume fails closed instead.
777+
778+ ``settle_terminal_output`` says every output guardrail completed. Only the successful
779+ finalize path can state that, so callers opt in rather than it being inferred from the step:
780+ a guardrail that raised must surface on the next resume, not be checkpointed over.
781+
782+ The step is replaced rather than mutated because the live run still holds the same
783+ ``NextStepFinalOutput`` for the result it is building.
746784 """
747785 if not settle_terminal_output or run_state is None :
748786 return None
749787 step = run_state ._current_step
750- if not isinstance (step , NextStepFinalOutput ) or type (step .output ) is not str :
751- return None
752- if is_openai_responses_compaction_aware_session (session ):
788+ if not isinstance (step , NextStepFinalOutput ):
753789 return None
790+ if _terminal_output_is_restorable (step .output , session ):
791+ run_state ._current_step = NextStepFinalOutput (output = step .output )
792+ else :
793+ run_state ._current_step = NextStepFinalOutput (output = TERMINAL_OUTPUT_UNRECOVERABLE )
754794 return run_state
755795
756796
757- def recoverable_terminal_step (run_state : RunState [Any , Any ] | None ) -> NextStepFinalOutput | None :
797+ def settleable_terminal_step (run_state : RunState [Any , Any ] | None ) -> NextStepFinalOutput | None :
758798 """Return the accepted terminal step a resumed run may settle without another model call.
759799
760800 The step is only settleable while the append it is waiting on is still outstanding. The
761- pending write is that record, and it is only armed by ``terminal_checkpoint_owner`` , so its
762- presence is what proves the append was all that remained . Reconciling clears it, so callers
763- capture this before settling it.
801+ pending write is that record, and only ``record_terminal_checkpoint`` arms it , so its
802+ presence is what proves the output was accepted . Reconciling clears it, so callers capture
803+ this before settling it.
764804 """
765805 if run_state is None or run_state ._pending_session_write is None :
766806 return None
@@ -770,6 +810,18 @@ def recoverable_terminal_step(run_state: RunState[Any, Any] | None) -> NextStepF
770810 return step
771811
772812
813+ def terminal_state_is_unrecoverable (run_state : RunState [Any , Any ] | None ) -> bool :
814+ """Return whether this state accepted a terminal output that can no longer be produced.
815+
816+ Unlike a settleable step this does not depend on the pending write. Settling the append
817+ repairs history but cannot bring the output back, so the state stays closed to resumes.
818+ """
819+ step = run_state ._current_step if run_state is not None else None
820+ return isinstance (step , NextStepFinalOutput ) and isinstance (
821+ step .output , TerminalOutputUnrecoverable
822+ )
823+
824+
773825def resumed_write_owner (
774826 run_state : RunState [Any , Any ] | None ,
775827 session : Session | None ,
@@ -778,14 +830,14 @@ def resumed_write_owner(
778830) -> RunState [Any , Any ] | None :
779831 """Return the state that owns a resumed write, so a failed append settles on the next resume.
780832
781- A run-again or interruption step always owns its write. A terminal step only does under the
782- stricter rule in ``terminal_checkpoint_owner``, because settling one ends the run .
833+ A run-again or interruption step always owns its write. A terminal step owns its write once
834+ ``record_terminal_checkpoint`` has recorded how that output may be resumed .
783835 """
784836 if run_state is None :
785837 return None
786838 if isinstance (run_state ._current_step , NextStepRunAgain | NextStepInterruption ):
787839 return run_state
788- return terminal_checkpoint_owner (
840+ return record_terminal_checkpoint (
789841 run_state , session , settle_terminal_output = settle_terminal_output
790842 )
791843
0 commit comments