Skip to content

fix(crew): say what a worker-kit refusal means and list the real kit - #23565

Merged
iamwhatever merged 2 commits into
mainfrom
fix/worker-kit-errors-preview
Oct 24, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/worker-kit-errors-preview

Conversation

@buluoray

@buluoray buluoray commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crewmate's worker-kit screens say in plain words what went wrong, and show the same worker kit everywhere: Built From's counts and lists, and the copy preview.

Three things in the worker-kit surfaces that #23010 added read wrong:

  • A refused copy showed the route's machine code as the message: stale_revision, invalid_spec, template_restrictions_uncarried and the rest appeared verbatim in Advanced > Worker's extra kit, in the editor's Built from, and in the Customize > Crewmates roster cell.
  • For a crewmate that owns its config file, Built From's summary counted the worker's merged kit (for example 18 tools) while its Tools / MCP Servers / Skills tabs listed only the rows in the crewmate's own file, so the number and the list did not match.
  • The copy preview left out what a template restricts on a server the worker base already has (a switched-off server, a turned-off tool). The copy writes those limits and the worker applies them, but the owner never saw them before pressing Apply.

Why it matters

Advanced > Worker's extra kit is where an owner changes what a crewmate's worker can do. A raw code tells them nothing about what to do next. A count that disagrees with the list next to it makes the whole summary look unreliable. A preview that leaves out a restriction asks the owner to confirm something they were not shown.

Not a goal

  • Changing what a copy writes, or which templates it refuses.
  • Changing how keep_additions decides what counts as added since the last copy.
  • Showing which Built From rows came from the base and which came from the crewmate's file.
  • Any change to the classic Capabilities page or to crewmates bound to a shared template.

