Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
46 changes: 26 additions & 20 deletions src/agentchatme/gate.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down
Loading