Repository navigation
feat(agent)!: make interrupt, resume and events predictable (ENG-505) - #15
Merged
folathecoder merged 1 commit intoNov 3, 2026
Conversation
Apps worked around the interrupt flag, duplicated tasks on resume and final_answer tool events by reaching into private state or filtering events. These fixes are breaking, so they ship in 0.2.0 with the model contract and apps migrate once. - interrupt() while no run is active does nothing. The flag is cleared once, when a run starts. - AgentSession.resume() continues an interrupted or failed run from memory without adding the task again. run(task, reset=False) still appends it. - A session runs one task at a time: run() or resume() during a run raises RuntimeError. is_running reports whether a run is active. - final_answer produces no ToolCallEvent or ToolResultEvent. The call is still recorded in the ActionStep. - Step callbacks can be async and are awaited in order before the step's StepEvent. The FinalStep is written before they run, so a callback that raises no longer loses the answer. - A tool call cut short by the model's output limit raises ModelOutputTruncatedError instead of asking the model to fix it. - Turns whose tool calls can't be parsed no longer count towards max_steps. - An interrupt during the last step stops the run before the step-limit answer. - run(stream=True) is typed as an async generator, so it works with contextlib.aclosing, and run() as a coroutine, so it works with asyncio.create_task. BREAKING CHANGE: an idle interrupt() no longer stops the next run, run() or resume() on a running session raises RuntimeError, final_answer emits no tool events, and malformed turns no longer use up max_steps.
folathecoder
deleted the
folathecoder/eng-505-020-2-reliability-fixes-bundled-into-the-break
branch
November 3, 2026 07:21
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Apps built on agentling work around its interrupt and event behaviour today by reaching into
AgentSession._interruptor filtering events. This fixes that: an idleinterrupt()no longer stops the next run,resume()continues an interrupted run without repeating the task, a session refuses a second concurrent run, andfinal_answerno longer appears as a tool in the event stream. Step callbacks can be async, and a tool call cut off by the model's output limit raises a clear error instead of asking the model to fix JSON it can't fix. These are breaking changes, so they ship in 0.2.0 with the model contract and apps migrate once.Ticket
ENG-505. Closes ENG-505. Dev plan: ENG-517. Test plan: ENG-518.
Changes
Interrupt and resume (
agent.py)interrupt()while no run is active does nothing. The flag is cleared once, when a run starts. It used to stop the next run before its first step and leave that run's task in memory.AgentSession.resume(stream=False, max_steps=None)continues an interrupted or failed run from memory without adding aTaskStep. It raisesValueError("Nothing to resume")when memory is empty or ends with aFinalStep.run(task, reset=False)still appends the task, as in 0.1.x.One run per session (
agent.py)AgentSession.is_runningisTruefrom the first iteration of a run until it returns or raises.run()orresume()during a run raisesRuntimeError("Session is already running. ..."). Withstream=Truethe error comes from the firstanext, so a stream that is created but never iterated doesn't hold the session._run_streamis now a small guard around the loop body, which moved to_loop. The guard closes the inner generator withcontextlib.aclosing.Events (
agent.py,events.py)final_answerproduces noToolCallEventorToolResultEvent. A step that calls it yields itsStepEvent, then theFinalEvent. The call and its result are still in theActionStep, so memory replays as before.Step callbacks (
agent.py)async. Callbacks run in registration order and are awaited before the step'sStepEvent.StepCallbackis exported for typing.final_answersucceeds, theFinalStepis written before the callbacks run. A callback that raises, or a cancellation while one awaits, no longer loses the answer or leaves the run looking resumable.Cut-off and malformed output (
agent.py,errors.py)ModelOutputTruncatedError(ModelError), not retryable. The loop raises it when a turn's tool call can't be parsed and the turn's lastfinish_reasonis"length", in a normal step and in the step-limit answer. It no longer asks the model to fix such a call. Text cut off by the limit still completes, withFinalEvent.finish_reason == "length".max_steps. Three in a row still raiseModelError.Typing
run(stream=True)andresume(stream=True)are typedAsyncGenerator[Event, None], so they work withcontextlib.aclosing. The non-streaming forms are typedCoroutine[Any, Any, str], so they work withasyncio.create_task. The objects returned haven't changed, and code annotated the 0.1.1 way still passesmypy --strict.Docs
step_callbacksrow and therun()reference are updated, and a new rule covers unparseable and cut-off tool calls.[0.2.0] - Unreleased.How it was tested
uv run pytest: 405 passed in 1.55 s, offline, on Python 3.11.15.uv run ruff check src tests examples,uv run ruff format --check src tests examples,uv run mypy src tests examplesanduv run mypy --strict src: clean.uv buildsucceeds.aclosing;final_answerstep keeps the answer, and the model is called once;mypy --strict;cli_advanced_observer,cli_dynamic_tools,cli_failure_recoveryandcli_memory_chat.agent.pyis 880 lines, +114 against 766.Screenshots / recordings
None: the library has no UI.
Notes for reviewers
_run_stream,_loopandresume()inagent.py, then the interruption and "one run at a time" sections oftests/test_agent.py, then the truncation and step-accounting tests intests/test_model_turns.py.interrupt()stopping the next run, on aToolCallEventforfinal_answer, or on two runs at once on one session.agent.pygrew by 114 lines, more than the 60 to 75 the plan expected. Most of it isresume()with its overloads, the guard and_loopsplit, and two small helpers. The breakdown is on ENG-517.interrupt()made before a run starts iterating is ignored by design. The README example yields once before interrupting.RuntimeErrormessage keeps "Session is already running" as its first sentence and adds a pointer tocontextlib.aclosing, so a match on the first sentence still works.{}and runs, because it can't be told apart from a complete call with no arguments. Afinal_answerwith bad arguments emits no events; its error is on theActionStep, and the README says so.uv run mypy --strict srcto CI. ENG-506 is the testing kit and ENG-507 the release. In ENG-508, Aldwin deletes its three_interrupt.clear()calls and itsfinal_answerfilters, and wraps its streaming loop inaclosing.