Skip to content

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
sanctrl merged 3 commits into
mainfrom
fix/kit-watchdog
Nov 12, 2026
Merged

sanctrl merged 3 commits into
mainfrom
fix/kit-watchdog

Conversation

@sanctrl

@sanctrl sanctrl commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

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 _admit raised it for every async admission, including the ones _pump starts 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 async message.new handler 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 in disconnect(), so every call ran out the grace.

    A handler that awaited disconnect() through a task of its own (asyncio.gather, ensure_future, or wait_for before 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's type was annotated str, and SendMessageRequest.type was MessageType, which includes "system". The server refuses it on a send with 400 VALIDATION_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. _admit no 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:

      • a lane job's handlers;
      • an async frame handler's coroutine, through a small wrapper (a handler that returns a task is its own dispatch task already);
      • the on_connect handlers 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 awaits disconnect() directly always did. The disconnect() 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 an async def. That task may not be recognised, and a disconnect() 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_connect handlers run in an owned task that disconnect() cancels without one, as before. The docstring wrongly said otherwise, and now matches the code.

  • types/message.py and _client.py:
    • send_message(type=...) (sync and async) and SendMessageRequest.type take SendableMessageType ("text", "structured" or "file"), exported from agentchatme.types.
    • The literals type-check as before; a plain str or a Message.type value now needs narrowing for a type checker.
    • At run time send_message is unchanged. SendMessageRequest(type="system") raises ValidationError.
    • For the founder: this breaks two undocumented patterns. A type checker rejects type=<a str variable>, and constructing SendMessageRequest with "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.
  • Version 1.3.2 in pyproject.toml and _version.py, and CHANGELOG 1.3.2.

Commits

The three commits are kept apart so the open decisions stay easy to edit:

  1. 5a7e685: the fixes, their tests and the docs, with the CHANGELOG under Unreleased.
  2. f23f30f: the SendableMessageType narrowing only, with its test and the CHANGELOG Types subsection. 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.
  3. 46a3932: the release number only (pyproject.toml, src/agentchatme/_version.py and the CHANGELOG heading). For a different number, edit those lines.

Proof (local)

Test On main With this change
Watchdog: a pump admission that never answers, then a cycle that hangs at its readiness check never abandoned; times out after 2 s abandoned at cycle_timeout_ms (50 ms)
disconnect() from a handler, no other lanes 1.00 s well under 0.5 s
disconnect() from a handler while another conversation's handler runs 0.15 s 1.00 s waits for that handler, which finishes uncancelled, and no longer
A message queued behind the caller in its lane passes, slowly never starts
disconnect() awaited through ensure_future, gather, wait_for (message handler) 1.00 s, or never returns; RecursionError on 3.13 well under 0.5 s; the handler goes on
The same through gather, from a frame handler and from an on_connect handler fails on the previous commit well under 0.5 s; the handler goes on
A handler that starts disconnect() without awaiting it, then works 0.2 s more — not cancelled; it finishes
A frame handler that returns a task, which awaits disconnect() fails on the previous commit (1.0 s; recursion on 3.13) well under 0.5 s
A task an on_connect handler started calls disconnect() during a held drain fails on the previous commit (the drain survives) the drain is cancelled

The 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:

  • the three literals and a narrowed value pass;
  • "system", a received MessageType and a plain str are errors, sync and async;
  • main's SDK accepts all of them.

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

  • CI green on this PR (3 OS × 3 Python)
  • After merge: tag v1.3.2 on the merge commit; publish.yml verify, test and build pass, then the pypi approval

…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.
@sanctrl
sanctrl merged commit 8368a78 into main Nov 12, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant