Skip to content

fix(dashboard): read each agent's hidden status as its own sentence - #33206

Merged
bolichen97 merged 1 commit into
mainfrom
fix/32067-agent-status-sr-sentences
Nov 10, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/32067-agent-status-sr-sentences

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A screen reader reads the Agent Harness list's hidden status text as one separate sentence per agent, each naming that agent.

In Settings > Agent Harness, the screen-reader-only status text under the list reads as one run-on line that names no agent, for example "In use. Default.Missing on this machine: kiro-cliMissing on this machine: strands". Browse mode and the accessibility tree both read it that way, in every language. The in-use line also joins two catalog strings with an English space, so Japanese and Chinese get an ASCII space between full-width sentences.

Why it matters

A screen-reader user choosing an agent on first run hears one garbled line and cannot tell which agents are ready. Automated accessibility checks read the same text.

Not a goal

  • Changing the visible rows, their badges, or the wording of any status sentence.
  • Changing what a row announces when it is focused: its description stays the status alone, apart from the in-use line's spacing in Japanese and Chinese.
  • The same run-on shape in the Decisions card (see Sibling sweep).

What changed (motivation → approach → change)

A screen reader now reads the Agent Harness list's hidden status as one sentence per agent, each naming that agent: "Kiro CLI: Missing on this machine: kiro-cli", then "Claude Code: In use. Missing on this machine: claude-agent-acp".

The block used to put one inline <span> per agent side by side with nothing between them, so their text joined, and the in-use row glued "In use." to its status in code. Now AgentBackendTab.tsx gives each agent a <p> worded by one catalog message, row_status_sentence (<name/>: <status/>), and words the in-use row with one message, in_use_status. A status that already names its agent ("Kiro CLI is installed and ready to use.") is read as it is, so the name is never said twice. Both keys are translated in all twelve catalogs, with full-width colons in Japanese and Chinese, and en.context.json tells translators what they hold.

The name sits outside the <span> each row points at with aria-describedby, so a focused row still reads its name once and then its status.

Backwards compatibility

Compatible: only screen-reader-only text changes; element ids, existing catalog keys and row descriptions stay, except that the in-use row's description loses the ASCII space Japanese and Chinese read after "In use.".

Removes nothing: no key, id, element or behaviour is removed; the hidden block gains a paragraph and a name per row.

Tests

  • website/src/test/AgentBackendTab.test.tsx — reads the hidden status block as one paragraph per agent, led by its name: in Japanese, the hidden block is one <p> per agent; each is led by its name unless its sentence already names the agent (Kiro CLI installed), the in-use line is one message with no ASCII space, and the in-use row's description is still the status alone. It fails on the base (inline spans, no names, "使用中。 " with a space) and passes with the fix.
  • Determinism: the new test passed 20 runs in a row, and the three AgentBackendTab*.test.tsx files passed in a shuffled order (--sequence.shuffle --sequence.seed=15862, 130 of 130).
  • Red on the base, checked by hand in a throwaway worktree with only the production hunks reverted: it fails at the description wait, receiving "使用中。 このマシンにありません: claude-agent-acp".

Proof: not provable -- frontend test (prove.py runs Python only)

Manual verification

Built the SPA from this head, served it with fixture API answers, opened Settings > Agent Harness in headless Chromium, and read the block's ARIA snapshot plus each radio's computed description over the DevTools accessibility tree. Scene A is the reporter's machine (Kiro Agent in use, the other three missing a binary); scene B has Kiro CLI installed. German and Chinese read the same way as English and Japanese.

A en  paragraph: "Kiro Agent: In use. Default."
A en  paragraph: "Kiro CLI: Missing on this machine: kiro-cli"
A en  paragraph: "Strands: Missing on this machine: strands"
A en  paragraph: "Claude Code: Missing on this machine: claude-agent-acp"
A en  radio "Kiro Agent" description: "In use. Default."
A en  radio "Kiro CLI" description: "Missing on this machine: kiro-cli"
A ja  paragraph: "Kiro Agent:使用中。デフォルト。"
A ja  paragraph: "Kiro CLI:このマシンにありません: kiro-cli"
B en  paragraph: "Kiro CLI is installed and ready to use."
B ja  paragraph: "Kiro CLI はインストール済みで、すぐに使用できます。"

Screenshots / video

Why no screenshot: the change is to visually hidden screen-reader text, so no pixel on the page moves; the accessibility-tree text is shown under Manual verification.

Related Issues

Closes #32067

Sibling sweep

Swept: git grep -n -A3 'className="sr-only"' -- website/src, then each hit that maps rows into the block
Sibling: website/src/pages/settings/DecisionsCard.tsx:928 -- tracked in #33065
Sibling: website/src/cards/CardChanges.tsx:412 -- not affected -- one hidden word inside a visible line, with its own trailing space

Pattern harvest

Rule candidate: review-prompt
Pattern: a screen-reader-only container that maps several inline spans with no block element or separator between them, so browse mode reads them as one run-on line.

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 November 8, 2026 14:04
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: a small, contained fix to screen-reader-only text, with accessibility-tree evidence for a change that moves no pixel.

Notes

  • named: true is set by hand for each branch, so it can drift from which catalog strings actually contain {name}. If a later status sentence gains the name and the flag isn't set, screen readers say the agent's name twice.

