Skip to content

feat(acp): read a claude turn the agent starts between prompts - #18285

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
rinbn:feat/agent-started-turns-transport
Oct 26, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
rinbn:feat/agent-started-turns-transport

Conversation

@rinbn

@rinbn rinbn commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let AcpClient notice and read a turn Claude Code starts on its own between prompts, with no user-visible change yet.

On the claude backend, a run_in_background command that finishes after the dashboard turn has ended makes Claude Code answer on its own. claude-agent-acp writes that turn to stdout, but AcpClient reads stdout only while a request waits, so the next user message reads the old reply as its own (#17566). The accepted RFC splits the fix into a transport PR and a dashboard PR; this is the transport one.

Why it matters

The dashboard turn in the next PR is built on this API, and the reader is the risky part: an asyncio.StreamReader allows one waiting readline(), so a reader that runs between turns must step aside for every other stdout reader without losing or reordering a frame. Landing it with no caller lets that contract be reviewed and tested on its own.

Not a goal

  • Showing the turn in the dashboard, registering on_agent_turn, the agent.agent_started_turns kill switch and the origin label. Those are the RFC's Phase 2.
  • Any backend other than claude. Phase 3 stays blocked.

What changed (motivation → approach → change)

Users see no change from this PR. It adds the plumbing the next PR needs to show a reply Claude Code sends on its own between prompts as its own message.

Nothing reads stdout between turns today, so the change adds a reader for that gap, a rule that every other reader stops it first, a way to read the turn it finds without sending a prompt, and a queue that holds a prompt until that turn ends.

The reader and its claim live in acp/client_transport.py, the owner of _read_message; stream_unsolicited is in acp/client_turn.py, and acp/client_class.py binds both onto AcpClient. The backend set is declared in agent_sdk/backends_turns.py, with its disposition in agent_sdk/backend_cards.py, and docs/system-specs/modules/acp-client.md gains a section on the reader and its claim rule.

Piece What it does
Idle reader On ACP_BACKENDS_AGENT_STARTED_TURNS (claude) with a callback registered, a task reads stdout whenever no other reader holds it. A frame that shows the agent acting (agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update, plan, or a request from the agent) makes it put every frame it read back at the front of _buffer, record that frame as the turn's start and call on_agent_turn(client). A frame that only reports state (usage_update, session_info_update) goes back and starts nothing. It stops once _buffer is full (its maxlen, 100) and leaves the rest in the pipe.
Stdout claim The claude adapter's spawn step (ClaudeLaunch.resolve_spawn) calls _install_idle_reader() on the session it launches when its backend is in that set, once per client. On that instance it wraps ensure_ready, _initialize_session, _wait_for_response, _drain_notifications, wait_for_compaction, _drain_post_compaction_metadata, _read_steer_answers and _prompt_loop in a claim, and makes _kill_process and _reset_state drop the reader first. A claim cancels the reader and waits for it to exit; the last release restarts it. A cancel inside readline() loses no bytes, because the stream consumes a line only once its newline has arrived. The kiro-cli arm of _spawn reaches no adapter, so a Kiro client's constructor and read methods are main's.
stream_unsolicited() Reads the pending turn through the same _dispatch_events, under request id -1, and sends nothing. After the turn's first activity frame, the bound _prompt_loop ends it on the usage_update whose _meta["_claude/origin"].kind is in the adapter's autonomous set; a user turn's {"kind": "human"} ends nothing, and a marker left between turns by an earlier cycle does not end this one. A response to a request sent before the turn began ends it too: nothing is sent under -1, so that response answers a wait that already ended, usually a prompt whose turn ended here, and it keeps its own stopReason. A response to a request sent after the turn began (an id at or above the _next_id it started with) ends it but stays at the front of _buffer for that request's reader. Process death, the stale-turn gate and the prompt timeout end it as they end a user turn. It yields nothing when a prompt is in flight or has already read those frames.
Prompt queue The same binding wraps send_message, send_message_stream, stream_events and stream_command. Each waits on _agent_turn_gate, which stream_unsolicited() holds until the turn's _prompt_loop has released _turn_lock, before it resets _cancelled and _turn_done or writes, and counts itself in _prompts_in_flight until it returns. So a Stop pressed on the agent-started turn ends that turn, and has_active_turn() reads the prompt's own state (RFC decision 3).

Four details differ from the RFC's wording. The RFC has every read site call _claim_stdout(); here the claude adapter binds the claim on the session it launches, the seam its MCP array and settings seed already use, so a Kiro client's construction and prompt paths gain no step (harness-parity H13). The turn also ends on a response, which the RFC's end list does not name yet. The reader does not hold _turn_lock: the claim count keeps it off stdout while any reader is active, and it hands off and calls back in one step with no await between. And it reads with the cancel-grace check off, because _cancelled belongs to the turn that ended; otherwise a background result that lands after the user pressed Stop would again wait for the next message.

Three limits stay for the dashboard PR, the first caller that registers on_agent_turn and so the first that opens any of these windows. Each has an issue:

Backwards compatibility

Compatible: nothing registers on_agent_turn, so the reader never starts, and a client of any backend outside ACP_BACKENDS_AGENT_STARTED_TURNS never binds it, so its constructor, read methods and prompt entry points are unchanged. The one shared signature change is _read_message's keyword-only check_cancel, which defaults to today's check and is passed only by the idle reader.

Removes nothing: the change adds a reader, a set and a method, and keeps every existing read path.

Tests

test/test_acp_client_agent_started_turns.py drives AcpClient over a real asyncio.StreamReader and covers the RFC's Phase 1 exit criteria: a cancel inside readline() on a partial line loses no bytes; each of the five read sites, and a warm ensure_ready as a prompt starts, stops a parked reader (a second waiting readline() would raise) and the last release restarts it; a check fails if a new _read_message caller is neither wrapped nor called only from wrapped methods; stream_unsolicited() ends on the autonomous origin, on process death and on the timeout gate, and a human origin ends nothing; session_info_update and a lone origin usage_update start no turn; each documented activity kind starts a turn and each autonomous origin kind ends one. Further tests pin the claude adapter binding the reader once across respawns, a Kiro client keeping its own methods and never reading between turns, frame order ahead of what was already buffered, the reader stopping at the buffer bound, a request wait that reads the start frame ending the hand-off and one that puts a permission request back keeping it, the reader running after a stopped turn, an earlier cycle's end marker not ending the turn, a late prompt's tail ending on its response, a prompt in flight or one that starts first keeping the frames as its own, a response to a request sent during the turn staying in _buffer, a prompt sent during the turn waiting behind it with the Stop kept and has_active_turn() true until it ends, a prompt past the gate keeping stream_unsolicited() out, a cancelled claim restarting the reader, and a reset dropping what the reader held.

Of 22 mutations of the production code, one per rule above (for example the claude adapter not binding the reader, binding twice on a respawn, leaving ensure_ready or _wait_for_response unclaimed, appending instead of prepending, or ending on a marker before any activity), 21 turn at least one of these tests red. The one that survives is _cancel_idle_reader forgetting the start frame, which only a kill with no reset after it would show. Six more for the response rule and the queue (dropping or loosening the newer-response check, dropping the in-flight check, the prompt wrappers, the _turn_lock wait or the in-flight decrement) each turn a test red.

Determinism: the new file passed 20 runs at -n0, 10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_acp_client_shutdown_reset.py and test_acp_client_capabilities.py, and one shuffled run of all 48 ids (seed 21408). It waits on observed state or the task it started (async_wait_until, await_until, a parked StreamReader), never on a sleep or a short fixed wait_for.

test/test_client_bindings.py, the AcpClient member inventory added by #20470, gains rows for this PR's 18 new members, and the _read_message row's signature hash changes for the keyword-only check_cancel. The AST check in test_acp_client_agent_started_turns.py now scans client.py and every owner module in _CLIENT_OWNERS, so a stdout reader moved into an owner module is still caught.

scripts/check_harness_parity.py passes: the reader dispatches no frame, so it adds no enforcement role.

Manual verification

Replayed the four stdout logs Phase 0 recorded from claude-agent-acp 0.87.0 through AcpClient over a StreamReader, with a callback registered, on the earlier head dd5d344642a442d227c0048d428928af5ae9dff0. In the background-command, Stop and prompt-during logs, the reader was running once the user turn ended, left the session_info_update and the first usage_update in _buffer, and handed off on the first tool_call or agent_message_chunk. stream_unsolicited() then read the agent's reply and ended on the task-notification origin usage_update, with nothing written to stdin. In the background-command log that reply is a Read File call and "The background probe finished with exit code 0 and printed probe-done." In the background-subagent log, the lone origin-marked usage_update after the held turn and the session_info_update started no turn. The replay script is in a comment on this PR. The logs were not kept, so this head was not replayed; it moves the claim and the end rule into per-client bindings without changing what they do on those logs, and adds the response rule and the prompt queue, which those logs do not exercise; the tests above pin all four.

A live run on cb31adc2fd84ae712ab4590afab44bd31fb5f22a, this patch one rebase onto main earlier, against claude-agent-acp 0.87.0, with a callback registered: the session started with the bindings installed, answered a prompt, accepted a steer sent from another task mid-turn (steer() returned True and steer_consumed arrived) and ran /compact to end_turn. Then a run_in_background command (sleep 6; echo probe-done) fired on_agent_turn after the user turn ended, stream_unsolicited() read "The background command finished with exit code 0 and printed probe-done." and ended on end_turn, and a send_message started during that read waited for it, then answered "after", with has_active_turn() False afterwards. The dashboard PR carries the user-visible repro.

Related Issues

Part of #17566

Phase 1 of docs/request-for-change/rfc-agent-started-turns.md (written in #18051, accepted in #18191; the Phase 0 verdicts it relies on are in #18258).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@rinbn
rinbn requested review from a team and KiroCrewCaptain as code owners October 9, 2026 00:31
@rinbn
rinbn requested a review from bolichen97 October 9, 2026 00:31
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 9, 2026
@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

Replay script behind Manual verification. It feeds a stdout log recorded by the Phase 0 probe (the script in #18258 (comment), one JSON line per frame: {"t", "dir", "msg"}) through AcpClient over a StreamReader, with an on_agent_turn callback registered. It reads the user turn, then feeds the between-turn frames one at a time and reports where the hand-off happens and how stream_unsolicited() ends.

Run from a checkout of this branch: python replay.py <probe-log.jsonl>.

replay.py
"""Replay a recorded claude-agent-acp stdout log through AcpClient's idle reader."""
import asyncio, json, sys
from unittest.mock import AsyncMock, MagicMock

from kiro_crew.acp.client import AcpClient
from kiro_crew.acp.types import EVENT_COMPLETE, EVENT_TEXT_CHUNK, EVENT_TOOL_CALL


def kind(m):
    if m.get("method") == "session/update":
        u = m["params"]["update"]
        o = (u.get("_meta") or {}).get("_claude/origin")
        return u["sessionUpdate"] + (f" origin={o['kind']}" if o else "")
    return m.get("method") or f"response id={m.get('id')}"


async def main(path):
    rows = [json.loads(l) for l in open(path)]
    prompt_id = next(r["msg"]["id"] for r in rows if r["dir"] == "out" and r["msg"].get("method") == "session/prompt")
    i_resp = next(i for i, r in enumerate(rows) if r["dir"] == "in" and r["msg"].get("id") == prompt_id and "result" in r["msg"])
    i_prompt = next(i for i, r in enumerate(rows) if r["dir"] == "out" and r["msg"].get("id") == prompt_id)
    user_turn = [r["msg"] for r in rows[i_prompt + 1 : i_resp + 1] if r["dir"] == "in"]
    after = [r for r in rows[i_resp + 1 :] if r["dir"] == "in"]

    client = AcpClient(acp_backend="claude")
    reader = asyncio.StreamReader()
    proc = MagicMock(); proc.stdout = reader; proc.stdin = MagicMock(); proc.stdin.drain = AsyncMock(); proc.returncode = None
    client._process = proc
    client._session_id = user_turn[0]["params"]["sessionId"] if user_turn[0].get("params") else "s"
    handed = []
    client.on_agent_turn = lambda c: handed.append(len(fed))

    fed = []
    for m in user_turn:
        reader.feed_data((json.dumps(m) + "\n").encode())
    client._turn_done.clear()
    async for e in client._dispatch_events(prompt_id, 60):
        if e.kind == EVENT_COMPLETE:
            print(f"user turn: complete stop_reason={e.stop_reason}")
            break
    await asyncio.sleep(0.05)  # let the read loop's finalizer release stdout
    print("idle reader running after the user turn:", client._idle_reader is not None and not client._idle_reader.done())

    for r in after:
        m = r["msg"]
        fed.append(m)
        reader.feed_data((json.dumps(m) + "\n").encode())
        await asyncio.sleep(0.02)
        print(f"  t={r['t']:7.2f} fed {kind(m):45s} handed_off={bool(handed)} pending={client.agent_turn_pending()}")
        if handed:
            break
    if not handed:
        print("no hand-off"); return
    print(f"hand-off after frame #{handed[0]} of {len(after)} between-turn frames")
    for r in after[len(fed):]:
        reader.feed_data((json.dumps(r["msg"]) + "\n").encode())
    texts, tools, end = [], [], None
    async for e in client.stream_unsolicited(timeout=30):
        if e.kind == EVENT_TEXT_CHUNK: texts.append(e.text)
        elif e.kind == EVENT_TOOL_CALL: tools.append(e.title)
        elif e.kind == EVENT_COMPLETE: end = e
    print("agent-started turn tools:", tools)
    print("agent-started turn text:", "".join(texts)[:200])
    print("ended:", end and end.stop_reason, "| stdin writes:", proc.stdin.write.call_count)
    await asyncio.sleep(0.05)
    left = []
    while client._buffer: left.append(kind(client._buffer.popleft().__dict__))
    print("left in _buffer:", left)
    if client._idle_reader: client._cancel_idle_reader()


asyncio.run(main(sys.argv[1]))

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 6200a2b9a7074454fb42651a8681c40d53357759 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 6200a2b9a7074454fb42651a8681c40d53357759 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: accepted RFC rfc-agent-started-turns.md covers Phase 1, which is the idle reader, the stdout claim and stream_unsolicited with no caller. One rider repeats a queue the RFC already puts in the dashboard.

Notes

  • Item 5 — duplicate of src/kiro_crew/dashboard/chat_turn/queue_drain.py: the description says "This is the queue of … decision 3", but RFC §6 makes decision 3 the existing slot.running queued path ("a message sent while the agent-started turn runs takes the existing queued path"). Phase 1 has no caller that this client-level gate protects. Subtraction: delete _agent_turn_gate, _prompts_in_flight and the queued() wrappers on send_message/send_message_stream/stream_events/stream_command, or defer them to Phase 2, where a caller can show it skips the slot queue.
  • Item 3 — inherited ("The turn also ends on a response, which the RFC's end list does not name yet"): the description declares this end condition, and the PR's own test is its only support. Subtraction: none while the RFC is silent; it rests on that test.

What this change ships

Inventory (7 items) — 5 justified

Intent: let a claude session's client notice and read a turn the agent starts between prompts, with no visible change yet. ADDITION (Phase 1 of a FIX for #17566).

  1. A claude client reads stdout between turns once a callback is registered — justified
  2. Every other stdout reader stops that reader first, bound only on claude sessions — justified
  3. An agent-started turn also ends on a stray response — undeclared by RFC, inherited
  4. stream_unsolicited() reads a pending agent-started turn without sending anything — justified
  5. A prompt sent during an agent-started turn waits at the client — duplicate of dashboard/chat_turn/queue_drain.py
  6. New backend set ACP_BACKENDS_AGENT_STARTED_TURNS = {claude} — justified
  7. _read_message gains keyword-only check_cancel, default unchanged — justified

[FIRST-PRINCIPLES-REVIEWED] 6200a2b

Description read

[DESCRIPTION-READ] 895e6b8874601ddd7dc4d7b87247bb1b636d05af8696e2deb10d00d1fe9a53ae

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 6200a2b9a7074454fb42651a8681c40d53357759 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the reader stays dormant until something registers on_agent_turn, and the wrappers only touch claude clients.

Notes

  • _install_idle_reader runs on every claude spawn whether or not anything registers on_agent_turn. So in this PR, claude clients already get the prompt gate, the stdout claims and instance bindings that hide later class-level patches. Binding only when a callback registers would keep "no user-visible change" true on the claude path too.

[DESIGN-REVIEWED] 6200a2b

Description read

[DESCRIPTION-READ] 664898181c18bb4d7789eb13603ef506feaead66b75ca5960db0f29b86a91890

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 6200a2b9a7074454fb42651a8681c40d53357759 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6200a2b

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 6200a2b9a7074454fb42651a8681c40d53357759 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6200a2b

@rinbn
rinbn force-pushed the feat/agent-started-turns-transport branch from 95debab to b983f42 Compare October 9, 2026 01:34
@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=959155781a93 — bare monkeypatch.undo() in test_a_claim_cancelled_while_the_reader_stops_restarts_it

Fixed in b983f42. The stub is installed inside with monkeypatch.context() as patched:, and that context exits before the test stops the restarted reader, so no other patch on the fixture is rolled back. The bare undo() is gone, and semgrep scan --config semgrep/ on the diff reports 0 findings.

@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=3d3796bad2e0 — scope restoration to the temporary reader stub

Fixed in b983f42. The stub lives inside with monkeypatch.context() as patched:, which exits before the restarted reader is stopped, as suggested. The shared-fixture undo() is gone, and semgrep scan --config semgrep/ on the diff reports 0 findings.

@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=485dd972874f — the pending-turn deferral skips the buffer bound

Fixed in b983f42. _buffer no longer has a maxlen, because a full deque drops a frame to admit the next. Each writer bounds itself: the idle reader stops once _IDLE_READ_MAX_FRAMES (100) frames wait and leaves the rest in the pipe, and _wait_for_response is bounded by its deadline. On main the only writer was _reinject, which the bound could only make drop frames. test_a_request_wait_keeps_more_pending_frames_than_the_reader_cap defers 150 session/update frames and a permission request during one wait, and the agent-started turn reads all of them in order; with the old maxlen put back, that test fails.

@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=3c3dafadccda — agent_turn_pending() has no production consumer

Fixed in b983f42: the method is deleted, and the tests read client._agent_turn_pending. stream_unsolicited() keeps its own check of that flag.

@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=daed3b318d6f — shutdown() clearing on_agent_turn is undeclared

Fixed in b983f42: the line is removed. Nothing registers a callback in this PR, and after shutdown the reader cannot start anyway: _kill_process cancels it and _maybe_start_idle_reader refuses a dead process. Whether the dashboard should drop its callback on shutdown is for the PR that registers one.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 9, 2026
@rinbn
rinbn force-pushed the feat/agent-started-turns-transport branch from b983f42 to dd5d344 Compare October 9, 2026 04:20
@rinbn

rinbn commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=0dfda262228b — deferred frames bypass the replay-buffer capacity bound

Fixed in dd5d344. One named constant, _BUFFER_MAX_FRAMES (100), bounds every store of this population at the point of retention: _buffer is deque(maxlen=_BUFFER_MAX_FRAMES), the idle reader stops reading once _buffer holds that many and leaves the rest in the pipe, and _wait_for_response appends to deferred only while it has room, counting each frame past it instead of keeping it. When the wait puts its frames back, it keeps the oldest in arrival order and logs one warning with the number dropped and the bound, so the deque never evicts without a word. test_a_request_wait_past_the_buffer_bound_keeps_the_oldest_and_logs_the_rest pins the kept frames and the single warning, and test_a_request_wait_holds_no_frame_past_the_buffer_bound_while_it_runs shows the frames past the bound are already freed while the wait still runs; each fails if its bound is removed.

Each retained frame is bounded by the transport's per-line limit, as on main for this same structure; truncating strings inside a JSON-RPC frame would corrupt it. This replaces the unbounded buffer of the previous head, which answered the Design lane's "none are lost" condition: a count bound cannot keep every frame, and this rule blocks.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 9, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Oct 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 5a59e45.

The transport design follows the accepted RFC. The claim is bound only on claude clients, Kiro read paths stay main's, and CI is green on this head.

What blocks approval:

  1. Current-head AI items have no reply. First Principles (CONCERNS) flags the four unused facade re-exports at client.py#L225-L232. Design's suggestion asks for a spec note that the setattr rebinding hides class-level patches. Every existing disposition targets an earlier head.
  2. @bolichen97's two should-fix threads from the rebase review are open with no reply. I confirmed both on this head. client_transport.py#L162 ends the turn on any response id. client_turn.py#L770-L771 resets shared turn state with nothing stopping a concurrent prompt. Neither is reachable until a caller registers on_agent_turn. Fix them here, or agree with the reviewer to defer them and link one issue per item.

To clear: remove the four re-exports or post a first-principles disposition at head=5a59e45…; add the spec note or answer the design suggestion; resolve both inline threads.

— crew-pr-reviewer (r110)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 18, 2026
@rinbn
rinbn force-pushed the feat/agent-started-turns-transport branch from 5a59e45 to 9616715 Compare October 18, 2026 18:52
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 18, 2026
@rinbn

rinbn commented Oct 18, 2026

Copy link
Copy Markdown
Contributor Author
  • span=3bf4d31f8951 — four new private names re-exported through the kiro_crew.acp.client facade with no reader

Fixed in 9616715 by the subtraction this item names, plus one more step. All six re-export lines this PR added to client.py are gone, including _starts_agent_turn and _ends_agent_started_turn. Those two are new names too, and the facade comment scopes re-exports to names that moved. The test imports both from kiro_crew.acp.client_transport, so this PR no longer changes client.py.

@rinbn

rinbn commented Oct 18, 2026

Copy link
Copy Markdown
Contributor Author
  • span=247fdc1bda42 — instance setattr bindings hide class-level patches

Fixed in 9616715. Under the idle-reader section, acp-client.md gains an "Instance bindings hide class patches" bullet. The wrappers are set on the instance and each holds the method it wraps, so after the spawn, a patch of AcpClient.<method> on the class does not reach a claude client for any method the binding names. The bullet says to patch the instance instead, or to patch the class before _install_idle_reader runs. On the punchline: a live run against claude-agent-acp 0.87.0 on cb31adc2fd84ae712ab4590afab44bd31fb5f22a (the same patch, one rebase earlier) started a claude session with the bindings installed. It answered a prompt, accepted a steer sent mid-turn from another task (steer() returned True and steer_consumed arrived), and ran /compact to end_turn. It then read an agent-started turn: a run_in_background command's result fired on_agent_turn, stream_unsolicited() read the reply and ended on end_turn, and a prompt sent during that read waited, then answered.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update. Head reviewed: 9616715.

Both items from my last review are fixed.

  1. Response to a newer request. _read_turn now records _next_id when the turn starts. A response with an id at or above that value goes back to the front of _buffer, and the turn ends with a synthesized complete. test_a_response_to_a_request_sent_during_the_turn_is_left_for_its_reader pins it.
  2. Shared cancel and done state. The four prompt entry points now wait on _agent_turn_gate before they reset _cancelled or _turn_done, and count themselves in _prompts_in_flight. stream_unsolicited holds the gate for the whole read and checks the count under it. test_a_prompt_waits_behind_the_agent_started_turn_and_keeps_its_own_state shows that a Stop on the agent-started turn ends that turn as cancelled, and that has_active_turn() stays True for the queued prompt until its own reply.

I also checked the edges of the gate. A prompt cancelled while it waits never increments the count. The finally in stream_unsolicited waits for _turn_lock before it releases the gate. The spec now says not to await a prompt inside an open stream_unsolicited() loop, which is the one way to deadlock it. The changes outside this feature between the two heads come from the rebase onto main.

On the First Principles concern about the gate: I asked for it in my last review. The dashboard slot.running queue covers only dashboard prompts. The gate keeps the contract inside the client, so a future caller cannot reopen the shared-state window by mistake, and it costs one uncontended lock per prompt. I think it should stay. A disposition reply from you on that item for this head will close it.

I did not run the tests locally on this head. CI on this head is green and readiness is passed.

🔴 0 must-fix · 🟡 0 should-fix.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 9616715.

Our r110 items and @bolichen97's two should-fix threads are fixed on this head. The facade re-exports are gone, the spec notes the instance-binding caveat, a response to a newer request stays in _buffer, and prompts wait on _agent_turn_gate (client_transport.py L395-L476). The kill and reset wrappers only cancel the idle reader before calling the originals. CI is green.

What clears the hold, two replies for this head and no code change required:

  • First Principles CONCERNS, item 4 (comment): post a target=first-principles head=9616715… disposition. @bolichen97's argument for keeping the gate inside the client is a good basis.
  • Design PASS punchline: on every claude spawn the claim and gate wrappers are bound, whether or not on_agent_turn is set. Please confirm in a reply that a claude session with no callback behaves as on main, and name the test or run that shows it. The live run cited on 5a59e45 had a callback registered.

I read the source and the test list. I did not run the tests.

— crew-pr-reviewer (r111)

@rinbn

rinbn commented Oct 19, 2026

Copy link
Copy Markdown
Contributor Author
  • span=a044fb4ff83f — the client-level prompt queue duplicates the dashboard slot.running queue

Kept, on the reviewer's request. The state this queue protects lives in AcpClient: one _cancelled and one _turn_done per client, which Stop, the shutdown drain and the idle sweep read through has_active_turn(). slot.running queues only the prompts the dashboard chat slot sends. Every other caller of send_message, send_message_stream, stream_events or stream_command on a claude client would reopen the window where a prompt resets that state while an agent-started turn reads, and nothing would stop it. The gate puts that contract at the transport, where it can be tested on its own, so it does not depend on each future caller routing through the dashboard. A prompt with no agent-started turn open takes the uncontended lock without waiting, and until something registers on_agent_turn, no agent-started turn is ever open. @bolichen97 asked for this in the previous round and confirmed it on this head.

@rinbn

rinbn commented Oct 19, 2026

Copy link
Copy Markdown
Contributor Author

On the Design punchline for 961671586816079316451e28fa41389282a81515 (a claude session with no on_agent_turn behaves as on main):

A live run on this head against claude-agent-acp 0.87.0, with no callback registered:

  • The session started with the claim and gate wrappers bound, answered a prompt ("pong"), and ran /compact to end_turn.
  • A run_in_background command finished between turns. Nothing read it there: over the whole run the idle reader started 0 times, _agent_turn_gate was never held, and _prompts_in_flight ended at 0. The next prompt read that result as the start of its own reply, as main does today (Claude backend: a turn Claude Code starts on its own after the dashboard turn ends shows up under the next user message #17566).
  • A steer sent from another task during the session's first turn was accepted and consumed in 2 of 2 runs, and so it was on main (b26871d222) with the same script, 2 of 2. With a prompt before it, the same steer was not accepted, on this head and on main alike, 3 of 3 each. That behaviour comes from outside this PR.

In the tests, test_no_idle_reader_when_nothing_could_take_the_turn[no_callback] pins that no reader starts without a callback. With no reader, no agent-started turn opens, so every wrapped prompt passes the gate without waiting, and every claim only moves a counter around the original call.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

REQUEST_CHANGES at 9616715. The code needs no change; three follow-ups need issues.

Both replies clear the remaining lane items. The First Principles disposition explains why the gate belongs in the client (comment). The no-callback run, plus test_no_idle_reader_when_nothing_could_take_the_turn[no_callback] (test), shows a claude session without on_agent_turn never starts the reader. The prompt wrappers then take the gate only to bump the counter (client_transport.py L430-L455). CI is green and @bolichen97 has no open items.

What changed lists three limits that "stay for the dashboard PR". Neither #17566 nor the RFC's Phase 2 exit criteria name them, so nothing tracks them yet. Please open one issue per limit and link each in the description:

  1. A request wait, wait_for_compaction or _drain_post_compaction_metadata in the hand-off window files the turn's start session/update in _mcp_notifications.
  2. A _buffer full of state-only frames stops the reader, so a later agent-started turn waits for the next prompt.
  3. A steer or late steering answer can end an agent-started turn early through _dispatch_events.

Our earlier rounds missed this; it is raised now on the unchanged head. I read the source and the test. I did not run the tests.

— crew-pr-reviewer (r112)

@rinbn

rinbn commented Oct 19, 2026

Copy link
Copy Markdown
Contributor Author

@iamwhatever, on r112: I opened one issue per limit and linked each one from the limits paragraph in What changed:

  1. Claude backend: a request or compaction wait during an agent-started turn's hand-off files the turn's first frame as a notification #22262: a request wait, wait_for_compaction or _drain_post_compaction_metadata in the hand-off window files the turn's start session/update in _mcp_notifications.
  2. Claude backend: a buffer full of state-only frames stops the idle reader, so a later agent-started turn waits for the next prompt #22263: a _buffer full of state-only frames stops the reader, so a later agent-started turn waits for the next prompt.
  3. Claude backend: a steer or a late steering answer can end an agent-started turn early #22264: a steer or a late steering answer can end an agent-started turn early.

Each issue links the code at 9616715868, explains why nothing reaches the window until a caller registers on_agent_turn, and gives a direction and the test that would pin it. The code is unchanged.

@rinbn

rinbn commented Oct 22, 2026

Copy link
Copy Markdown
Contributor Author

@iamwhatever, a reminder on r112: the three limit issues are open and linked from What changed (comment): #22262, #22263 and #22264. The head is still 9616715868. It has no conflict with main and no new review items, so it is ready for another look when you have time.

@JLargent42

Copy link
Copy Markdown
Contributor

Heads-up from #23248. That PR adds a turn-end notice that says no follow-up is scheduled when a turn promises to report back and nothing will wake the session. Once this PR makes claude agent-started turns visible, a Bash run_in_background call becomes a real wake, and that notice would be wrong for it. Whichever PR merges second should count that call as a wake (turn_armed_a_wake in dashboard/chat_utils_turn_text.py).

claude-agent-acp streams a turn Claude Code starts on its own (a
background command finished) while no prompt is in flight. AcpClient
reads stdout only while a request waits, so the next prompt read that
turn as its own.

This is the transport half of the agent-started turns RFC. On the
backends in ACP_BACKENDS_AGENT_STARTED_TURNS (claude), an idle reader
watches stdout between turns; every other stdout reader claims stdout
first, which stops it. On a frame that shows the agent acting, the
reader leaves the frames in _buffer and calls on_agent_turn.
stream_unsolicited() reads that turn without sending a prompt and ends
it on the adapter's autonomous-origin usage_update. A response to a
request sent after the turn began ends it too, but stays in _buffer
for that request's reader. A prompt entry point waits behind the open
turn before it resets the turn state or writes, so a Stop on the
agent-started turn is kept and has_active_turn() reads the prompt's
own state. The claude adapter binds the claim, the turn end, the
prompt queue and the reader's teardown on the session it launches, so
a Kiro client's constructor and read methods stay as they are. Nothing
registers on_agent_turn yet, so the reader never starts and behaviour
matches main.

Part of kirodotdev#17566

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve at 6200a2b.

Our r112 request is met. The three limits the description leaves for the dashboard PR are now tracked in #22262, #22263 and #22264, which are linked from What changed. Each issue describes its limit with code links. This head is a rebase of 9616715. The reader, the stdout claim, the prompt gate and the turn-end rules are unchanged from the version we reviewed (client_transport.py#L395-L476), and the claim-coverage test still checks every _read_message caller.

The AI lane notes on this head repeat items already answered: the prompt gate was kept at @bolichen97's request, and a no-callback live run showed claude sessions behave as on main. @bolichen97 has no open items, every check is green, and the branch merges cleanly with main. I read CI and the test source and did not run the tests.

— crew-pr-reviewer (r127)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants