Repository navigation
release: 1.3.2 — the cycle watchdog counts only the cycle's own admissions; disconnect() from a handler leaves its caller alone; a send cannot carry type "system" - #23
Merged
Conversation
…missions; disconnect() from a handler leaves its caller alone integration.ReceiveLoop: _admit timed every async turn admission, including the ones _pump starts as its own task when a slot frees, outside any cycle. The watchdog breaks only when that counter is 0, so an admission hung there kept it from ever abandoning a hung cycle (and any pump admission's time was left out of the running cycle's deadline). The timing now wraps only the cycle's own admission, in _launch's direct path (and the run, as before). New test: a pump admission that never answers, then a cycle that hangs at its readiness check; it is abandoned at cycle_timeout_ms (the old code never abandoned it). RealtimeClient.disconnect() from inside an async message.new handler always took the whole 1 s dispose grace: the handler's lane worker waits on the handler, which was waiting in disconnect(). That worker now gets no grace but is still cancelled, so a message queued behind the handler never starts. More generally the handler that asks is the caller, neither waited for nor cancelled: message.new, frame and on_connect handlers, whether they await disconnect() directly, through a task (gather, ensure_future, wait_for before 3.12) or fire it off. A ContextVar holds a mark on the task running host handler code (a lane job, an async frame handler's coroutine, the on_connect phase, cleared before the drain); tasks the handler starts copy it. Before, such calls waited out the grace, cancelled the handler, or (3.12+) recursed and never returned. Documented limit, as on main: a handler written as a plain function that returns a task. Tests for each case; each failed on the code before it. CHANGELOG: Unreleased (Fixed).
send_message(type=...) (sync and async) and SendMessageRequest.type take
SendableMessageType ("text" | "structured" | "file", exported from
agentchatme.types). The server refuses "system" on a send with 400
VALIDATION_ERROR. send_message's type was annotated str: literals
type-check as before, a plain str or a Message.type value is now flagged by
a type checker, and SendMessageRequest(type="system") raises
ValidationError. send_message's run-time behaviour is unchanged.
Its own commit: the founder decides whether this narrowing ships in a patch
(VERSIONING.md); reverting this commit takes it out.
…; the founder sets the number)
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.
Why
Three fixes in code that ships in the package:
A hung admission could switch off the cycle watchdog. The receive loop abandons a cycle that runs past
cycle_timeout_ms, but leaves out the time the cycle spends starting its own turns. It measured that with one counter,_turn_depth, and_admitraised it for every async admission, including the ones_pumpstarts as its own task when a slot frees, outside any cycle. The watchdog abandons only while that counter is 0. So a pump admission that never answered kept it from ever abandoning a hung cycle, and any pump admission's time was left out of the running cycle's deadline.disconnect()from inside a message handler always took a full second. An asyncmessage.newhandler runs in a task that its conversation lane's worker waits on.disconnect()gives running handlers a 1 s grace to finish. It skipped the caller, but still waited for the caller's lane worker. That worker was waiting for the caller, which was waiting indisconnect(), so every call ran out the grace.A handler that awaited
disconnect()through a task of its own (asyncio.gather,ensure_future, orwait_forbefore 3.12) was not recognised at all, whatever kind of handler it was (message.new, a frame handler,on_connect). That call could wait out the grace, cancel the handler, or never return; on 3.12+ it hit a recursion error.A send could carry
type="system".send_message'stypewas annotatedstr, andSendMessageRequest.typewasMessageType, which includes"system". The server refuses it on a send with 400VALIDATION_ERROR.What changes
integration/receive_loop.py: the watchdog timing wraps only the cycle's own admission, in_launch's direct path; the run is timed as before._admitno longer times anything itself, so_pump's admissions count for no cycle._realtime.py,_release_dispatches:Who the caller is. It is the calling task plus the handler task that asked. A ContextVar holds a mark on the task running host handler code:
on_connecthandlers while they run. The mark is cleared when they finish, so a task one of them started never shields the drain.Any task the handler starts copies the mark.
The rule: the handler that asks is the caller, and it is neither waited for nor cancelled. That holds whether it awaits
disconnect()directly, through a task, or starts it without awaiting. The last case used to get the grace and then be cancelled; it now runs on, as a handler that awaitsdisconnect()directly always did. Thedisconnect()docstring and the README state the rule, and its one known limit, unchanged from main: a handler written as a plain function that returns a task, instead of anasync def. That task may not be recognised, and adisconnect()from it then waits out the grace or, on 3.12+, may not return.The caller's lane worker gets no grace but is still cancelled with the rest, so a message queued behind the caller is concluded as not handled and never starts.
Other handlers. Running message and frame handlers keep their grace. Async
on_connecthandlers run in an owned task thatdisconnect()cancels without one, as before. The docstring wrongly said otherwise, and now matches the code.types/message.pyand_client.py:send_message(type=...)(sync and async) andSendMessageRequest.typetakeSendableMessageType("text","structured"or"file"), exported fromagentchatme.types.stror aMessage.typevalue now needs narrowing for a type checker.send_messageis unchanged.SendMessageRequest(type="system")raisesValidationError.type=<a str variable>, and constructingSendMessageRequestwith"system"now raises. The server already refuses that send with a 400. VERSIONING.md leaves a change that breaks existing callers to you, so this patch needs your OK on it.pyproject.tomland_version.py, and CHANGELOG 1.3.2.Commits
The three commits are kept apart so the open decisions stay easy to edit:
5a7e685: the fixes, their tests and the docs, with the CHANGELOG underUnreleased.f23f30f: theSendableMessageTypenarrowing only, with its test and the CHANGELOGTypessubsection. If it should not ship in this patch, revert this one commit. That is checked: the revert is clean, and the tests and type-check pass after it.46a3932: the release number only (pyproject.toml,src/agentchatme/_version.pyand the CHANGELOG heading). For a different number, edit those lines.Proof (local)
cycle_timeout_ms(50 ms)disconnect()from a handler, no other lanesdisconnect()from a handler while another conversation's handler runs 0.15 sdisconnect()awaited throughensure_future,gather,wait_for(message handler)RecursionErroron 3.13gather, from a frame handler and from anon_connecthandlerdisconnect()without awaiting it, then works 0.2 s moredisconnect()on_connecthandler started callsdisconnect()during a held drainThe last test guards the cancel. A variant that skipped the cancel failed it: the queued message started after disposal.
The type change, checked with
mypy --strict:"system", a receivedMessageTypeand a plainstrare errors, sync and async;The full gate passes on Python 3.9–3.13: ruff, mypy, and pytest (731 passed, 2 skipped on each). The contract-fixture check matches the published manifest. 15 repeat runs of the new tests on 3.9 and on 3.13: 0 failures.
Test plan
v1.3.2on the merge commit;publish.ymlverify, test and build pass, then thepypiapproval