What changed (motivation → approach → change)

  • Refusal text. The worker-kit routes send {"error": code, "code": code}, and the three callers rendered err.message, which is the code. components/crew/workerKitErrors.ts maps each code the routes send to a catalog sentence that says what to do (preview again, choose another template, fix the file). Any other failure, such as an owner-only refusal or a dropped connection, keeps the text the transport already made readable. WorkerKitPane, builtFromName and kiroCrewAgentsPageRosterLabels all go through it. When Apply gets stale_revision, the pane also drops the preview it can no longer apply, so the next step is a fresh preview. The errors still render through ErrorNotice, with the same hand-off settings as before.
  • One set for Built From. mate_capabilities.worker_summary used to return three counts read from the merged worker spec. It now returns the merged spec's rows (worker.rows: tools, auto-approvals, servers without their approval lists, and skills, where a skill:// resource is named by its folder). For a crewmate that owns its file, CrewEditorNextDialog reads the summary tiles, the three tabs and the auto-approval badges from that one row set. Server rows still go through safe_view, so a transport credential is masked here the same way as in the file rows.
  • Restrictions in the preview. _worker_kit builds the preview's before and after from worker_additions, then passed them through _kit_of, which drops disabledTools and disabledServers. Those are exactly what a file restricts on a base server, because the base's own entry wins the merge. _worker_kit now keeps both (a per-tool limit only when it is on a base server, since a server the kit adds already shows as a changed connection), and _changes lists them added or removed. The pane shows them as "Turned off", using the existing section label.
  • A preview you can scan. The copy preview was one mixed list with the change word in muted grey. components/crew/workerKitGroups.ts puts each row under one kind, in a fixed order (Instructions, Connections, Tool access, Skills, Auto-approvals, Turned off), each kind under a PanelSectionHeader with its row count and divider, and orders a kind added, then changed, then removed, then by the shown name. Each change word is a badge tinted by its hue (bg-ok-subtle / bg-warn-subtle / bg-danger-subtle) with a hue-coloured glyph (plus, pen, minus). The word itself is painted in text-text: a plain status hue on its own tint reads 3.08:1 in kiro-dark (--ok is #008543 there), while the glyph only needs the 3:1 non-text floor. The word stays, so colour is never the only cue. The rows no longer repeat the kind, so crewWorkerKit.section_mcp, section_skill and section_approval leave every catalog (the dead-keys ratchet counts them). Under "Turned off" a row IS a restriction, so its badge states the effect instead of a change word: "Turns off" (danger tint) when the copy adds the limit, "Turns back on" (ok tint) when it lifts it. A tool selector reads as what the worker can use (toolAccessLabel: "Can use every jira tool"), so a Tool access row never reads like an Auto-approvals row.
  • Review rounds on 3045613fd5, 3af35278b4 and e1462a5ae3. error_stale_revision and error_revision_required name the button that makes a preview through {{action}} ("Press “Copy into the worker” again to see the new changes."); WorkerKitPane passes the label its preview button shows right now, so a re-copy names "Re-copy from template". The three refusal sentences say "mate", per docs/decisions/2026-10-15-the-standing-teammate-agent-is-called-a-mate.md. The roster's hand-off is given the failed request's report (reportForError) along with the translated sentence, since findReport matches messages exactly and the chat would otherwise lose the endpoint, status and body; the card's notice takes a whole grid row so the sentence does not wrap one word per line. A skill:// row in Built From is no longer labelled **: the server sends skill rows with no label, and the pane names them with the preview's own workerKitLabels.skillLabel (a folder by its name, a pattern as "Skills in skills"), so one function names a skill URI.
  • docs/system-specs/modules/crew-mode.md describes all four.

Backwards compatibility

Compatible: the worker field on the capability view changes shape from three counts to {rows}, and its only reader is the editor in this same diff. The preview can now also return two new section values, and the pane in this diff labels them. No request shape changes.

Removes nothing: the counts were replaced by rows that hold the same numbers, and only the editor in this diff reads either.

Tests

  • test/test_mate_worker_kit.py::test_the_preview_lists_what_a_copy_restricts_on_a_base_server: a template that switches off a base server, or turns off a tool on one, shows as an added row in the preview, and as a removed row once a re-copy drops the limit.
  • test/test_mate_capabilities_worker_summary.py: the rows are the merged worker spec's tools, approvals, servers and skills. A skill:// skill is named by its folder, and a server row keeps its switch-off but not its approval list.
  • test/test_mate_capabilities_redaction.py::test_the_workers_server_rows_are_masked_too: no env or header token reaches the browser through worker.rows.
  • WorkerKitPane.test.tsx: stale_revision, template_restrictions_uncarried and template_unreadable each read as a sentence and never show the code. A stale apply drops the preview. An owner-only message passes through unchanged. Restriction rows are named.
  • WorkerKitPane.test.tsx (grouping): headings come out as Instructions, Connections, Auto-approvals with their counts; a kind lists added, changed, removed; each badge carries its tint class and its word, with the hue on the glyph.
  • WorkerKitPane.test.tsx (restrictions): a restriction row's badge reads "Turns off" on the danger tint, a lifted one "Turns back on" on the ok tint.
  • workerKitLabels.test.ts: a tool selector reads "Can use every jira tool" / "Can use read on notes", never the approval wording.
  • KiroCrewAgentsPage.rosterLabels.test.tsx (hand-off): in both views the roster's "Ask the agent" is handed the failed request's report; dropping report= reddens it in both.
  • test_mate_capabilities_worker_summary.py::test_a_skill_row_carries_no_name_of_its_own: every skill row the server sends has an empty label, so the pane is the only namer.
  • CrewEditorNextDialog.test.tsx (skill URIs): a worker's skill pattern reads "Skills in skills" and a .../release-notes/SKILL.md row reads "release-notes".
  • WorkerKitPane.test.tsx (button names): a stale Apply on a re-copy names “Re-copy from template”, the button on screen; workerKitErrors.test.ts covers the default first-copy label.
  • workerKitGroups.test.ts: every section lands in its kind, in the fixed order, empty kinds are left out, and a kind sorts by change then name.
  • workerKitErrors.test.ts: every refusal code reads as its sentence; an unknown code, an inherited property name, a plain Error and a string keep their message (this also brings the module to 100% per-file coverage).
  • KiroCrewAgentsPage.rosterLabels.test.tsx: a roster cell shows invalid_spec as its sentence, in both card and list views.
  • CrewEditorNextDialog.test.tsx: the summary tiles and the Tools / MCP / Skills lists show the worker's rows, and not the file's.

Proof: PROVEN test/test_mate_worker_kit.py::test_the_preview_lists_what_a_copy_restricts_on_a_base_server[entry0-row0], test/test_mate_worker_kit.py::test_the_preview_lists_what_a_copy_restricts_on_a_base_server[entry1-row1] (head 94989b6)

The frontend changes were checked by mutation by hand: pointing the Tools tab back at the file rows fails the dialog test.

Manual verification

On a pod of this branch, with a release-bot template whose kirocrew-core entry turns off cron_add, everything below was driven by Playwright and captured in the screenshots:

  • Advanced > Worker's extra kit: picked release-bot with "Keep what was added" off and previewed. The preview groups the rows and ends with "Turned off 1 · Turns off · cron_add on kirocrew-core". The box scrolls inside the editor; the end shots below are the same preview scrolled to Apply.
  • A stale Apply: previewed, then edited the mate's file on disk, then pressed Apply. The pane shows "This mate's config or the template changed after the preview. Press “Copy into the worker” again to see the new changes.", the preview is gone and that button is back.
  • A lifted restriction: copied release-bot (turns off cron_add on kirocrew-core), then previewed release-bot-lite, which does not. The preview shows "Turned off 1 · Turns back on · cron_add on kirocrew-core" on the ok tint.
  • An unreadable file: wrote broken JSON to a second mate's file. Customize > Mates shows "This mate's config file can't be read. Fix or restore the file, then try again." with Ask the agent, in the card and the list view.
  • Not shown, and why: the editor's own Built from error (builtFromName). It renders only when the capability view reads and the worker-kit read fails. An unreadable file fails the capability read first, so the editor never reaches it, and General then shows the binding id as Built from. That fallback is feat(crew): give each crewmate its own config, a conductor and a worker #23010's and outside this goal; it is reported to the owner as a follow-up.

Badge contrast, measured from the pod screenshots (word / glyph against its tint): light Added 7.81 / 8.29, Changed 8.28 / 8.54, Removed 7.88 / 9.40; dark Added 10.50 / 3.08, Changed 9.42 / 6.98, Removed 10.52 / 4.15. Words clear 4.5:1 and glyphs clear 3:1 in both. Other built-in palettes were not measured.

Screenshots / video

The copy preview, before and after, in the light and dark default themes (same template):

Light Dark
Before Before, light: one flat grey list Before, dark: one flat grey list
After, top After, light: grouped under counted headings After, dark: grouped under counted headings
After, scrolled to Apply After, light: Tool access, Skills, Auto-approvals and Turns off After, dark: Tool access, Skills, Auto-approvals and Turns off

The refusal sentences:

Advanced after a stale Apply: the sentence names the Copy into the worker button shown below it

A restriction the copy lifts:

Light Dark
Turned off group with a Turns back on badge, light Turned off group with a Turns back on badge, dark
Roster, cards Roster, list
Mates card: the unreadable-file sentence across the row, with Ask the agent Mates list: the unreadable-file sentence in the Built from column
Earlier rounds

First round: the flat preview with the new restriction row

First round: Built From summary

First round: Built From tools

Related Issues

Follow-up to #23010.

Sibling sweep

Swept: git grep -n crewWorkerKitApi -- website/src ':!*.test.*' (every caller of the worker-kit routes)
Sibling: website/src/components/crew/WorkerKitPane.tsx -- changed here
Sibling: website/src/components/crew/builtFromName.ts -- changed here
Sibling: website/src/pages/kiroCrewAgentsPageRosterLabels.ts -- changed here

Pattern harvest

Rule candidate: review-prompt
Pattern: a route whose error is a machine code rendered through err.message instead of a code-to-catalog map

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

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 23, 2026 21:37
@buluoray
buluoray requested a review from mbriones98 October 23, 2026 21:37
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 94989b6883301d4b28f63dde5b8fa189d7c8b13b — 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

The three fixes are aimed at their causes. The preview redesign rides along on a fix whose Goal never asks for it, and nobody is named as having had trouble reading the old list.

Notes

  • Items 6–9 — rides along, unjustified move: the Goal is "say in plain words what went wrong, and show the same worker kit everywhere". The redesign rests only on "The copy preview was one mixed list with the change word in muted grey". No report or observed misread is cited, so existing users relearn the layout for a harm nobody has shown. Subtraction: drop the second commit (workerKitGroups.ts, the tinted badges and glyphs, the "Turns off"/"Can use…" relabels, the removal of the section_* keys). Keep only the label that names the new disabledTools/disabledServers rows. Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (10 items) — 6 justified

Intent: a mate's owner sees refusals as plain sentences and one consistent worker kit across Built From and the copy preview. This is a FIX.

  1. Worker-kit refusals read as sentences, not codes, in three places — justified
  2. A stale-revision Apply drops the preview it can no longer apply — justified
  3. Built From's counts and Tools/MCP/Skills tabs read one merged worker row set — justified
  4. The capability view's worker field changes from counts to {rows} — justified
  5. The preview lists what a copy turns off on a base server — justified
  6. The preview is regrouped by kind under counted headings, in a fixed order and sort — rides along, unjustified move
  7. Change words become tinted badges with glyphs — rides along
  8. Rows drop the per-row kind word, and three catalog keys are removed — rides along, relabel
  9. "Turns off"/"Turns back on" badges and the "Can use every X tool" wording — rides along, relabel
  10. The roster's "Ask the agent" hand-off still carries the failed request's report — justified

[FIRST-PRINCIPLES-REVIEWED] 94989b6

Description read

[DESCRIPTION-READ] 007a4173ff7fa07ce98a23af1d8b12dcb5bdeb29f50188f41464cd72894eea57

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. The worker shape change has one reader, CrewEditorNextDialog, and this diff updates it.

[DESIGN-REVIEWED] 94989b6

Description read

[DESCRIPTION-READ] 8ce715f790dc92a5d179e9e935c18e8fffb5922b10feb062b281729170416a0c

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

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

UX-Verdict: PASS

cannot evaluate: missing the shipped stale-preview sentence. Shot-07 shows "Preview the copy again.", but the diff ships "Press “{{action}}” again to see the new changes.", so nobody has seen the wording this PR exists to fix.

Evidence gaps

  • Stale-preview message in Advanced > Worker's extra kit. en.manual.json ships error_stale_revision with {{action}} filled in as "Copy into the worker", but shot-07 shows an older sentence. A new still of the pane after a stale Apply would close this.
  • Built From's Skills and MCP Servers tabs, now reading worker.rows. This includes the new skillLabel name for a skill:// row with no label. Only the Tools tab (shot-12) is shown. Stills of both tabs for a crewmate that owns its file would close this.
  • Roster card-view error notice (col-span-2, actionPlacement="below"). Shot-08 cuts it off at "…ent", and shot-09 shows the table view only. A full card-view still with the error would close this.

Notes

  • The "Turned off" heading sits over a "Turns off" badge (shot-05), and the reader saw the two tenses clash. Either make the heading "Turned off tools", or make the badges "Off" / "Back on".
  • The refusal sentences say "This mate's config", and the blind reader did not know what "config" is (shot-07). Use "This mate's settings file" instead.
  • The badge glyph in shot-05 looks like a crossed-out alarm clock to the reader, but the code renders PowerOff. Recapture it with the other stills.

[UX-REVIEWED] 94989b6

Description read

[DESCRIPTION-READ] 1a25afb10e6c3bc0c27767d5b720063bc81d73294a5d8a12b8b1f0bdb67d4152

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 94989b6

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

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

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 94989b6

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

@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 23, 2026
@buluoray buluoray mentioned this pull request Oct 23, 2026
5 tasks done
@buluoray
buluoray force-pushed the fix/worker-kit-errors-preview branch from c5c9367 to 3045613 Compare October 23, 2026 23:37
@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 23, 2026
@buluoray
buluoray force-pushed the fix/worker-kit-errors-preview branch from 3045613 to 3af3527 Compare October 24, 2026 00:33
@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 24, 2026
@buluoray
buluoray force-pushed the fix/worker-kit-errors-preview branch from 3af3527 to e1462a5 Compare October 24, 2026 02:02
@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 24, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

🤖 Kiro Crew Auto-Pipeline [operator: buluoray#ce473fca]: First Principles on 3af35278b4:

  • Blocker (second spelling of skill naming): fixed in e1462a5ae3. _skill_folder_name, _GLOB_SEGMENT and the re import are gone. Skill rows in worker.rows carry label: "", and Built From's Skills tab names a skill:// row only through workerKitLabels.skillLabel, the same function the preview uses. Tests: test_a_skill_row_carries_no_name_of_its_own, and the dialog test that reads "Skills in skills" for a pattern and "release-notes" for a folder URI.
  • Note (items 5–7 ride along): not taken. The grouped preview, the coloured change badges, the "Turns off" / "Turns back on" wording and the "Can use…" tool rows were requested by the owner (Ray, @buluoray) in his review of this PR's preview, because the flat grey list was hard to tell apart. They change only the preview this PR already touches. The Goal is unchanged.

@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 24, 2026
The worker-kit routes refuse with a machine code (stale_revision,
invalid_spec, ...) that the Advanced pane, the editor's Built from and
the roster showed as it was. Each code now reads as a localized
sentence, and a stale apply drops the preview it can no longer apply.

Built From counted the worker's merged kit but listed only the file's
own rows; the capability view now returns the worker's rows, and the
summary and the Tools / MCP / Skills lists both read them.

A worker-kit preview diffed the kit without the limits a copy sets on
servers the worker base declares (a switched-off server, a turned-off
tool), because the base's entry wins the merge; those are now listed.
The copy preview listed every row in one mixed list with the change
word in muted grey, so a long re-copy was hard to read. Rows now sit
under one counted heading per kind (instructions, connections, tool
access, skills, auto-approvals, turned off), added before changed
before removed, and each change word is a badge tinted by its hue with
a hue-coloured glyph. The word itself stays in the text colour, since a
plain status hue on its own tint reads under 4.5:1 in kiro-dark.

Under "Turned off" the badge states the effect ("Turns off", "Turns
back on") instead of a green "Added", and a tool selector reads "Can
use every jira tool" so it is not mistaken for an auto-approval.

The refusal sentences say "mate", per the recorded naming decision, and
the two that ask for a fresh preview name the button that makes one.
The roster's hand-off now carries the failed request's report, since
its message is translated, and the card gives the sentence a whole row.
A skill URI in Built From is named only by the pane, with the same
skillLabel the preview uses, so a pattern reads as the folder it covers.

The three section labels the rows no longer show leave the catalogs,
and workerKitErrors gets its own test so every refusal code is covered.
@buluoray
buluoray force-pushed the fix/worker-kit-errors-preview branch from e1462a5 to 94989b6 Compare October 24, 2026 02:48
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 24, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) October 24, 2026 06:14
@iamwhatever
iamwhatever merged commit 29334c8 into main Oct 24, 2026
159 of 167 checks passed
@iamwhatever
iamwhatever deleted the fix/worker-kit-errors-preview branch October 24, 2026 06:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 24, 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.

2 participants