[DESIGN-REVIEWED] ca22217

Description read

[DESCRIPTION-READ] bf056b8cb7785765012f3e418dee93a3b8e631f0f5a8256cbf14f7be03539992

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 Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks: the diff changes only screen-reader text, so no pixel moves and no screenshot could show it. The PR's accessibility-tree transcript covers each new sentence.

[UX-REVIEWED] ca22217

Description read

[DESCRIPTION-READ] a7a2d732f9154c112029d0088836a9c4463d592cf52032d77dce993bc418f412

That sha256 names everything this verdict read: the PR description, plus the 3 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 Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ca222178d9b5681e27c540ef1c02a50825c86c6d — 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. This fixes a reported defect (#32067), the PR adds a test that fails on base, and each new key and field is used by the hidden block.

What this change ships

Inventory (4 items) — 4 justified

Intent: let screen-reader users hear which agents are ready, one clear sentence per agent. This is a FIX.

  1. The hidden status block under Agent Harness now reads one paragraph per agent instead of one run-on line — justified
  2. Each paragraph starts with the agent's name, unless its status sentence already names the agent — justified
  3. The in-use line is now one translated message, so Japanese and Chinese no longer get an ASCII space after "In use." — justified
  4. Two new catalog keys (in_use_status, row_status_sentence) in all twelve locales, plus translator context — justified

[FIRST-PRINCIPLES-REVIEWED] ca22217

Description read

[DESCRIPTION-READ] 1829f88d4b44b9c137882a44046c1487629b82f1f14ea0ae9e6b9d1b0cab7918

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 Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ca22217

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable ca222178d9b5681e27c540ef1c02a50825c86c6d false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ca22217

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ca222178d9b5681e27c540ef1c02a50825c86c6d false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 enabled auto-merge (squash) November 8, 2026 14:14
@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 Nov 8, 2026
@bolichen97
bolichen97 force-pushed the fix/32067-agent-status-sr-sentences branch from 0268383 to f8e19bb Compare November 8, 2026 19:18
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto main to pick up the fix for main's red Backend Tests (3.12, 3) (#33221). The earlier red came from test/test_kas_skill_scope.py and related KAS tests failing on main at d1a9a81; this PR only touches frontend files. The patch is unchanged (same patch-id). Local frontend gate and local GPT and Opus reviews passed with no findings. Coverage Gate failed only because the backend shard failed (fail-closed).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 8, 2026
The screen-reader-only status block under Settings > Agent Harness put
one inline span per agent side by side, so browse mode and the
accessibility tree read every row's status as one run-on line that
named no agent. The in-use row also joined two catalog strings with an
English space.

Each agent now gets its own paragraph, worded by one catalog message
that leads with the agent's name, and the in-use row by one message of
its own, translated in every catalog. The span each row points at with
aria-describedby keeps the status alone, so a focused row does not
read its name twice.

Closes #32067
@bolichen97
bolichen97 force-pushed the fix/32067-agent-status-sr-sentences branch from f8e19bb to ca22217 Compare November 10, 2026 01:10
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/pages/developer/AgentBackendTab.tsx and the 13 i18n catalogs plus website/src/i18n/en.context.json since this head's CI ran (6d1e817 -> 39aecc7); GitHub reported the PR as conflicting. The only conflict was the icon import line in AgentBackendTab.tsx, where main added TriangleAlert (#32849) beside this PR's Trans import; both are kept and the change itself is unchanged. CI re-running.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 10, 2026

@buluoray buluoray 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 on ca22217. Screen-reader-only Agent Harness status block now renders one

per agent led by its name (unless the sentence already names it) and words the in-use line with one catalog message; visible UI and row aria-describedby text unchanged apart from the CJK space; tests green, both guards mutation-verified. Decisive lines: website/src/pages/developer/AgentBackendTab.tsx:1134, website/src/pages/developer/AgentBackendTab.tsx:1772, website/src/pages/developer/AgentBackendTab.tsx:1776-1777, website/src/test/AgentBackendTab.test.tsx:419

@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.

Approving. On head ca22217 the review traced every branch of status() and the hidden per-agent block, which is its only caller. It checked that the aria-describedby span still holds the status alone, and that both new keys exist in all 13 locale catalogs with their placeholders kept. It confirmed that the new test fails on the base, through the extra ASCII space after "使用中。" and the span children. It also checked the test against the determinism and side-effect rules.

Done well: the separator is now a translatable <name/>: <status/> message, and the name stays outside the described span. Browse mode reads one sentence per agent, and focus announcements do not change.

Optional:

  • #34147 adds a sandbox_refusal branch to the same status(), and its sentences already name the agent. Whichever PR lands second should return { text: sandboxRefusalLine(value), named: true }. Without that flag the code still compiles, but the hidden block reads the name twice.
  • Only the ready-to-use named: true flag has a test. A wrong-version row and a restart-required row in the new test's fixture would make deleting either of the other two flags fail a test.

@bolichen97
bolichen97 merged commit dd3cbea into main Nov 10, 2026
100 of 109 checks passed
@bolichen97
bolichen97 deleted the fix/32067-agent-status-sr-sentences branch November 10, 2026 13:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 10, 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.

Agent list: hidden screen-reader status text runs together with no separators

3 participants