Skip to content

feat: let any crewmate guide users to the control on their screen - #18443

Merged
buluoray merged 1 commit into
mainfrom
feat/guide-tours
Oct 10, 2026
Merged

buluoray merged 1 commit into
mainfrom
feat/guide-tours

Conversation

@buluoray

@buluoray buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

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

  • Changing anything for the user. A guide only highlights and explains; every click is the user's, and prepared changes are the next PR.
  • A path around approvals, governance or the security policy. Trust-root controls (security policy, approvals, the approval-mode picker, a crewmate's permission picker, computer use, secrets) get no guide and are answered in words.
  • Letting the model drive the page or send a route, selector or markup.
  • Changing where a new user lands on first open.

What changed (motivation → approach → change)

Approach: extend the kirocrew-guide server 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.

  • Tools (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's next line. All seven tools are exact allowedTools grants (agent._GUIDE_AUTO_GRANTS, config/defaults.json), through the governance ceiling.
  • Location index (ui_index.py, website/scripts/gen-ui-index.mjs, website/src/uiLocations): curated plus auto-stamped controls in 12 languages, generated into src/kiro_crew/docs/ui-index.generated.json and guidePlans.gen.ts; CI checks it is current. GUIDE_DENY_IDS marks the approval-mode picker and a crewmate's permission picker deny.
  • Guide runs (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.
  • 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 a card row of the conversation (dashboard/chat_cards.py, cards/ConversationCard.tsx) and a guide/* crew-log entry, so it stays where it was offered across a reload.
  • Crewmates page (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.py and history_projection.py add the guide/* entries and the display-only card role; chat_runner.py reads past a card row; security_posture.py lists the guide-row redaction sink and the gate-side catalog; validation.py holds the argument schemas; dashboard/server.py, server_runtime/mcp_routes.py, dashboard/state.py, chat_handlers.py, ws_event_scope.py and agent_admin/crew_records.py wire the routes, the sending tab and the crewmate-create hook; src/kiro_crew/apps and website/src/apps mark delete buttons guideCaution; 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.tsx and vite-env.d.ts carry the markers and wiring; src/kiro_crew/agent.py and src/kiro_crew/agent_materialization (service agents) grant the new tools and keep them off background agents; website/src/i18n holds the strings; .github, .gitignore and src/kiro_crew/builtin_skills run the index check; src/kiro_crew/docs and docs/ cover MCP, crew log, crew mode, history, config and the feature map; test/gui_user adds 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

  • Backend: 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.
  • Frontend: 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.
  • Mutation checks from the earlier rounds still hold: removing the channel-origin or not_user_turn check, the trust-root route check or a GUIDE_DENY_IDS entry reddens a named test.
  • Test volume: the change-card tests moved to the next PR, and the overlapping admission and server tests were merged into one file each.

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.py reorder 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.

a-guide-card

b-guide-outline-popover

c-multistep-1-select-row

c-multistep-2-delete-step

e-phone-guide-card

e-phone-guide-step

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

  • 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 9, 2026 10:31
@buluoray
buluoray requested review from chenmingwei23 and removed request for a team October 9, 2026 10:31
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • @buluoray posted a complete reasoning template for e64c4bf.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of e64c4bf110a157057a399bc9bbe9a1dbc9693ff8 — 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/CONCERNS are advisory.

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

  • Item 6 — unjustified move, oversized: The Crewmates "+" now opens a menu: "New crewmate" opens the embedded MeetCrewmatesFlow in place of the chat, and the old dialog drops to "Advanced". In that flow the schedule defaults to embedded ? 'ask' : 'morning', and a receipt card is kept in sessionStorage. The Goal's "Not a goal: Changing anything for the user" names nobody who was failing to find the create control.
    Subtraction: keep NewCrewmateDialog as the "+" target and give crewmate.create a prefill on it; delete the embedded path, the Advanced menu row, CREATED_RECEIPTS_KEY and its receipt card.
    Clears when: a report of users failing at the old create path is linked, or the move is removed.
  • Item 7 — duplicate of guide_catalog.ACTION_CREWMATE_CREATE: the onClickCapture handler in MembersPage.tsx uses createDraftFromHref (1 consumer, from grepping createDraftFromHref) to turn any assistant-written /members?create=1&name=&goal= link into a draft. That skips the offer/Start step and _validate_crewmate_create. It also contradicts "Not a goal: Letting the model … send a route".
    Subtraction: delete createDraftFromHref and the click-capture handler; keep the ?create=1 hand-off only for guideActions.ts.
    Clears when: the link intercept is removed.

What this change ships

Inventory (8 items) — 6 justified

Intent: let any crewmate show users where a Kiro Crew control is on their own screen. This is an ADDITION, covered by rfc-crewmate-guides-and-mate.md (accepted).

  1. Crewmates gain find_ui/search_docs/guide_* tools, granted by default — justified
  2. A guide offer row appears in chat; Start walks a pill/arrow over the real control — justified
  3. The packaged UI-location index is generated from dashboard source, with a CI freshness check — justified
  4. Guide markers are stripped from rendered messages — justified
  5. Guide lifecycle entries are added to the crew log — justified
  6. Crewmate creation moves inline with a new "+" menu and an on-demand schedule default — unjustified move
  7. An assistant chat link opens a prefilled crewmate draft — duplicate of crewmate.create
  8. Meet CrewMates auto-open now belongs to the first-run host only — justified

[FIRST-PRINCIPLES-REVIEWED] e64c4bf

Description read

[DESCRIPTION-READ] efff6342fa0c901606b14f8bbbe3f4cb93698dad06c3e6993592802d9d9aa046

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ human override accepted

Human judgment by @buluoray overrides the GPT 6.1 finding for e64c4bf110a157057a399bc9bbe9a1dbc9693ff8; the recorded reason is authoritative for this commit.

[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:
/ai-review override gpt e64c4bf110a157057a399bc9bbe9a1dbc9693ff8: <one-sentence reason>

@buluoray
buluoray force-pushed the feat/mate-first-crewmate branch from 6dd9d77 to ab68b31 Compare October 9, 2026 10:43
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 9, 2026
@buluoray
buluoray force-pushed the feat/mate-first-crewmate branch from ab68b31 to 2fdd164 Compare October 9, 2026 10:59
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 9, 2026
@buluoray
buluoray force-pushed the feat/mate-first-crewmate branch from 2fdd164 to 915d831 Compare October 9, 2026 11:56
@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 9, 2026
@buluoray
buluoray force-pushed the feat/mate-first-crewmate branch from 915d831 to 4518263 Compare October 9, 2026 12:27
@buluoray
buluoray force-pushed the feat/mate-first-crewmate branch from 4518263 to 79b7e18 Compare October 9, 2026 12:56
@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 9, 2026
@buluoray
buluoray force-pushed the feat/mate-first-crewmate branch from 79b7e18 to 7d3595a Compare October 9, 2026 13:24
@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@buluoray marked the design AI finding as false positive, not applicable, or explicitly accepted for e64c4bf110a157057a399bc9bbe9a1dbc9693ff8.

The lane failed closed because the diff exceeds 1 MB (mostly the generated UI index); the owner reviewed the design on preview gateways.

This decision applies only to this commit. A new push requires a new judgment.

@buluoray

Copy link
Copy Markdown
Contributor Author

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

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@buluoray marked the ux AI finding as false positive, not applicable, or explicitly accepted for e64c4bf110a157057a399bc9bbe9a1dbc9693ff8.

The lane failed closed because the diff exceeds 1 MB (mostly the generated UI index); the owner reviewed the UX on preview gateways.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ human override accepted

@buluoray overrode this lane for e64c4bf110a157057a399bc9bbe9a1dbc9693ff8 via /ai-review override (this commit only).

@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ human override accepted

@buluoray overrode this lane for e64c4bf110a157057a399bc9bbe9a1dbc9693ff8 via /ai-review override (this commit only).

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

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 guideCaution markers across website/src/apps and src/kiro_crew/apps.

Suggested split:

  • (a) The generator, the committed index, the read-only find_ui / search_docs tools 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 the guide/* crew-log entries.
  • (c) The Crewmates page flow plus the crewmate.create commit 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.start additionally 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.create commit step completes only from the gateway's own successful POST /api/agents response, never from the tab's word. A failed save calls abort_commit and 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-root regions, catalog keys in any language), not from the agent's words. The English-only CEILING_LABEL_RE is 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, and clean_find_report keeps page text in the tab.
  • Docs lookup. search_docs looks up a page by name from the directory listing, so a caller string never becomes a path.
  • Card rows. card is in DISPLAY_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.

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.

Let any crewmate guide users to a control and propose changes as cards

4 participants