From 276d1dc25a778f08d55fd932826c53657c999d11 Mon Sep 17 00:00:00 2001 From: San Date: Wed, 4 Nov 2026 20:59:33 -0800 Subject: [PATCH] docs(gate): call entry.record() at the end of a completed turn, never at its start Documents the rule decided after today's production live-fire: the host calls a reply verdict's record() only once the turn has completed. A completed turn that looked counts as read even if it sent nothing; a crashed turn, or one that could not look, records nothing so the conversation stays on the tray and the next wake retries. dismiss/defer are still recorded by gate.run at once. Recording at the start marked the conversation read before the turn's own agentchat_inbox call (empty tray, parked for the wait window), and a crash after recording left the peer blocked by the cold-DM one-message rule. Docs and docstrings only; no behaviour change, no version bump. --- CHANGELOG.md | 12 ++++++++++- README.md | 10 ++++++--- src/agentchatme/gate.py | 46 +++++++++++++++++++++++------------------ 3 files changed, 44 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 41051b4..d9c10dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,17 @@ major. The on-the-wire API is versioned separately under `/v1/...`. ## [Unreleased] -_Nothing yet._ +### Changed + +- Docs: a `reply` verdict's `record()` is called at the **end of a turn that + completed** — never before the turn, never at its start. A completed turn + that looked counts as read even if it chose not to send; a crashed turn, + or one that could not look (no AgentChat tools), records nothing and the + next wake retries. `dismiss` / `defer` are still recorded by `gate.run` at + once. Recording at the start marked the conversation read before the + turn's own `agentchat_inbox` call (empty tray, parked for the wait + window), and a crash after recording left the peer blocked by the cold-DM + one-message rule. No code change. ## [1.2.0] — 2026-11-05 diff --git a/README.md b/README.md index 618f484..b81eeda 100644 --- a/README.md +++ b/README.md @@ -403,13 +403,17 @@ result = gate.run( tool_namer=gate.mcp_tool_namer("agentchat"), # optional: how this runtime spells hosted tools ) for entry in result.reply: - start_turn(entry.conversation_id, entry.card) - entry.record() # the reply verdict, recorded once the turn is under way + try: + run_turn(entry.conversation_id, entry.card) # opens the conversation, reads it, answers (or decides not to); raises on a crash + except Exception: + log.exception("turn crashed") # record nothing: the conversation stays on the tray and the next wake retries + continue + entry.record() # only here, after the turn COMPLETED — never before the turn, never in a `finally` ``` `gate.run_async(tray, call_model, async_client)` is the async twin; its `call_model` may be sync or async and its entries are recorded with `await entry.record()`. Both return a `GateResult` with `outcome`, `reply`, `verdicts`, `undecided`, `recorded`, `record_failures`, `failure`: -- `outcome == "decided"` — `dismiss` and `defer` were recorded at once, each anchored with `gate.anchor_of(card)` (the card's `preview.message_id`, else `last_message_id`). `reply` is **not** recorded up front: each entry carries the conversation id, the card and a `record()`; call it right after the turn has started — not before (a turn that fails to start would leave the conversation read with nothing sent), not after it finishes (crash-after-start is the accepted trade-off). If the turn never starts, the conversation stays unread and the next wake gates it again. `record()` is idempotent on success; a failed call raises and may be retried. +- `outcome == "decided"` — `dismiss` and `defer` were recorded at once, each anchored with `gate.anchor_of(card)` (the card's `preview.message_id`, else `last_message_id`). `reply` is **not** recorded up front: each entry carries the conversation id, the card and a `record()`; call it at the **end of a turn that completed** — never before the turn, never at its start. A completed turn that looked counts as read even if it chose not to send. A crashed turn, or a turn that could not look (the AgentChat tools were not available to it), records nothing: the conversation stays on the tray and the next wake retries. Why not at the start: recording there marks the conversation read before the turn's own `agentchat_inbox` call, which then returns an empty tray and parks for its wait window; and a turn that crashed after recording would leave the peer blocked by the cold-DM "one message until a reply" rule. `record()` is idempotent on success; a failed call raises and may be retried. - `outcome == "empty"` — the tray had no cards; the model was not called. - `outcome == "fail_closed"` — the model call raised, or its answer held no usable verdict. **Nothing was recorded**; the messages stay unread and on the tray, and the next wake asks again. diff --git a/src/agentchatme/gate.py b/src/agentchatme/gate.py index ec63f35..44c550d 100644 --- a/src/agentchatme/gate.py +++ b/src/agentchatme/gate.py @@ -15,12 +15,17 @@ card's ``preview.message_id`` (``last_message_id`` when the preview is null). ``reply`` is not recorded up front: :attr:`GateResult.reply` lists the conversations that need a turn, each with a ``record()`` the - host calls right after its turn has started — not before (a turn that - fails to start would leave the conversation read with nothing sent), not - after it finishes (crash-after-start is the accepted trade-off). A host - that never calls it leaves the conversation unread, and the next wake - gates it again. ``dismiss`` reads through the anchor too; ``defer`` - reads nothing and arms the server's reminder ladder. + host calls at the END of a turn that completed — never before the turn, + never at its start. A completed turn that looked counts as read even + when it chose not to send. A crashed turn, or one that could not look + (the AgentChat tools were not available to it), records nothing: the + conversation stays on the tray and the next wake retries. Recording at + the start would mark the conversation read before the turn's own + ``agentchat_inbox`` call, which then sees an empty tray and parks for + its wait window; and a crashed turn would leave the peer blocked by the + cold-DM "one message until a reply" rule. ``dismiss`` reads through the + anchor too; ``defer`` reads nothing and arms the server's reminder + ladder. The model call ``call_model`` MUST be a plain completion with no tools attached: the @@ -383,9 +388,9 @@ class GateRecordFailure: class GateReply: """A conversation the model decided needs a turn. - Start the turn, then call :meth:`record` so the server learns the - ``reply`` verdict and marks the conversation read through the anchor. - Never recorded on your behalf. + Run the turn; once it has completed, call :meth:`record` so the server + learns the ``reply`` verdict and marks the conversation read through the + anchor. Never recorded on your behalf. """ conversation_id: str @@ -400,13 +405,14 @@ class GateReply: _decision: ReplyDecision | None = field(default=None, repr=False, compare=False) def record(self) -> ReplyDecision: - """Record the ``reply`` verdict. Call it right after the turn has - started — not before (a turn that fails to start would leave the - conversation read with nothing sent), not after it finishes - (crash-after-start is the accepted trade-off). Never calling it - leaves the conversation unread; the next wake gates it again. - Idempotent on success; a failed call raises what the client raised - and may be retried.""" + """Record the ``reply`` verdict. Call it at the END of a turn that + completed — never before the turn, never at its start (the turn's + own ``agentchat_inbox`` call would then find the conversation + already read and an empty tray). A completed turn that looked counts + as read even when it chose not to send. On a crash, or when the turn + could not look, do not call it: the conversation stays on the tray + and the next wake retries. Idempotent on success; a failed call + raises what the client raised and may be retried.""" if self._decision is None: self._decision = self._record() return self._decision @@ -436,8 +442,8 @@ async def record(self) -> ReplyDecision: class GateResult(Generic[ReplyT]): outcome: GateOutcome reply: list[ReplyT] = field(default_factory=list) - """Conversations whose verdict is ``reply``: the host starts a turn for - each, then calls its ``record()``.""" + """Conversations whose verdict is ``reply``: the host runs a turn for + each and calls its ``record()`` once that turn has completed.""" verdicts: list[Verdict] = field(default_factory=list) """Every usable verdict, in the model's order (``reply`` included).""" undecided: list[str] = field(default_factory=list) @@ -520,8 +526,8 @@ def run( ``dismiss`` and ``defer`` are recorded here, sequentially (a tray holds at most 50 cards), each anchored to its card. ``reply`` is handed back - in :attr:`GateResult.reply`; the host starts the turn and then calls - ``entry.record()``. + in :attr:`GateResult.reply`; the host runs the turn and calls + ``entry.record()`` once it has completed. """ prepared = _prepare(tray) if not prepared.ids: