Repository navigation
feat(dashboard): read the credit balance through /usage by default - #12918
Conversation
|
Intent: Make the billed credit-balance fallback pay-per-click: a Refresh button beside the meter runs one owner-only, single-flight, cooled-down /usage turn, and the Settings > Display background toggle goes away. |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The no-cost premise is verified on an unspecified account class, yet the opt-out for exactly the untested class (org/IAM Identity Center) is deleted. WatchThe design overturns #2039's pin ("a REAL billed kiro-cli chat turn") on three evidence legs, but the empirical leg — "three back-to-back runs on this account… unchanged" — doesn't state the account class, and the fallback fires only for accounts the free API returns no [DESIGN-REVIEWED] d15c192 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
First Principles Review (Fable 5) — ✅ human override accepted@CrysisDeu overrode this lane for |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsA transient FINDING — src/kiro_crew/dashboard/handlers/sessions.py:926 — FINDING — src/kiro_crew/dashboard/handlers/sessions.py:193 — the touched comment still sizes the ceiling as " FINDING — src/kiro_crew/dashboard/handlers/sessions.py:546 — the new docstring asserts [OPUS-REVIEWED] d15c192 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS One stale fact ships in two tones and wordings, and "Try again in about N min." sits above a Refresh the modal keeps disabled. Watch
Suggestions
[UX-REVIEWED] d15c192 |
4b8892f to
e236ee2
Compare
e236ee2 to
604e40b
Compare
|
Design, watch: the "free /usage" premise is verified on one account and one kiro-cli version; keep the key as a kill switch. Declined on the key; the premise now has provenance beyond the measurement, in the description. |
|
UX, watch: 409 rendered as an error; three outcomes unshot; bonus-row label. Fixed on this head for the first two. A colliding click now renders as progress: a muted |
604e40b to
9b2e188
Compare
|
Design, watch: the free-read premise was verified on an account whose CLI printed a plan, while the fallback fires for accounts the API returns no plan for; also on kiro-cli 2.23.0 only. Declined, with one correction to the premise of the finding. The account the measurement ran on IS the fallback case: the dashboard's |
e26d2e0 to
02eb060
Compare
|
Opus, BLOCK: a failed Opus, FINDING (span=21910eb8fc84): the adjacent whoami ran before the wedged scrape child was reaped. Fixed on the same head. |
|
/ai-review override first-principles 02eb060: /usage is a free local kiro-cli panel over GetUsageLimits (measured, documented); a config key guarding zero cost is dead surface, so the fallback is always on and the key/toggle go. |
Human judgment recorded@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
UX, BLOCK (evidence): the paused frame showed a superseded layout. Fixed in the body: UX, watch: "Could not read the gateway configuration." Held for the next push if one is needed; the sentence is changed to "Could not load settings, so your balance can't be shown." then. The notice already carries the agent hand-off and the Refresh button beneath it, so the action is present on this head. UX, watch: stale and in-flight outcomes render in the alert. Declined on the same grounds as the previous heads: the GPT lane's blocking rule UX, watch: the dimmed "—" pill's explanation is hover-only. Declined as on the previous heads: the segment carries the same text as |
02eb060 to
ce595e7
Compare
|
GPT, BLOCK (fenced): the API publish path judged identity against the top-of-refresh whoami. Fixed on |
|
/ai-review override first-principles ce595e7: /usage is a free local kiro-cli panel over GetUsageLimits (measured, documented); a config key guarding zero cost is dead surface, so the fallback is always on and the key/toggle go. |
Human judgment recorded@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
ce595e7 to
c5121ca
Compare
|
GPT, BLOCK (fenced): two empty whoami snapshots agreed vacuously. Fixed on |
|
/ai-review override first-principles c5121ca: /usage is a free local kiro-cli panel over GetUsageLimits (measured, documented); a config key guarding zero cost is dead surface, so the fallback is always on and the key/toggle go. |
Human judgment recorded@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
GPT, BLOCK (fenced): the scrape branch labelled and published against a whoami taken only after the read. Fixed on |
|
/ai-review override first-principles ccb8352: /usage is a free local kiro-cli panel over GetUsageLimits (measured, documented); a config key guarding zero cost is dead surface, so the fallback is always on and the key/toggle go. |
Human judgment recorded@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
When the free usage API returns no plan, the credit pill can still be filled by running `kiro-cli chat /usage` and reading the table it prints. That read costs nothing: /usage is a local slash command over the same free GetUsageLimits call, and three back-to-back runs left the account's usage counter unchanged. The code treated it as a billed chat turn, so it sat behind an opt-in config key that defaulted to off, a Settings > Display toggle for that key, an owner-only gate, and copy that warned about spending credits. The read is now the pill's automatic fallback: API first, /usage when the API has no plan, parked after repeated failures exactly as before. The account modal gets one plain Refresh button backed by POST /api/sessions/usage/refresh, refused with 409 while a refresh is already running and reporting a parked scrape only after the free API attempt. The dashboard.usage_text_scrape_enabled key, its schema field, its PATCH allowlist entry, the Settings toggle, its harness, its tests and its strings are removed; a config.json still carrying the key loads and keeps it as an unknown extra.
|
/ai-review override first-principles d15c192: /usage is a free local kiro-cli panel over GetUsageLimits (measured, documented); a config key guarding zero cost is dead surface, so the fallback is always on and the key/toggle go. |
Human judgment recorded@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Design, watch (span=51e54068b0da): the cost check should be repeated on the affected account class. Declined as on the previous heads. The three-run measurement was taken on the plan-less account class the fallback serves (the API returned no |
|
UX, watch (span=37facf2380c3): the earlier-reading fact appears in two severities. Declined on the same grounds as the previous heads: the GPT lane's blocking rule |
|
UX, watch (span=40d33582634e): the paused copy names a wait while Refresh is held. Declined: the sentence names WHEN the next press will work ("Try again in about N min.") and the button is held for exactly that window, which is the only honest pairing — an enabled button would answer 409/parked again. The notice clears on the next successful refresh or when the modal is reopened after the back-off; a countdown that re-enables the button live is a follow-up if the modal grows a ticking clock. |
|
UX, suggestion (span=c8e23d9514d0): render the 409 in the grey status style. Declined on the same grounds as the previous heads: the GPT lane's blocking rule |
|
UX, suggestion (span=245ff677d23d): |
bolichen97
left a comment
There was a problem hiding this comment.
Approving over the First Principles BLOCK, on evidence rather than on the author's own override.
The BLOCK rests on #2039's premise that a usage reader must not itself spend a billed turn. That premise was tested directly against this path, not reasoned about: two kiro-cli chat --no-interactive /usage calls three seconds apart on an org-managed account (the only account class the fallback serves) left the credit count byte-identical and returned the usage table with no model text. The fallback is not a billed turn, so the pin it is said to reverse does not reach it.
Every failure path still has a retreat in code and in tests: no kiro-cli writes available:false without spawning, an unparseable table parks the scraper for 6 hours after 3 strikes, and both timeouts reap the child before writing. The residual risk is upstream changing what /usage costs, whose remedy is a revert, not a config key.
Problem / Motivation
Some accounts (org-managed, IAM Identity Center) get no
credits_planfrom the free usage API. For them the top-bar credit pill shows nothing unless the dashboard reads the balance another way: runkiro-cli chat --no-interactive --agent kirocrew-lite /usageand parse the table it prints.That read has been treated as a billed chat turn since #2039, so it sits behind
dashboard.usage_text_scrape_enabled(default off), a Settings > Display toggle for that key (#12037), an owner-only gate on enabling it, and copy that tells the user each check spends credits.It costs nothing.
/usageis a kiro-cli slash command handled locally. Three checkable facts: the kiro.dev CLI reference lists/usagein the slash-command table next to/helpand/contextas "Usage limits with progress bar and credit balance", a client-side panel; the kiro-cli 2.23.0 binaries carryAmazonCodeWhispererService.GetUsageLimitsandcrates/amzn-codewhisperer-client/src/operation/get_usage_limits.rs, the same free API the pill's primary path calls; and three back-to-back runs on this account 7 s apart left the usage counter unchanged at 0.01 granularity, with the output being the usage table alone and no model text.Why it matters
The people who need the fallback are exactly the people whose pill is empty. Today they see "not available", are told to edit
config.json, and if they find the toggle they are warned about a cost that does not exist. A meter that reads for free should just read.What changed (motivation → approach → change)
src/kiro_crew/dashboard/handlers/sessions.py/usageread whenever the API returns no plan;api_sessions_usage_refreshforPOST /api/sessions/usage/refreshsrc/kiro_crew/dashboard/handlers/core.py,handlers/__init__.py,routes/system.pysrc/kiro_crew/config/sections.py,config/loader.py,config-baseline.jsondashboard.usage_text_scrape_enabledfield and reader removed; baseline regeneratedwebsite/src/components/KiroAccountModal.tsx,website/src/api/kiroUsage.ts,website/src/api/client.ts,website/src/App.tsxwebsite/src/pages/settings/DisplayPanel.tsxwebsite/src/i18n/locales/*.json(13 catalogs incl.en.manual.json,en-XA.json)website/src/components/commandPalette/settingsRegistry.gen.ts,src/kiro_crew/docs/settings-registry.generated.jsonsrc/kiro_crew/docs/configuration.md,docs/system-specs/modules/learn-cron-dashboard.md,docs/feature-map/README.mdThe fallback is on.
_fetch_usage_bgtries the API; with no plan it runs the/usageread. Parking after three failed or unparseable scrapes stays. An auth-class verdict plus a failed read carriesreason: signin_required.One Refresh button. Compact beside a reading, primary under "Could not read your balance." when there is none. Success renders the meter and writes the
['kiro-usage']query so the pill updates. Every outcome that is not a new reading renders throughErrorNoticewith the agent hand-off: a running refresh, a parked scrape ("Balance checks are paused because recent ones failed. Try again in about N min."), an earlier reading, anything else ("Could not read your balance.").The route.
POST /api/sessions/usage/refreshruns one refresh (API first, read second, like the timer) and answers with the GET's payload. Guards: the GET'sreject_if_kiro_unverified, and single-flight (409refresh_in_flight), shown through the same notice ("A refresh is already running.") with a usage re-read 3 s later and Refresh held meanwhile. A parked scrape is reported after the API attempt, not pre-checked, including one that parks during this refresh:skipped: "scrape_parked"withretry_after, returning what the parked path wrote.Identity. A reading is published only when a whoami taken immediately before the credential read and one taken immediately after it prove the same account (
_whoami_agreement: a shared non-empty email,start_urlor ARN, nothing disagreeing). This brackets the API call and the/usageread alike; a disagreement or an identity-less pair publishes nothing. Every cache writer re-resolves whoami before writing and keeps a prior reading only under_same_identity. Timeout and exception paths reap the scrape process first.In the modal, every refresh result is written into the shared usage query before any notice is chosen; an outcome notice replaces the standing one; Refresh is held while parked. An earlier reading returned by a refresh is not stamped as checked now: the modal says "The refresh did not return a new reading. Showing the earlier one." A failed refresh says "Could not read your balance."
Removed. The config key, the Display toggle with its test and harness, the
scrape-disabledstate, all cost copy.No reading is a visible state, on the Kiro backend. With nothing to read, the pill shows a dimmed dash ("no balance reading yet; open to refresh") and the modal stays open with Refresh. The dash is gated on
isKiroBackend(a positive check onagent.acp_backend); other harnesses keep hiding the pill and closing the modal once the config has loaded. When the['kirocrewConfig']read itself fails, the backend is unknown, so the pill is not hidden: it shows the dash labelled "could not read the backend setting; open to retry" (config-unreadable) and the modal opens on anErrorNotice("Could not load settings, so your balance can’t be shown.") with hand-off and Refresh, re-reading the config on open and on each press. The state iserrorUpdatedAt > 0 && data === undefined, the last settled outcome, so an in-flight retry does not flip the pill to the hidden shape.Backwards compatibility
Breaking:
dashboard.usage_text_scrape_enabledis removed. Writer sweep on origin/main @ 4e7f968:config/sections.py(schema field, deleted),config/loader.py(reader, deleted),handlers/core.py(_EDITABLE_CONFIGentry + owner-only PATCH branch, deleted;PATCH /api/config/kirocrewwith that key now answers 400 "field not editable"),handlers/sessions.py(gate + log copy, deleted; the read is unconditional),config-baseline.json(regenerated), both settings registries (regenerated),configuration.md(row deleted),learn-cron-dashboard.mdanddocs/feature-map/README.md(rewritten),test/test_usage_scrape_editable.py(rewritten to pin that the key is not a setting),test/test_session_usage.py(gate tests replaced by fallback tests). Aconfig.jsonstill carrying the key loads, keeps it in_extra_keys, round-trips it on save, and logs nothing about it (pinned by test).kirocrew config set dashboard.usage_text_scrape_enabled ...writes an unknown key with no effect. Anyone who had the key on gets the same behaviour they had; anyone who had it off gets a working pill.website/package.jsonswaps one script (verify:credit-meter-toggle→verify:usage-refresh); no dependency changes.Tests
Backend,
test/test_session_usage.py(111 pass): the timed refresh runs the read when the API has no plan and does not when it has one;TestUsageRefreshRoute: any authenticated caller 200; unverified-kiro guard ordering; 409 during a concurrent click and during a timer refresh with one spawn total; a parked scrape reported only after the API attempt (API returns a plan while parked → 200 with the plan and noskipped; API has no plan while parked →skipped: scrape_parked, no scrape spawned); cache replaced; auth-class verdict + failed read →reason: signin_required; a lapsed switch from account A to account B never shows A's email or balance under B; a timed-out refresh keeps only the same account's reading; a switch inside the refresh window is caught by the whoami resolved before preserving, on the failure and the parked paths alike.test/test_usage_scrape_editable.py(3 pass): key not editable, not in the schema, not in the registry; aconfig.jsoncarrying it loads and round-trips with zero log lines.TestFetchUsageBg: a recording fake pins the orderwhoami, kill, wait, whoamion both the timeout and the exception path, onekill, elapsed under 5 s.TestCredentialSelectionIsAnchored: the API path runswhoami, api, whoami; an A→B switch between the two publishes nothing and leaves{"available": False}with no trace of A; the same account publishes the adjacent snapshot's fields; a Builder ID pair agreeing on email alone publishes; the same email in a different org is a switch. Two identity-less whoamis with an API plan never publish the API numbers, spawn one scrape and cache its reading; with the scrape parked the cache is exactly{"available": False}; an identity that appears or vanishes between the two is a switch with no scrape. The scrape is bracketed too: orderwhoami, api, whoami, spawn, whoami; A→B across the scrape publishes nothing;{}×3 publishes nothing; a top whoami that fails but a bracket that proves A publishes from the after-snapshot; parked API partials ride the marker only when the pair agrees. Frontend (App.test.tsx110,App.creditPillError.test.tsx7,KiroAccountModal.test.tsx32): config 500 with no reading renders the dash with the config label and no no-reading label; opening shows the alert with hand-off and an enabled Refresh and re-reads the config; with that retry left hanging for 600 ms the dash, alert and dialog persist; the Refresh press invalidates the config query again before the POST.Frontend,
KiroAccountModal.test.tsx(23 pass): Refresh in the reading, failed and none states; pending disabled witharia-busyand no second POST; success re-renders the meter and writes the query; stale line present onstale; a refresh that returnsstaleis not stamped as checked now and shows the stale-refresh notice; 409 renders as a status line with no alert and re-reads after 3 s; parked and generic copy; a cold failure renders throughErrorNoticewith the hand-off and Refresh under it; a refresh that resolves to no reading writes that state into the query and the previous account's email is gone;askAgentandonHandoffon every failure notice; a parked refresh writes its result into the query before the notice; the pill keeps a dash and the modal stays open on a no-reading payload; the dash is absent for a non-Kiro backend and present for Kiro; a 409 renders through the notice with the hand-off, re-reads after 3 s and holds Refresh; one notice at a time in the failed state; Refresh held while parked or in flight.src/i18n/productName.test.tspasses (the round-one string it flagged is gone).Mutation-verified, source restored byte-identical after each: drop the 409 → 2 fail; pre-check the back-off before the API → 1 fail; drop the
scrape_parkedmarker → 2 fail; dropsignin_requiredon read failure → 2 fail; drop the frontend 409 classification → 1; not disabling while pending → 1; drop the query write → 2; droponHandoff→ 1; dropaskAgent→ 3; drop the stale line → 1; drop the identity check in_cache_transient_failure→ 5; pass the cache instead of the whoami on the timeout path → 1; re-addsetCheckedAton a stale refresh → 1; drop the stale-refresh notice → 1; render 409 as an alert → 1; drop the 3 s re-read → 1; route the cold failure back to the passive div → 1; drop its hand-off → 1; skip the query write on a no-reading refresh → 1; preserve against the top-of-refresh identity → 1; pass the stale identity on the parked path → 1; skip the query write on a parked refresh → 1; restore the modal auto-close → 1; hide the dash on a no-reading payload → 1; drop the backend check → 1; treat an unloaded config as Kiro → 1; drop the 409 hand-off → 1; drop the 409 re-read → 1; not hold Refresh on 409 → 1; stack both notices → 1; keep the stale line under the stale notice → 1; not hold Refresh → 4; hold only in flight → 2. Round 12: drop theconfig-unreadablebranch → 1;isError-only → 1; no config re-read on open → 2; none on Refresh → 1; notice without hand-off → 2; old reap order on timeout → 1; on exception → 1; reap without kill → 4. Round 13: drop the adjacent check → 4; compare against the top identity → 7; publish before the check → 1; merge top-identity fields → 1; ignorestart_url→ 1; one-sided agreement → 1. Round 14: empty pair agrees → red; skip the scrape fallthrough → red; publish before the check → red; keepapi_usageon the parked marker → red; one-sided evidence agrees → red; ignore a disagreeing field → red. Round 15: drop the before-snapshot → 7; judge the scrape against the top identity → 3; publish onunproven→ 3; label frombefore→ 1; publish before the check → 7; no-plan path against the top identity → 2; partials on an unproven pair → 1.Manual verification
/usagecost:kiro-cli chat --no-interactive --agent kirocrew-lite /usagerun three times at 22:22:10, :19, :26 UTC; the printed "Credits (N of M covered in plan)" showed the same N each time. Output is the usage table only, no model text.npm run verify:usage-refreshmounts the built SPA against the stub API, opens the pill's modal and asserts each state (button present where expected, pending disabled, one POST per click, meter reads the refreshed payload, pill updates, no credit control on Display) before shooting the frames below. Gates run locally: black (diff-scoped), isort, flake8, mypy, comment-history, feature-map, docs-lint, tsc, eslint at CI's warning cap,i18n:checkwith the per-locale suites.Screenshots / video
A reading with the compact Refresh:
No reading yet, with the primary Refresh:
An earlier reading, said plainly:
A refresh already running:
Pending, dark variants, and Settings > Display without the toggle
Related Issues
no linked issue: #7627 asked for the fallback to be reachable without the CLI, which an always-on fallback satisfies; #12037's placement of the toggle is moot once the toggle is gone.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)