Skip to content

fix(acp): bill AcpClient credits read between turns on the next turn - #22228

Merged
bolichen97 merged 1 commit into
mainfrom
fix/acpclient-between-turn-credits-22171
Oct 21, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/acpclient-between-turn-credits-22171

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On the AcpClient path, credits kiro reports while a compaction is waited on between turns are billed once, on the next turn.

AcpClient.wait_for_compaction and its post-compaction grace drain (src/kiro_crew/acp/client_usage.py) add meteringUsage credits to last_prompt_stats. They run after the turn that asked for the compaction already billed its EVENT_COMPLETE, and the next turn's carry_over() starts its credit counter at zero. So those credits are never billed. The shared-runtime path had the same loss and was fixed in #22155.

Why it matters

Every session on the non-shared runtime that compacts between turns under-reports its spend: the compaction's credits never reach a turn's usage row, so the usage ledger and spend views read low.

Not a goal

What changed (motivation → approach → change)

Credits read between turns had no turn to land on. Now they wait on the client and the next turn picks them up.

Reader Where its credits go
wait_for_compaction, _drain_post_compaction_metadata held in _between_turn_credits
next turn (stream_events/stream_command, send_message, send_message_stream) adds the held amount right after carry_over(), then zeroes it
any frame read inside a turn that turn, as before
rekey() (a pooled client claimed by another session) held amount dropped

_track_metadata takes a keyword-only between_turns flag that the two between-turn readers pass. The caller says which window it reads for, rather than _turn_done as in #22155, because stream_command (the autocompact path) never clears _turn_done; reading turn state would move a slash command's own credits to the turn after it. The _track_metadata signature row in test/test_client_bindings.py is updated for the new keyword, and docs/system-specs/modules/acp-client.md describes the hold.

Backwards compatibility

Compatible: between_turns is keyword-only with a False default, so every existing caller of _track_metadata bills exactly as before; only the two between-turn readers pass it.

Removes nothing: no key, field, path or caller is taken away; the change adds one held counter and one keyword.

Tests

test/test_acp_client_between_turn_credits.py, all through real turns on an AcpClient with a scripted read stream:

  • credits read by wait_for_compaction (metering after completed, before completed, and carrying the pct itself) bill 0.5 on the next turn and 0.0 on the one after, for each of stream_events, send_message and send_message_stream;
  • credits read by the grace drain alone (the cached-result path AcpProvider.wait_for_compaction takes) bill the next turn once;
  • credits inside a turn, and inside a stream_command("/compact"), stay on that turn;
  • after rekey(), the claiming session's first turn bills 0.0.

Red on origin/main (10 of 15 fail, Obtained: 0.0, Expected: 0.5); prove.py --base origin/main reports PROVEN. Determinism: 20/20 repeated runs and 5/5 shuffled-order runs pass.

Manual verification

N/A — unit coverage sufficient: the change is internal accounting, driven end to end through the client's own turn entry points with a scripted kiro stream.

Screenshots / video

N/A — no frontend change.

Related Issues

Fixes #22171

Pattern harvest

Rule candidate: review-prompt
Pattern: a counter written outside the window that resets it (a reader that runs between turns adding to per-turn stats) loses whatever it adds.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 19, 2026 16:29
@bolichen97
bolichen97 requested a review from CrysisDeu October 19, 2026 16:29
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d5e88a9ac6d72e071b687f6412d6fde3a23b1472 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 added the readiness: checking Automated validation is still running label Oct 19, 2026
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d5e88a9ac6d72e071b687f6412d6fde3a23b1472 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: every caller of wait_for_compaction runs it after a turn has finished, so holding its credits for the next turn's carry_over() covers the loss end to end.

Notes

  • If a session ends or is evicted right after a between-turn compaction, the held credits are still never billed. This is narrower than the bug being fixed, but it is a known residual, so say so in the spec line.

[DESIGN-REVIEWED] d5e88a9

Description read

[DESCRIPTION-READ] 94f702e899880725e241a72639e2d3e55bb97ca9d6ff14534e72b76e6b94afde

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 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d5e88a9ac6d72e071b687f6412d6fde3a23b1472 — 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. The fix is backed by issue #22171 and by tests that fail on base. It covers every carry_over() reset site on AcpClient (3 of 3) and every between-turn reader (3 of 3).

What this change ships

Inventory (5 items) — 5 justified

Intent: make sure kiro credits spent on a compaction between turns show up in the usage ledger. This is a FIX.

  1. Credits reported while wait_for_compaction runs between turns are now billed on the next turn — justified
  2. Credits read by the post-compaction grace drain are billed on the next turn — justified
  3. Each of the three turn entry points adds the held credits once, then clears them — justified
  4. A pooled client claimed by another session (rekey()) drops the held credits, so they are not billed to the new session — justified
  5. _track_metadata gains a keyword-only between_turns parameter — justified

