Repository navigation
fix(acp): keep an agent-started turn readable through a request wait - #38313
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS This is a fix for two named transport defects. It changes no default, and each item it adds has exactly one caller. What this change shipsInventory (5 items) — 5 justifiedIntent: On the claude backend, a reply the agent sends on its own should show as its own message even when a request wait overlaps it, and a cycle that goes silent should not hold the chat for hours. This is a FIX.
[FIRST-PRINCIPLES-REVIEWED] 6f96241 Description read[DESCRIPTION-READ] 340ab274c2d2590e344d5d04994474925840f736440f0aa29573ae42ac94d5fb That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: the provider probe counts the held frames, the stream waits on the hold's end event, and only the agent-started read path arms the existing stale-turn gate earlier. Notes
[DESIGN-REVIEWED] 6f96241 Description read[DESCRIPTION-READ] 2f702f6c886b4a48daf6867853ff5e0b140aefa99e282d9b221697902e01f333 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
On the claude backend, a request wait that runs while a turn the agent started waits to be read (a live config push, a compaction wait) holds that turn's frames until it returns. The provider's pending probe read False meanwhile, so the dashboard turn started for the agent ended before it opened, or stream_unsolicited() returned at once. The frames went back to the buffer with no reader left, and the reply waited for the user's next message again. has_pending_agent_turn() counts the held first frame, and the provider's agent_turn_pending() reads it. stream_unsolicited() waits until the holding reader has put the frames back, or a kill or reset has dropped them, before it checks. An agent-started cycle that goes quiet after a thought, a plan or an answered permission request, with no closing usage_update, held the read and its chat slot until the prompt timeout: the stale-turn gate armed only after text. Under the agent-started request id it now arms from the turn's first activity frame. An open tool call still leaves the tool-stall watchdog in charge, and user turns are unchanged. Refs #17566 Ported onto main from #30797; the provider probe keeps main's AcpSessionProvider branch, and _read_turn keeps main's backend-aware _starts_agent_turn(msg, self.backend). Co-authored-by: rinbn <34065934+rinbn@users.noreply.github.com>
64788e4 to
6f96241
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. On head 6f96241 the review checked four things:
- The
_agent_turn_hold_endEvent is set in thefinallyof_claiming_stdoutand in_cancel_idle_reader, so a kill, reset or cancel cannot leavestream_unsolicitedwaiting. has_pending_agent_turn()lets the dashboard gate see the held start frame. The idle reader and the claim keep the buffer-only_agent_turn_pending().- The new stale-gate arming runs only on the agent-started read id, so user turns and the Kiro path do not change.
- Each new test fails with its fix reverted, and every one waits on a signal, not a sleep.
Well done: the takeover matches #30797 except for the two documented conflict resolutions, and the stale-gate change reuses the existing possibly_open idiom and the 90 s oracle reap instead of adding a new timer.
- Optional: the
Proof: PROVENline names head 700ba73, which is not this head. Re-running prove.py on 6f96241 would also list the hand-off tests. - Optional: after a permission ask is answered more than 90 s later,
_read_turnre-arms_stale_eligibleand the idle clock does not subtract the park time. One fix is to refreshlast_data_tswhen the dispatcher resumes from a permission or elicitation park. - Optional: no test covers a cycle that opens a tool call and then goes silent under
_stale_gate_expired, so nothing pins thenot possibly_openguard on the new arming line. Once this merges, #30797 can be closed as replaced.
…8853) On a claude chat served by the shared runtime, a request wait (a live model or effort change) that starts while a turn the agent began waits to be read takes that turn's frames into its own buffer until its answer arrives. The dashboard turn opened for the agent then found an empty queue and ended at once, which freed the chat: a message sent before the wait returned started a prompt, the wait put the frames back while that prompt read, and the agent's reply showed at the front of the follow-up's answer. The wait now marks when it holds the agent turn's first frame, and stream_unsolicited() waits until the wait has put it back before it reads, as the per-chat client does since #38313. The turn then reads the reply as its own message, and a message sent meanwhile queues behind it. Closes #37904
kirodotdev#38313's request-wait test predates turn_start; the reply is that turn's only row, so it carries the opener origin.
Supersedes #30797
Takeover of #30797 by @rinbn, which was approved but went stale against main. The commit keeps @rinbn as its author and carries a
Co-authored-by: rinbntrailer; the design, code, tests and live runs below are theirs. Thank you, @rinbn.What changed vs #30797
Rebased onto current main. Two conflicts, each resolved by keeping both sides:
providers/acp_turns.pyagent_turn_pending(): main now also answers for anAcpSessionProvider(the shared claude process, feat(acp): let claude dashboard chats share one ACP process, switch off by default #37540). That branch is kept; theAcpClientbranch now readshas_pending_agent_turn()as fix(acp): keep an agent-started turn readable through a request wait #30797 intended. The shared-process handle's probe (session_handle_agent_turns.agent_turn_pending) already reads True while_agent_turn_startis set and holds no frames aside, so it needs no change.acp/client_transport.py_read_turn: main now passes the backend to_starts_agent_turn(msg, self.backend). That call is kept, and fix(acp): keep an agent-started turn readable through a request wait #30797's stale-turn arming follows it unchanged.One test needed adapting:
test_a_kill_or_reset_wakes_a_stream_waiting_for_the_held_frames[_kill_process]now patchesplatform_compat.terminate_windows_asyncio_tree, because main's Windows kill path drains the real process tree and raisedOSError: Cannot retain the original Windows runtime process handleon the test's mock process (New-test stability, windows-latest). The test's assertions are unchanged. #37922 (merged) touchedstream_unsolicited()'s neighbourhood inclient_turn.pyfor a different path (a turn whose prompt was never sent) and merged cleanly with this change.Local gates on this head: the 9 related test files (1,647 tests) pass at
-n 4; black, isort, flake8, mypy oversrc/kiro_crew/,check_harness_parity.py,check_black_formatting.py,check_comment_history.py,check_file_line_cap.py,docs-lint.sh, the flake-pattern ratchet and the repo semgrep rules are clean.Original description from #30797 follows.
Problem / Motivation
Goal: On the claude backend, a reply that Claude Code sends on its own between dashboard turns still shows up as its own message when a request wait (such as a live config push) is running as it arrives, and a cycle of the agent's that goes quiet without a closing frame no longer holds the chat until the prompt timeout.
#30092 shows a turn Claude Code starts on its own as its own reply. Two gaps remain in the transport underneath it.
A request wait in the hand-off window drops the turn. When the idle reader hands a turn off, the turn's first frame waits in the client's buffer. A request wait can claim stdout before the turn reads that frame, for example a live effort or model push, or a compaction wait. #29269 makes that wait hold the turn's frames and put them back when it returns. While they are held,
AcpProvider.agent_turn_pending()reads False. So the dashboard turn started for the agent ends before it opens, because its dispatch gate sees nothing pending, orstream_unsolicited()returns at once. When the frames go back, nothing reads them: the idle reader does not restart while a hand-off is pending. The reply waits for the user's next message and shows under it, which is #17566's symptom.A silent agent-started cycle holds the slot. claude-agent-acp sends the closing
usage_updateonly when an assistant message set the cycle's usage. Suppose a cycle sends a thought, a plan or a permission request and then nothing. No response is coming either, and the stale-turn gate arms only after text. So the read stays open until the prompt timeout (4 h by default), and the chat slot with it, so every message sent meanwhile queues behind it.Why it matters
This affects anyone on the claude backend with agent-started turns on, which is the default. The first gap needs a request wait to overlap the moment the agent's turn arrives, which a settings change or a compaction can cause. When it happens, the reply is misattributed exactly as before #30092. The second gap is rare. When it hits, the chat stops answering for hours and shows no error.
Not a goal
AcpClientbackends keep main's behaviour (harness-parity H13): the changed reads run only on a client the claude adapter installed the idle reader on, and a user turn's stale-turn gate is unchanged.What changed (motivation → approach → change)
Design record:
docs/request-for-change/rfc-agent-started-turns.md(statuspartial).AcpClient.has_pending_agent_turn()is True while the turn's first frame is in_buffer, or in the list a claimed reader holds (_claiming_stdout).AcpProvider.agent_turn_pending()reads it, so in that window the dashboard's claim (_on_agent_turn) still starts the turn and its dispatch gate still opens it._agent_turn_pending()keeps its buffer-only meaning for the idle reader and the claim._agent_turn_hold_end(anasyncio.Event) and sets it when it puts the frames back._cancel_idle_reader(kill, reset) sets it too.stream_unsolicited()waits on it before its checks, so it never reads beside the holder. After a kill or reset it finds nothing pending and yields nothing._read_turn, under request id-1, each frame from the first activity frame on sets_stale_eligiblewhen no tool call is open. A silent cycle then ends on the existing gate: 90 s, deferred while the liveness oracle reads the backend as working, then a syntheticend_turn, the same end a stale user turn gets. An open tool call leaves the tool-stall watchdog in charge. A user turn never reaches this branch.acp/client_transport.py,acp/client_turn.pyandacp/client_class.pyhold the client half, andproviders/acp_turns.pyholds the provider probe.acp-client.md("Idle reader and agent-started turns", "Stale-turn gate") is updated.Backwards compatibility
Compatible: the new probe and event are internal to the claude client, and the only read that changes is the one under the agent-started request id, which only a claude session makes.
Removes nothing: the change adds a client method and an internal field and arms an existing gate earlier on one read path; nothing that main accepts is rejected, renamed or removed.
Tests
test/test_acp_client_agent_started_turns.py:test_stream_unsolicited_waits_for_a_reader_that_holds_the_turns_frames, for each of the request wait,wait_for_compactionand_drain_post_compaction_metadata: the stream blocks while the frames are held, then reads every one of them in order, the first included.test_a_turn_counts_as_pending_while_a_reader_holds_its_first_frame:has_pending_agent_turn()is True during and after the hold, and False once a prompt has read the frames.test_a_kill_or_reset_wakes_a_stream_waiting_for_the_held_frames(reset, kill): the blocked stream ends empty and writes nothing.test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate(a thought, a plan, an answered permission request): the read ends on the patched stale-turn timeout with a synthetic completion. On main it was still open when the 5 s wait expired, against a 30 s stand-in for the prompt timeout.test_a_user_turn_that_goes_silent_after_thinking_is_not_ended_by_the_stale_turn_gate: a user turn is unchanged.test/test_dashboard_agent_started_turn.py,test_a_request_wait_in_the_hand_off_window_does_not_leave_the_turn_empty: main's_run_chat(_agent_started=True)runs through the provider seam over a realAcpClientandStreamReaderwhile a request wait holds the frames. The reply lands as an agent-started row. On main the turn ended with no row before the wait's answer arrived.test/test_client_bindings.pypins the new member and field.Proof: PROVEN test/test_acp_client_agent_started_turns.py::test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate[thought], test/test_acp_client_agent_started_turns.py::test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate[plan], test/test_acp_client_agent_started_turns.py::test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate[permission], test/test_client_bindings.py::test_the_member_set_is_the_frozen_inventory, test/test_client_bindings.py::test_each_member_keeps_its_kind_shape_and_owner[_agent_turn_hold_end] (head 700ba73)
Determinism: the 11 new cases passed 15 runs at
-n 4 --dist loadgroup --max-worker-restart=2and 10 runs at-n0. Timing constants are patched and every await is bounded bykiro_crew.testing.wait; there are no sleeps.Local gates: the 21 test files that
run_scoped_tests.related_targetspicks for this diff, plustest_acp_client_stale_turn.py, are green at-n 4(1,658 tests). black (touched files only), isort, flake8,check_harness_parity.py,check_black_formatting.py,check_subprocess_encoding.py,check_file_line_cap.py,check_comment_history.py,check_brand_name.pyanddocs-lint.share clean. mypy reports two errors inapps/routes_registry.py, which this PR does not touch:was_installedis used there but never bound, on main as well.Manual verification
Live runs against claude-agent-acp 0.100.0 with no gateway and no browser. A driver built the dashboard state from the test helpers with a real
SessionManagerand the configured provider factory. It ran_run_chatfor the user turns and left the agent-started turn to the watch. Each run used a fresh data home. Times are seconds after the first prompt.sleep 15; echo probe-donein the backgroundprobe-done." lands at 29.3 s as its own row withmeta.origin, with its ownchat_doneprobe-done.No, the only background task…": the late result is glued to the fronttouchafter the background commandchat_donetouchpermissionThe request-wait race and the silent cycle were not reproduced live: both need the adapter to act at a chosen moment, so the tests above drive them.
A background subagent's permission request could not be placed between turns with this adapter version. When asked to start a background subagent, the adapter kept the user's prompt open until the subagent finished, so its ask and its report arrived inside that user turn. A Workflow agent was not tried.
Related Issues
Part of #17566
Builds on #30092 (agent-started turns on the dashboard) and #29269 (a request wait keeps the turn's frames).
Sibling sweep
Swept:
git grep -n "_agent_turn_pending()" -- src/for readers that ask whether a hand-off is pending, andgit grep -n "_stale_eligible = " -- src/kiro_crew/acp/for the stale-turn arming sites.Sibling: src/kiro_crew/providers/acp_turns.py -- changed here
Sibling: src/kiro_crew/acp/client_turn.py -- changed here
Sibling: src/kiro_crew/acp/client_transport.py -- not affected -- the claim and the idle reader's restart check need the buffer-only meaning: a held frame is already being kept for the turn
Sibling: src/kiro_crew/acp/session_handle_turn.py -- not affected -- the shared-runtime handle never reads an agent-started turn, only a direct claude client does
Pattern harvest
Not generalizable: both defects come from the agent-started read having no response to wait for, which no other read path in the client shares.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement