Repository navigation
feat: let any crewmate guide users to the control on their screen - #18443
Conversation
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Crewmate creation was redesigned along the way, and a model-written chat link opens prefilled create drafts, even though the Goal says guides only highlight. Not justified as shipped
What this change shipsInventory (8 items) — 6 justifiedIntent: let any crewmate show users where a Kiro Crew control is on their own screen. This is an ADDITION, covered by
[FIRST-PRINCIPLES-REVIEWED] e64c4bf Description read[DESCRIPTION-READ] efff6342fa0c901606b14f8bbbe3f4cb93698dad06c3e6993592802d9d9aa046 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ human override acceptedHuman judgment by @buluoray overrides the GPT 6.1 finding for [GPT-OVERRIDE] e64c4bf This comment is updated in place on each push. The model was not re-run because an authorized human decision supersedes it. False positive or not applicable? A repository writer can comment: |
6dd9d77 to
ab68b31
Compare
40c156a to
5d0724b
Compare
ab68b31 to
2fdd164
Compare
5d0724b to
de717d0
Compare
2fdd164 to
915d831
Compare
de717d0 to
3ba9530
Compare
915d831 to
4518263
Compare
3ba9530 to
56b5be4
Compare
4518263 to
79b7e18
Compare
56b5be4 to
d8add30
Compare
79b7e18 to
7d3595a
Compare
Human judgment recorded@buluoray marked the design 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. |
|
/ai-review override ux e64c4bf: The lane failed closed because the diff exceeds 1 MB (mostly the generated UI index); the owner reviewed the UX on preview gateways. |
Human judgment recorded@buluoray marked the ux 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 Review (Opus 5.5) — ✅ human override accepted@buluoray overrode this lane for |
UX Review (Opus 5.5) — ✅ human override accepted@buluoray overrode this lane for |
chenmingwei23
left a comment
There was a problem hiding this comment.
Review of head e64c4bf (review only, not an approval).
The problem is real. "Where is X?" is a frequent question, and pointing at the live control is a better answer than describing it from memory. The approach is sound: the agent can only read or offer, the gateway owns guide state, and the tab decides from element identity what may be outlined. I read the hand-written backend in full (handlers/guide.py, dashboard/guide_runs.py, the guide_catalog.py validators, mcp_guide.py tools, guide_observe.py sender/lang intake, the chat_handlers/ws_event_scope/history_projection hooks). On the frontend I read findByName.ts, findTargetPolicy.ts, untrustedContent.ts and the GuideContext navigation. I ran test_guide_admission.py, test_guide_runs.py and test_search_docs.py: 50 passed. The main problem is scope, not code.
BLOCKING
1. Split the PR. It is 314 files, one commit, about 14k lines of Python and 28k of website/src, and it touches security_posture.py. Several parts are separate changes:
- The Crewmates page create flow: MembersPage.tsx, MeetCrewmatesFlow.tsx, the removed Meet CrewMates button and its locale keys, and the crewmate-create hook in agent_admin/crew_records.py. First Principles flagged this flow, and it was accepted by override.
- The website/scripts/check-i18n-keys.mjs refactor into lib/i18n-key-resolve.mjs.
- The delete-button
guideCautionmarkers across website/src/apps and src/kiro_crew/apps.
Suggested split:
- (a) The generator, the committed index, the read-only
find_ui/search_docstools and the CI freshness check. This PR adds no browser routes. - (b) The guide runs store, the agent and browser
/api/guide/*routes, observation, GuideLayer / GuideOfferCard, card rows and theguide/*crew-log entries. - (c) The Crewmates page flow plus the
crewmate.createcommit hook (run_guided_crewmate_create).
Each piece is reviewable on its own, and (a) is useful by itself.
SHOULD-FIX
2. The committed generated index is coupled to the whole UI. src/kiro_crew/docs/ui-index.generated.json (5.9k lines) and website/src/uiLocations/guidePlans.gen.ts (3.3k lines) are regenerated from every surface and all 12 catalogs. build_digest at ui-index.generated.json:5 changes on any input change. npm run gen:ui -- --check in ci.yml and in npm run build both fail when the index is stale. So any unrelated PR that edits a label or a marker must regenerate both files, and two such PRs always conflict on the digest line.
The backend goldens make this worse. test_find_ui_heldout.py and the roughly 70 cases in test_find_ui.py assert search ranking against the committed live index, so a copy edit in one area can turn Python tests red.
Fix: build the index at package time, as the auto tier already is (static/dist/ui-index.auto.json), or add a regenerate-on-merge job. Run the ranking tests against a fixture index and keep only a small smoke set against the live one.
3. Live observation is not gated on a user turn. _USER_TURN_OPERATIONS at handlers/guide.py:150 covers only guide.start and member.rename_self. /api/guide/agent/observe therefore admits any running dashboard-slot turn, including a loop wake or an injected turn. Every find_ui search (_with_live, mcp_guide.py:901) pushes a guide_observe frame to the user's tab. If the tab does not answer in time, handlers/guide.py:436 calls note_stale_tab and broadcasts a change to the user's running guide.
The reply is enum-only, so the risk is low. It is still a crewmate probing the user's screen and changing the user's guide state on a turn the user did not send. Fix: add guide.observe to the user-turn set, or skip observation on non-user turns. In either case, do not mutate a guide on an observe timeout that a non-user turn caused.
NIT
4. Serial waits in find_ui. find_ui makes two gateway calls one after the other: _dashboard_ui_lang (1.0s, mcp_guide.py:878/1079) and then observe (1.5s, :873). That adds up to 2.5s to a search when the tab is slow or absent. Return ui_lang in the observe reply instead.
5. Missing audit on observe refusals. handlers/guide.py:411, :429 and :439 return not_observed without _audit. Only success is audited (:442).
6. Untrusted-content exclusion is easy to lose. findByName.ts:192 interactive() excludes untrusted content only through the default shown predicate (isDisplayed, liveRegistry.ts:60). Every caller passes it today, but a future caller with a different predicate would silently match agent-authored markdown and artifacts. Put the inUntrustedContent filter inside interactive().
7. search_docs re-reads all docs on every query. It reads all 56 packaged docs (about 900 KB) per query (mcp_guide.py:846). Cache them on mtime, as guide_catalog does.
8. CodeQL alert is a false positive. The "incomplete multi-character sanitization" alert on findTargetPolicy.ts:108 stripTags is one: the result is only matched against catalog values and never rendered. Dismiss it with that reason.
What looks good
- Admission (
_resolve_agent_caller). It requires the internal secret and an attested session key. It refuses app, subagent, unattended, app-scoped and channel-born or channel-steered turns.guide.startadditionally needs a turn the user sent. The admission tests cover each refusal. - Browser half. It is owner-only, and every write checks revision, owner tab and lease. The
crewmate.createcommit step completes only from the gateway's own successfulPOST /api/agentsresponse, never from the tab's word. A failed save callsabort_commitand returns the handler's response unchanged. - Trust roots, enforced twice. The server checks routes, location ids, excluded settings tabs and deny policy. The tab decides from element identity (
isTrustRootTarget,data-guide-trust-rootregions, catalog keys in any language), not from the agent's words. The English-onlyCEILING_LABEL_REis only a backstop. - Marker hygiene. Guide markers are stripped from sanitized markdown and artifacts, so agent content cannot pose as a product control.
- Bounded state. Stores are capped (
MAX_LIVE_GUIDES,MAX_STORED_GUIDES,MAX_PENDING,MAX_SENDERS), browser input is validated field by field, andclean_find_reportkeeps page text in the tab. - Docs lookup.
search_docslooks up a page by name from the directory listing, so a caller string never becomes a path. - Card rows.
cardis inDISPLAY_ONLY_ROLES, so offers never reach the model, and their text passes the redactors before it is stored. - Generated-artifact checks. CI checks the index is fresh and runs the generator-required goldens with a skip-to-fail switch. This is the right mechanism for keeping committed generated files honest.
Problem / Motivation
Goal: Let any crewmate answer "where is X?" and "how do I do Y?" about Kiro Crew by pointing at the real control on the user's screen, with every click still the user's.
Today a crewmate asked "where do I turn on the terminal?" can only describe the dashboard from memory or tell the user to search Settings and the docs. It cannot see where a control lives on this build or show it on the live page, where the control is often behind a collapsed sidebar, a closed menu or a phone layout. The decision is recorded in
docs/request-for-change/rfc-crewmate-guides-and-mate.md(accepted, merged in #18326). This is the second of three PRs that ship it: Mate (#18406, the base of this PR), then guided tours (this one; it replaces #18301), then change cards.Why it matters
The long tail of Kiro Crew settings is where people get stuck, new and existing users alike. A crewmate that finds the exact control and walks the user to it on their own screen turns a docs search into a one-message request.
Not a goal
What changed (motivation → approach → change)
Approach: extend the
kirocrew-guideserver from #18406 with tools that can only read or offer. Pointing at the UI uses an index generated from the dashboard source and the live page, not a remembered map; the gateway owns every guide's state.src/kiro_crew/mcp_guide.py):find_ui(search or browse the location index, labels in the user's dashboard language),search_docs(packaged user docs),guide_list_actions/guide_start/guide_status/guide_cancel. Trust-root and caution rules travel in each tool's text and each result'snextline. All seven tools are exactallowedToolsgrants (agent._GUIDE_AUTO_GRANTS,config/defaults.json), through the governance ceiling.ui_index.py,website/scripts/gen-ui-index.mjs,website/src/uiLocations): curated plus auto-stamped controls in 12 languages, generated intosrc/kiro_crew/docs/ui-index.generated.jsonandguidePlans.gen.ts; CI checks it is current.GUIDE_DENY_IDSmarks the approval-mode picker and a crewmate's permission pickerdeny.guide_catalog.py,dashboard/guide_runs.py,dashboard/guide_observe.py,dashboard/handlers/guide.py): registered actions (settings.show,crewmate.create,mcp.open_add,ui.show,ui.find), claim/progress/lease per tab, reveal, select and gate steps, viewport re-planning, and a bounded live observation of one tab. Starting a guide uses feat: welcome users with Mate, a first crewmate they get to name #18406's admission: only a turn the user sent from the dashboard.website/src/guide,GuideLayer.tsx,GuideOfferCard.tsx): the offer is a card in the chat; after Start, the layer opens the page and outlines the control beside a step panel, and a press on the target finishes the step. Each offer is acardrow of the conversation (dashboard/chat_cards.py,cards/ConversationCard.tsx) and aguide/*crew-log entry, so it stays where it was offered across a reload.MembersPage.tsx,MeetCrewmatesFlow.tsx): New crewmate and a crewmate's create link open the embedded flow in place of the chat; Advanced opens the full form.Smaller pieces:
crew_log/emit.py,crew_log/entry_types.py,crew_log/schema.pyandhistory_projection.pyadd theguide/*entries and the display-onlycardrole;chat_runner.pyreads past a card row;security_posture.pylists the guide-row redaction sink and the gate-side catalog;validation.pyholds the argument schemas;dashboard/server.py,server_runtime/mcp_routes.py,dashboard/state.py,chat_handlers.py,ws_event_scope.pyandagent_admin/crew_records.pywire the routes, the sending tab and the crewmate-create hook;src/kiro_crew/appsandwebsite/src/appsmark delete buttonsguideCaution;website/src/api,website/src/store,website/src/hooks,website/src/components,website/src/shell,website/src/surfaces,website/src/lib,website/src/pages,website/src/app-sdk,App.tsxandvite-env.d.tscarry the markers and wiring;src/kiro_crew/agent.pyandsrc/kiro_crew/agent_materialization(service agents) grant the new tools and keep them off background agents;website/src/i18nholds the strings;.github,.gitignoreandsrc/kiro_crew/builtin_skillsrun the index check;src/kiro_crew/docsanddocs/cover MCP, crew log, crew mode, history, config and the feature map;test/gui_useradds scenarios.Backwards compatibility
Compatible: agents that do not mount the server behave as before, and the new routes refuse callers they cannot attribute to a dashboard turn; they accept nothing main accepted before.
Reader: website/src/pages/members/MembersPage.tsx:meet_crewmates -- crew page -- the empty-roster Meet CrewMates button and its locale keys are removed; the empty state's New crewmate hero opens the same flow (
MembersPage.test.tsx)Tests
test_find_ui*.py,test_guide_*.py(routes, runs, observation, reveal/select/gate steps, re-plan, the approval-mode and permission pickers never guided),test_guide_admission.py(real admission for start and reads: channel turns and non-user turns refused, reads still answer),test_guide_server.py(mount, per-tool grants, off-dashboard wording, offer hints),test_search_docs.py, plus updated composition, spec-byte, crew-log and MCP contracts.src/guide/*.test.tsx,src/uiLocations/*.test.ts,cards/ConversationCard.test.tsx,ChatPane.cardColumn.test.tsx,TurnBlock.cardRow.test.tsx,chatSlice.cardRow.test.ts,MeetCrewmatesFlow.test.tsx, Members page cases.not_user_turncheck, the trust-root route check or aGUIDE_DENY_IDSentry reddens a named test.Manual verification
Earlier heads, live on a preview gateway with real model turns: "where do I change the theme?" →
find_ui+guide_start, and Start opened Settings → Display and outlined Theme; "How do I delete a schedule myself? Show me." → a two-step guide ending on the outlined Delete with its caution line, nothing deleted; at 390px the card and step render as a bottom sheet. Gates on this head: black, subprocess-encoding, isort, flake8, mypy, docs-lint, harness parity,tsc,npm run build(with the index check), i18n against origin/main, eslint on changed files; related pytest (about 18.8k tests; the only reds,test_agent_template_skills.pyreorder cases, also fail on origin/main on this host) and vitest (881 targeted; the wider run's other reds also fail on the #18406 branch on this host). Not exercised: Windows and macOS hosts.Screenshots / video
All frames from an earlier head of this branch.
Related Issues
Closes #18300
Part of the RFC in #18326; based on #18406 (Mate); followed by a change-cards PR.
Pattern harvest
Not generalizable: a feature PR.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.