[FIRST-PRINCIPLES-REVIEWED] d5e88a9

Description read

[DESCRIPTION-READ] f27e664b5e1e099a02183e1f71f07017b70f0bac0ed4cc63246c5582b8807a93

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 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed d5e88a9ac6d72e071b687f6412d6fde3a23b1472 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d5e88a9

Verdict parsed from the review's SHA-scoped output markers for commit d5e88a9ac6d72e071b687f6412d6fde3a23b1472.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d5e88a9ac6d72e071b687f6412d6fde3a23b1472: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d5e88a9ac6d72e071b687f6412d6fde3a23b1472 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d5e88a9

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d5e88a9ac6d72e071b687f6412d6fde3a23b1472: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) October 19, 2026 16:35
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 19, 2026
@bolichen97

bolichen97 commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Fast Gate's Harness Parity Gate fails here with ACP_BACKENDS_MEMBER_CAPABILITIES [claude]: allowlisted but now proven; delete the entry. This PR touches no capability set; the same red is on main's own Fast Gate runs since 2026-10-19 08:05 PDT (e.g. run 39285437059 on 88914fd). Coverage Gate is the downstream fail-closed (backend-test=skipped because Fast Gate failed). The fix is open in #22241 (it replaces the closed #22186); this PR rebases onto it once it merges.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Held credits dropped when a session closes or is evicted after its last compaction

rebutted: the loss is accepted and unchanged from main, not introduced here. A held amount exists only after a between-turn compaction wait; if no turn follows on that client, there is no usage row to attach it to.
On main the same credits were already dropped at the next carry_over(); this PR bills them whenever a next turn exists, and never bills them twice.
Writing a turn-less usage row on close would be a new billing surface outside the goal (issue #22171 asks for the next-turn hand-off only).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • rekey() drops held credits instead of billing the previous session

rebutted: dropping is the required invariant, not a gap. A claimed client must never bill one session's credits to another (the same rule the shared-runtime path applies in AcpSessionProvider.rekey).
Billing them to the previous session would need a turn-less usage row for a session that no longer owns the client, a new billing surface outside this PR's goal.
The amount is the same one main already lost at the next carry_over(), so nothing billed today is lost by this change.

@bolichen97
bolichen97 force-pushed the fix/acpclient-between-turn-credits-22171 branch from c758f3b to bb31427 Compare October 19, 2026 17:18
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=f7c3db8ac481 acp-client.md billing paragraph omits the between-turn hold

fixed in bb31427: the "Per-turn kiro billing credits" paragraph in docs/system-specs/modules/acp-client.md now states that credits read by wait_for_compaction() and _drain_post_compaction_metadata() are held in _between_turn_credits, added once after carry_over() in the three turn entry points, and dropped by rekey().

@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 19, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Held credits never billed when no turn follows the compaction (close, stop, or rekey)

rebutted: the loss is accepted and unchanged from main, not introduced here. A held amount exists only after a between-turn compaction wait; if no turn follows on that client, there is no usage row to attach it to.
On main the same credits were already dropped at the next carry_over(); this PR bills them whenever a next turn exists, and never bills them twice.
Writing a turn-less usage row on close would be a new billing surface outside the goal (issue #22171 asks for the next-turn hand-off only).
rekey() drops them on purpose: a claimed client must never bill one session's credits to another.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased onto main ba5a6fc (bb31427 -> d5e88a9, same patch-id). Main now carries the Harness Parity fix from #22178, so Fast Gate / Coverage Gate should clear; CI re-running.

@bolichen97
bolichen97 force-pushed the fix/acpclient-between-turn-credits-22171 branch from bb31427 to d5e88a9 Compare October 21, 2026 15:20
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 21, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Every wait_for_compaction caller runs after a turn finishes

rebutted: agreed, no change needed. The between_turns readers are exactly the post-turn compaction waits, and test/test_acp_client_between_turn_credits.py pins next-turn billing once for all three turn entry points.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Covers every carry_over() reset site and every between-turn reader

rebutted: agreed, no change needed. All 3 carry_over() sites in client_turn.py add and zero _between_turn_credits; the 3 between-turn reads in client_usage.py pass between_turns=True.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Oct 21, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Tier 1 auto-approve: fix (7 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: ACP client bills credits reported between turns on the next turn instead of dropping them, with tests. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/acp-client.md.

@bolichen97
bolichen97 merged commit 5297d22 into main Oct 21, 2026
105 checks passed
@bolichen97
bolichen97 deleted the fix/acpclient-between-turn-credits-22171 branch October 21, 2026 18:10
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 21, 2026
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.

bug(acp): AcpClient drops credits reported while a compaction is waited on between turns

2 participants