Repository navigation
feat(app-sdk): let an app read and wake the Bots the owner gives it - #32983
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks: the screenshots show every new control and state, and the blind reader understood the approve button, the Bot tick boxes and the save button correctly and would use them. Notes
[UX-REVIEWED] fbc972c Description read[DESCRIPTION-READ] c8a4bbf44db5bc6cec17a874d45c273dcf4b58d4ad5428018cc47df63d5a574f That sha256 names everything this verdict read: the PR description, plus the 9 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 |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: app access to a Bot requires a scope the owner approved and a Bot the owner ticked, both stored outside the app's tree, and the wake text is written by the gateway. Notes
[DESIGN-REVIEWED] fbc972c Description read[DESCRIPTION-READ] 7e8b18249c6ddda7d2f31eab8030a6960ccce19c8e346fec9ef31f9f67d8e8f9 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every item removes a named harm (an app token gets a 404 on every member route today), it reuses the existing wake, rate-limit and grant plumbing, and the shape is in the accepted Notes
What this change shipsInventory (10 items) — 9 justifiedIntent: let an installed app see the Bots the owner gives it and nudge one, without reading their chats or speaking as the owner — ADDITION.
[FIRST-PRINCIPLES-REVIEWED] fbc972c Description read[DESCRIPTION-READ] dc4bb9eb3ce4865b33bdc5c85a188a2358f3b0ae9730d77525f407bca7d361f0 That sha256 names the PR description this verdict read. Recompute it with |
4e042f0 to
5f88cc9
Compare
|
Re the First Principles note on The SDK types (
The blocking items (second slug regex, second thread lookup, |
5f88cc9 to
04c1fcf
Compare
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 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: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
04c1fcf to
625e8e3
Compare
625e8e3 to
28c3f68
Compare
|
Re GPT 6.1 on Re the Opus 5.5 note on the same head: the comment in |
|
Re GPT 6.1 on |
|
This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. This PR gives third-party apps a new kind of reach into the owner's Bots. It adds a Review result on b41b0ba: no blocking defect found.
Done well: the app's view of a Bot is built from an explicit allowlist ( Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
I read the whole product diff, the app-side access rules in particular. The access design looks right to me: an app needs a declared and owner-approved bots scope AND a Bot the owner ticked, both start empty and are kept in a gateway-only record, the owner-only route refuses an app token, every refusal is the same 404, and the wake text is written by the gateway from a validated ref. One blocking point, on a single line.
New regex in product code. dashboard/handlers/members_app.py adds WAKE_REF_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,64}\Z") and checks the wake ref with WAKE_REF_RE.match(ref). This repository does not accept new regex in product code. (APP_NAME_RE in bot_grant_store.py is an existing pattern reused from apps.execution, so that one is fine.)
A plain check does the same job. For example, keep a module-level frozenset of the allowed characters (ASCII letters, digits and _ . : -), and accept a ref that is a string, has 1 <= len(ref) <= 64, and whose every character is in that set. Then update the places that name WAKE_REF_RE (the re-export in handlers/members.py and the mention in app_bot_wake.py, plus any docs or tests), and drop the import re in the new file if nothing else uses it.
Everything else I read is fine, and I will approve once this is changed.
|
A short reminder on dde59b3: my one point from the request-changes on b41b0ba is still open.
and checks |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Thanks for this. I checked head dde59b3, and two items still need changes before this can move on.
website/src/pages/AppDetailBotGrants.tsx:98and:117: the UX review on this head could not evaluate the new card. If a crew has no Bots, the card shows "You have no bots yet." with a link to/members?create=1and no Save button. If a load or save fails, it shows the inline ErrorNotice. The PR body has four screenshots, and none of them shows either state, so these controls would merge without anyone having seen them rendered. Smallest fix: attach stills of this head showing (a) the card for an app that declarespermissions.botson a crew with no Bots, and (b) the inline error after a failed load or save. Then let the UX review run again.src/kiro_crew/dashboard/handlers/members_app.py:50: the open change request onWAKE_REF_REstill applies. The regex is unchanged on this head. It is also listed in__all__, re-exported inhandlers/members.py, and named in theapp_bot_wake.pydocstring. Smallest fix: replace it with a frozenset of allowed characters plus a length check at every one of those sites. If you think the regex should stay, reply on the review and say why.
This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here.
Optional:
src/kiro_crew/apps/manager_records.py:947:_freeze_declarednow also stores[]forreachableByUserSessionson a legacyapproveDeclaredset, not only forbots. You could narrow the condition to the Bot families, or say so under Backwards compatibility and add a test for it. The body also says "SDK level 6", but the diff sets level 8.src/kiro_crew/dashboard/mate_thread_wakes.py:454: a wake held for a busy Bot is still delivered after the owner unticks the Bot, removeswake, or disables or uninstalls the app. You could check the grant again at flush time, or document this behaviour.src/kiro_crew/apps/manager_install.py:478: no test runs install or first registration with a manifest that declaresbots, so reverting that call site would not turn any test red.
|
Re @bolichen97's review ( Every site that named the regex is updated: |
|
Re the review on
Optional items:
|
|
Re GPT 6.1 and Opus 5.5 on |
|
|
Where each open change request stands on the current head,
All checks pass on this head (83 pass, 0 fail) and every review lane passes. A re-review is requested. |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Thanks for the updates. I checked head e1dd0f8, and one item still needs a change.
website/src/pages/AppDetailBotGrants.tsx:65,:98-103and:126: the UX review on this head says it "cannot evaluate: missing the no-Bots empty state". WhennoBotsis true, the card shows "You have no bots yet.", adds a "New bot" link to/members?create=1and hides Save. None of the five stills in the body shows that state, so the control would merge without anyone having seen it rendered. You say a real crew cannot reach this state becausedefaultis always listed. If that is right, these lines are a branch no user can see. Smallest fix, pick one: (a) attach a still of this head rendered against a stubbed/api/membersthat returns{"members": []}, then let the UX review run again; or (b) remove thenoBotsbranch and its strings, and say so in the body.
Status of my earlier review on dde59b3:
- Item 1(b), the error state still: fixed. The save-error still is in the body.
- Item 1(a), the no-Bots still: still stands (item 1 above).
- Item 2,
WAKE_REF_RE: fixed. No regex remains, andis_wake_refchecks the length and the characters against a frozenset, with edge-case tests.
This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here.
Optional:
dashboard/apps/app_sdk_level.py:7: open PRs #37459 and #37492 also set level 9. Agree a merge order. The PR that lands second renumbers the level inapp_sdk_level.py,sdkLevel.tsand the docs.dashboard/handlers/members_app.py:243: no route-level test covers the QUEUE_FULL 429, NO_BOT 404 or NO_THREAD 409 mapping. You could parametrizetest_wake_past_the_limit_is_429over those outcomes.dashboard/app_bot_wake.py:117:_load_threadruns before the rate-limit check, so a wake refused with 429 can still reopen a thread the owner closed. You could check the budget first with a read-only call.
|
Re the KiroCrewCaptain review on
Optional items, all in
|
|
This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. Review result on 63f03a2: no blocking finding. The review checked these points on this head:
Done well: the race tests inject a close or a second wake from inside the off-loop grant read. They then check both the refused state and the delivered state. Status of my earlier review on e1dd0f8:
Optional:
|
|
Re First Principles on
|
|
Maintainer decision: ship the app-token Bot routes and SDK level 9 now. The planned consumer is the Bot Team use case (an app wakes a Bot, and the Bot acts through the app's tools). The routes are additive, off by default, and reach only Bots the owner has ticked for that app. |
|
/ai-review override first-principles a0b9d7f owner-decision: Ship before a named app calls these routes; decision recorded at #32983 (comment) |
Human judgment recorded@buluoray recorded a owner-decision release (class
This decision applies only to this commit. A new push requires a new judgment. |
|
A maintainer decision to ship this design is recorded on this PR. The author posted it, so the PR now waits for an approval from a maintainer. Review result on a0b9d7f: no blocking finding. The review checked these points on this head:
One thing done well: the app's view of a Bot is built from the app's own allowlist, not by trimming the owner's roster row. Optional:
|
An installed app could not see or reach any of the owner's Bots: every
Crew Members route answers an app token with a 404. Apps that work
beside the crew need a narrow, owner-controlled door.
Add permissions.bots with two scopes, read and wake, as a staged grant
family registered explicit-only, plus a per-app list of Bots the owner
ticks on the app detail page (PUT /api/apps/{name}/bot-grants, owner
only). The approved scopes are the bots family of the app's approved
set in the shared protected store; declaring them is never enough. An
install or first registration approves none, a set that defers to the
manifest approves none, and the owner approves each scope on the app's
page. The ticked list lives in member-records/app-bot-grants/, bound
to the install and removed on uninstall.
With read, GET /api/members and GET /api/members/{slug}/goals return a
trimmed list and goals of the ticked Bots, never their threads,
briefings or rules. With wake, POST /api/members/{slug}/wake takes only
an opaque ref and queues one fixed reminder through mate_thread_wakes,
rate limited per app and Bot and refused with 429 when the queue is
full. A Bot the owner did not tick answers 404.
APP_SDK_LEVEL is 9: an app may declare permissions.bots and call these
routes from its backend with its own token. The dashboard SDK gets no
Bot hooks yet. The MCP Servers card moves out of AppDetailPage.tsx to
keep the page under the line cap.
Co-authored-by: Kyle Seaman <2904635+kyleseaman@users.noreply.github.com>
bolichen97
left a comment
There was a problem hiding this comment.
Approving fbc972c415.
- My earlier blocking point is fixed: the wake
refcheck is nowis_wake_refwith afrozensetof allowed characters and a 64-character cap, and there is no new regex in product code. - New since my last read:
request_wakenow asks the read-onlyhas_create_budgetbefore it loads the thread, so a wake the budget refuses never reopens a closed thread. The realallow_createstill decides later, and the test pins that nothing is loaded on a refused wake. The status mapping test now covers every outcome. - Ran the 8 touched test files locally: 162 passed.
- The one red check, Render Benchmark (counter budgets), is not this PR:
kirocrew-linux-4-coremoved to ubuntu-26.04 and Playwright 1.58.2 refuses to install Chromium there. #37653 fixes that step.
AI-assisted, sent by Bolin Review bot
Problem / Motivation
Goal: An installed app can list the Bots the owner gives it, read their goals and progress, and wake one with a fixed note, without ever reading a Bot's chats or speaking as the owner.
Today every Crew Members route answers an app token with a 404 (
_deny_app_caller), so an app has no way to see a Bot or tell it that something arrived. An app that works beside the crew (a notes app, a team board, a chat bridge) has to ask the owner to copy things over by hand.Why it matters
The App SDK is how third-party surfaces use the owner's Kiro Crew. Without a narrow Bot door, each such app either does without the Bots or asks for wide grants (
sessionApproval+memberThreads) that let it type into a Bot's thread as if it were the owner. This PR gives apps the smallest useful reach: see the Bots the owner picked, and wake one. The message itself stays data the Bot reads through the app's own tools.Not a goal
tools.provide(an app offering tools to a Bot, with the gateway telling the app which Bot is calling).bots:create(creating or importing a Bot). It is a restricted scope and needs its own design./v1/crew/bots.approved-grants.json(follow-up; this PR moves onlybots).What changed (motivation → approach → change)
An app reaches a Bot only when its manifest declares a scope, the owner approved that scope, the app is enabled, and the owner ticked that Bot. Every miss is the same 404, so an app cannot tell a Bot it was not given from one that does not exist.
Scopes are explicit-only.
permissions.botsholdsreadand/orwake.botsis a staged grant family registered withexplicit_only=True(apps/point_grants.py,apps/manifest_sections.py). Declaring a scope is never enough: an install or a first registration approves none, and a stored set that defers to the manifest approves none (apps/manager_records.py).Approved scopes live in the shared protected grants store,
member-records/app-grants/<app>.json, with every other family.apps/bot_grants.app_bot_scopesreads them there, and reads the owner's disable frommember-records/app-disabled/. Nothing in the app's own tree is read.Ticked Bots live in
member-records/app-bot-grants/<app>.json(apps/bot_grant_store.py, a new kind inmember_records.py). The list starts empty, is bound to the install, and goes when an uninstall commits. Only the owner'sGET/PUT /api/apps/{name}/bot-grants(apps/routes_bot_grants.py) reads or writes it.What the owner sees. The app detail page gets a "Bots this app can reach" card (
website/src/pages/AppDetailBotGrants.tsx, strings inwebsite/src/i18n/locales/*.json). After an install each scope reads "not approved", and a notice asks the owner to approve Bot access. Then the owner ticks Bots and saves.Routes opened to apps (
dashboard/handlers/members_app.py; the gate is inmembers_access.py):GET /api/membersreadGET /api/members/{slug}/goalsreadPOST /api/members/{slug}/wake(new)wake{status: started | queued}Every other member route still refuses app tokens.
Wake (
dashboard/app_bot_wake.py). The body is{"ref": "<id>"}and nothing else;is_wake_refchecks it is 1 to 64 characters, each one ofWAKE_REF_CHARS(ASCII letters, digits,_ . : -). The gateway writes the text, and the turn runs as actorapp, never as the owner. Refs wait indashboard/mate_thread_wakes.pyand arrive in one turn. The limits are proposals: 20 wakes per 300 s per app and Bot (create_rate_limit.py) and 10 held refs, then 429.SDK level 9 (
apps/app_sdk_level.py,website/src/app-sdk/sdkLevel.ts; level 8 is main's directory entries incredentialMasks). An app may declarepermissions.botsand call these routes from its backend with its own token. The dashboard SDK gets no Bot hooks yet.docs/app-kit/api-reference.mdhas an example.Also touched.
website/src/api/client/apps.tsandwebsite/src/components/appstore/types.tscarry thebotsfield. The MCP Servers card moves toAppDetailPageMcpServers.tsxto keepAppDetailPage.tsxunder the line cap.website/src/test/pins,docs/system-specs/modules/app-kit-platform.mdanddocs/feature-map/README.mdare updated.Differs from the Crew API draft.
Bot.idis the member slug.Botcarriesstatusandhas_goal. The scope isread, notbots:chat. There is no paging. The wake route follows the draft's ownPOST /v1/crew/bots/{id}/wakedesign: the body carries only a reference.Backwards compatibility
Compatible: an app with no
permissions.botsgets exactly the old 404 and the same audit row on every member route.dispatch_hidden_turngains an optionalactor, defaulting to the old"gateway".Reader: src/kiro_crew/apps/manifest.py:CORE_APP_ROUTE_SEGMENTS -- app --
bot-grantsis now a reserved segment, so an app endpoint by that name is refused at install; no shipped app declares one (test_file_menu_items.py scans the route sources)Reader: website/src/apps/coreAppRoutes.ts:CORE_APP_ROUTE_SEGMENTS -- app -- mirror of the same set, same reason
Tests
test/test_app_bot_access.py:busyfollows the live slot.text,messageor a prose ref returns 400 and never reaches the Bot. A 429 carriesRetry-After.app. A busy Bot gets one turn for all refs at its next turn end. A full set of held refs refuses a new ref and keeps the old ones.installed.jsonafter the owner's disable holds no Bot scope.test_a_save_that_would_not_read_back_is_refused_not_shown_as_saved).test_a_waiting_worker_report_goes_before_the_app_wakes).wakeback (test_a_held_wake_is_dropped_once_the_app_loses_the_bot).rate_limitedandwake_queue_full, 404, 409bot_unavailable, 202 (test_each_wake_outcome_maps_to_its_status). A wake past the budget never reopens a closed thread (test_a_wake_past_the_budget_never_reopens_a_closed_thread).test_a_wake_ref_is_one_to_64_allowed_characters,test_wake_refuses_anything_but_an_opaque_ref).test/test_protected_app_state.py:test_the_import_carries_no_bot_scope_over).botsapprove no Bot scope (test_an_install_and_a_first_registration_approve_no_declared_bot_scope).test_an_install_removes_the_ticked_bots_an_earlier_install_left,test_a_first_registration_removes_the_ticked_bots_an_earlier_install_left).test_a_failed_install_write_leaves_no_app_and_no_earlier_ticked_bots).test/test_app_bot_disabled_token.py: a real app token through the realtoken_auth_middlewarelists and wakes, then the app is disabled and the same token gets 404 on both.test/test_app_bot_grant_routes.py: the owner route's reads, writes and refusals.src/pages/AppDetailBotGrants.test.tsxcovers the card.src/test/AppDetailPageCoverage.test.tsxchecks that approving a held-back Bot scope re-reads the card.75425d948c: the 124 backend test files that install or register apps, reach the wake flush or the Bot routes, with the Bot, grant, facade and SDK level tests (4196 passed, 7 skipped; 4 real-sandbox tests intest_app_agent_readonly_dirs.pywere left out because they fail the same way on plain main on this host); the 19 frontend test files for the app detail page and the SDK (174 passed);tsc, mypy, flake8, the black gate, docs-lint, the line cap and the flake-pattern ratchet.Proof: not provable -- other: this is a feature PR, so there is no fix hunk to revert
Manual verification
permissions.botsin a pod built from this branch. Saw both scopes marked "not approved" and the approval notice (screenshots below).Screenshots / video
Right after an install and enable, before the owner approves: the notice that asks for Bot access.
The "Bots this app can reach" card in the same state, with both scopes marked "not approved".
The card with two demo bots ticked and saved, after approval.
Light:
Dark:
A save that does not land (here the install record's
installedAtis too long to store) shows the inline error under the list, and the ticks stay so the owner can save again:On a crew with no Bots (here
/api/membersis stubbed to answer{"members": []}, since a real crew always lists itsdefaultmember and Mate), the card says "You have no bots yet.", links to New bot (/members?create=1) and shows no Save button:A narrow-width shot is not attached: the capture browser has a fixed 1280 px viewport. The card is a single column of checkboxes inside the page's existing card grid.
Related Issues
N/A
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.