Skip to content

feat(app-sdk): let an app read and wake the Bots the owner gives it - #32983

Merged
buluoray merged 1 commit into
mainfrom
crew/headless-crew/app-sdk-bot-api
Nov 15, 2026
Merged

buluoray merged 1 commit into
mainfrom
crew/headless-crew/app-sdk-bot-api

Conversation

@buluoray

@buluoray buluoray commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

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.
  • Deleting a Bot, or any other action that cannot be undone.
  • Usage reporting back to the app, a one-click pause per app, and event subscriptions.
  • Moving the routes to /v1/crew/bots.
  • Fixing the global app-token check (see the finding under Manual verification).
  • A gateway relay that lets an app's dashboard page call the Bot routes as the app, not as the owner; the SDK Bot hooks come back once it is in place (follow-up, added at the owner's request).
  • Moving the other grant families' approvals out of the app-writable approved-grants.json (follow-up; this PR moves only bots).

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.bots holds read and/or wake. bots is a staged grant family registered with explicit_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_scopes reads them there, and reads the owner's disable from member-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 in member_records.py). The list starts empty, is bound to the install, and goes when an uninstall commits. Only the owner's GET/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 in website/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 in members_access.py):

    Route Scope Returns
    GET /api/members read the ticked Bots, in the owner's order
    GET /api/members/{slug}/goals read goals and key results only
    POST /api/members/{slug}/wake (new) wake 202 {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_ref checks it is 1 to 64 characters, each one of WAKE_REF_CHARS (ASCII letters, digits, _ . : -). The gateway writes the text, and the turn runs as actor app, never as the owner. Refs wait in dashboard/mate_thread_wakes.py and 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 in credentialMasks). 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. docs/app-kit/api-reference.md has an example.

  • Also touched. website/src/api/client/apps.ts and website/src/components/appstore/types.ts carry the bots field. The MCP Servers card moves to AppDetailPageMcpServers.tsx to keep AppDetailPage.tsx under the line cap. website/src/test/ pins, docs/system-specs/modules/app-kit-platform.md and docs/feature-map/README.md are updated.

  • Differs from the Crew API draft. Bot.id is the member slug. Bot carries status and has_goal. The scope is read, not bots:chat. There is no paging. The wake route follows the draft's own POST /v1/crew/bots/{id}/wake design: the body carries only a reference.

Backwards compatibility

Compatible: an app with no permissions.bots gets exactly the old 404 and the same audit row on every member route. dispatch_hidden_turn gains an optional actor, defaulting to the old "gateway".

Reader: src/kiro_crew/apps/manifest.py:CORE_APP_ROUTE_SEGMENTS -- app -- bot-grants is 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:
    • Missing or wrong scope returns 404. An unticked Bot returns 404 on the list, goals and wake.
    • The roster row is exactly the allowlist. busy follows the live slot.
    • With both scopes, the thread, rules, briefing, activity and projections routes still return 404.
    • A wake carrying text, message or a prose ref returns 400 and never reaches the Bot. A 429 carries Retry-After.
    • The wake text is the gateway's, with actor 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.
    • An app token cannot tick Bots for itself; the owner can.
    • A set written in the app's own tree approves nothing. A set that defers to the manifest, and an install, approve no Bot scope; the owner's approval does.
    • An app that rewrites installed.json after the owner's disable holds no Bot scope.
    • A failed uninstall keeps the owner's ticks, and a finished one removes them. A reinstall reaches no Bot.
    • A save whose record would not read back answers 500 and is not shown as saved (test_a_save_that_would_not_read_back_is_refused_not_shown_as_saved).
    • A waiting worker report goes before the app wakes (test_a_waiting_worker_report_goes_before_the_app_wakes).
    • A held wake is dropped when, before it is delivered, the owner unticks the Bot or takes wake back (test_a_held_wake_is_dropped_once_the_app_loses_the_bot).
    • Each wake outcome maps to its status: 429 rate_limited and wake_queue_full, 404, 409 bot_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).
    • A wake ref is 1 to 64 allowed characters: empty, 65 characters, a space, a newline, a non-ASCII letter and a non-string are refused (test_a_wake_ref_is_one_to_64_allowed_characters, test_wake_refuses_anything_but_an_opaque_ref).
  • test/test_protected_app_state.py:
    • The one-time import carries no Bot scope over (test_the_import_carries_no_bot_scope_over).
    • An install and a first registration with a manifest that declares bots approve no Bot scope (test_an_install_and_a_first_registration_approve_no_declared_bot_scope).
    • An install and a first registration remove a ticked list that an earlier install left, and refuse when they cannot (test_an_install_removes_the_ticked_bots_an_earlier_install_left, test_a_first_registration_removes_the_ticked_bots_an_earlier_install_left).
    • An install whose later write fails leaves no app and does not bring the earlier list back (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 real token_auth_middleware lists 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.
  • Frontend: src/pages/AppDetailBotGrants.test.tsx covers the card. src/test/AppDetailPageCoverage.test.tsx checks that approving a held-back Bot scope re-reads the card.
  • Run locally on 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 in test_app_agent_readonly_dirs.py were 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

  • Installed a demo app that declares permissions.bots in a pod built from this branch. Saw both scopes marked "not approved" and the approval notice (screenshots below).
  • Not done here: a live run of an app backend calling the routes.

Screenshots / video

Right after an install and enable, before the owner approves: the notice that asks for Bot access.

Approval notice with the Bot scopes

The "Bots this app can reach" card in the same state, with both scopes marked "not approved".

Bot card with scopes not approved

The card with two demo bots ticked and saved, after approval.

Light:

Bot card, light theme

Dark:

Bot card, dark theme

A save that does not land (here the install record's installedAt is too long to store) shows the inline error under the list, and the ticks stay so the owner can save again:

Bot card, save error

On a crew with no Bots (here /api/members is stubbed to answer {"members": []}, since a real crew always lists its default member and Mate), the card says "You have no bots yet.", links to New bot (/members?create=1) and shows no Save button:

Bot card, no bots

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

  • 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

Contributed under the project's Apache-2.0 license.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 8, 2026 06:59
@buluoray
buluoray requested a review from tim-finnigan November 8, 2026 06:59
@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

UX Review (Opus 5.5) — ✅ PASS

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

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

  • Bot scopes show "not approved" in the "Bots this app can reach" card, but the only place to approve them is the reconsent notice at the top of the page. The tick boxes and "Save bot access" stay enabled anyway, so the blind reader said "I could pick bots for something that's switched off." While a scope is unapproved, put a short pointer such as "Approve above to use these bots" next to the "not approved" tag.
  • The 500 response's "Bot access was not saved" gives no reason and no next step. The reader said it "gives no reason and no next step." Change it to "Bot access was not saved. Reload the page and try again."
  • The new Bot scopes live in their own card, beside a separate card titled "Permissions" that doesn't list them. The reader asked "which of these counts as the app's permissions." List the Bot scopes in the Permissions card, or call the reconsent heading "Bot access" so it matches the card.

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

Design Review (Opus 5.5) — ✅ PASS

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

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

  • Held wakes and the rate limit are kept in memory, so a restart drops a wake that has not started. The description says so. Apps should treat 202 queued as best-effort and re-send after a restart, and docs/app-kit/api-reference.md should say this to app authors.

[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 .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 fbc972c415942910abfbaae53a3f70cc8317ad0c — 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

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 rfc-crew-api.md (bots:read, bots:wake).

Notes

  • Item 6 — one consumer, generalized: _OWNER_APPROVED_FAMILIES = (BOT_GRANT_FAMILY,) is a one-entry tuple that two sites loop over (manager_records.py:880, :1054). Subtraction: drop the tuple and test family == BOT_GRANT_FAMILY directly.
  • Item 2 — cost of existence: the description says "Moving the routes to /v1/crew/bots" is not a goal, but SDK level 9 publishes /api/members as the app-facing path. When the RFC route lands, both paths must keep working. Subtraction: none in scope. Move the routes before the preview ends so only one path ever exists.

What this change ships

Inventory (10 items) — 9 justified

Intent: let an installed app see the Bots the owner gives it and nudge one, without reading their chats or speaking as the owner — ADDITION.

  1. App manifests can declare permissions.bots with read and/or wake — justified
  2. An app token on GET /api/members gets a trimmed list of the ticked Bots — justified
  3. An app token can read a ticked Bot's goals and key results — justified
  4. New POST /api/members/{slug}/wake takes an opaque ref, and the gateway writes the text — justified
  5. New "Bots this app can reach" card on the app detail page, backed by owner-only GET/PUT bot-grants — justified
  6. An install or first registration never approves Bot scopes; the owner approves them on the app's page — one consumer, generalized
  7. Wakes are limited to 20 per 300 s per app and Bot, with at most 10 held refs; beyond that the route answers 429 — justified
  8. bot-grants becomes a reserved app route segment — justified
  9. The App SDK level goes from 8 to 9 — justified
  10. The MCP Servers card moves into its own file to stay under the line cap — justified

[FIRST-PRINCIPLES-REVIEWED] fbc972c

Description read

[DESCRIPTION-READ] dc4bb9eb3ce4865b33bdc5c85a188a2358f3b0ae9730d77525f407bca7d361f0

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 added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 8, 2026
@buluoray
buluoray force-pushed the crew/headless-crew/app-sdk-bot-api branch from 4e042f0 to 5f88cc9 Compare November 8, 2026 12:58
@buluoray

buluoray commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

Re the First Principles note on has_more, first_id/last_id, object and avatar_url (non-blocking): keeping them.

The SDK types (website/src/app-sdk/bots.ts) are written against the Crew API draft's Bot and BotList for /v1/crew/bots. The hooks are meant to move onto that route by changing only the path. Dropping these fields now would change the SDK's public types twice: once now, and again when they come back with /v1.

  • first_id / last_id are not fixed: members_app.app_bot_list fills them from the real list (the first and last ticked Bot), and null when the list is empty.
  • object is the draft's type tag ("list", "bot"), not a placeholder.
  • has_more is false because the ticked list is capped (MAX_BOT_GRANTS) and returned whole; it becomes real when paging lands.
  • avatar_url is null until the gateway serves avatars by URL.

The blocking items (second slug regex, second thread lookup, BOT_SCOPES alias) are removed in 5f88cc9.

@buluoray
buluoray force-pushed the crew/headless-crew/app-sdk-bot-api branch from 5f88cc9 to 04c1fcf Compare November 8, 2026 13:31
@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 fbc972c415942910abfbaae53a3f70cc8317ad0c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fbc972c

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

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] fbc972c

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable fbc972c415942910abfbaae53a3f70cc8317ad0c 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 Nov 8, 2026
@buluoray
buluoray force-pushed the crew/headless-crew/app-sdk-bot-api branch from 04c1fcf to 625e8e3 Compare November 8, 2026 14:56
@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 Nov 8, 2026
@buluoray
buluoray force-pushed the crew/headless-crew/app-sdk-bot-api branch from 625e8e3 to 28c3f68 Compare November 8, 2026 15:47
@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 readiness: checking Automated validation is still running labels Nov 8, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Re GPT 6.1 on 364c37e188 (a saved list that does not read back): fixed in d37efa6216. bot_grant_store.write_granted_bots refuses an installedAt longer than 64 characters and any record larger than the 64 KiB the reader accepts, and PUT /api/apps/{name}/bot-grants answers 500 bot_grants_not_saved instead of 200, so the card never shows "Saved" for a list that has no effect. Pinned by test_a_save_that_would_not_read_back_is_refused_not_shown_as_saved.

Re the Opus 5.5 note on the same head: the comment in website/src/app-sdk/sdkLevel.ts now says level 6.

@buluoray

Copy link
Copy Markdown
Contributor Author

Re GPT 6.1 on d37efa6216 (app wakes ahead of worker reports): fixed in 62e7474423. mate_thread_wakes._flush now starts an app-wake turn only when no worker report is waiting, so waiting reports go first and the held refs follow at the next turn end. A steady run of wakes can no longer hold a report back; this covers the reports from note_cron_result too, since they wait in the same store. Pinned by test_a_waiting_worker_report_goes_before_the_app_wakes.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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 permissions.bots grant family with its own consent card, a protected ticked-list record, POST /api/members/{slug}/wake, a new [App wake] injected envelope, and App SDK level 6. The PR body bases the design on the Crew API draft, and that draft is not in the repository.

Review result on b41b0ba: no blocking defect found.

  • Owner-only routes: GET/PUT /api/apps/{name}/bot-grants goes through require_owner_dashboard_request, so an app token cannot tick Bots for itself.
  • Consent: bots is explicit-only. Install, first registration and the one-time import approve none of it, and updates hold new scopes back.
  • App-token gate: it checks that the app is enabled, the scope is approved and the Bot is ticked. Every refusal returns the same 404 and is audited.
  • Wake: the gateway writes the wake text, and the body accepts only a bounded ref. Held refs are capped by count and length, and worker reports still go out first.
  • Tests: the reviewers report the PR's backend tests pass on this head, and mutating the new invariant lines turns tests red.

Done well: the app's view of a Bot is built from an explicit allowlist (_bot_row, _goals), not by trimming the owner's roster row. The wake also reuses the existing mate_thread_wakes flush instead of adding a second scheduler.

Optional:

  • mate_thread_wakes.py _flush: a held app wake is still delivered after the owner unticks the Bot, withdraws wake, or disables or uninstalls the app. Re-check app_bot_scopes and the ticked list before dispatch, or document the behaviour in app-kit-platform.md.
  • app_bot_wake.py request_wake: _load_thread runs before the queue-full and rate-limit checks, so a refused wake still reopens a Bot thread the owner closed. Run those checks first.
  • manager_records.py _freeze_declared: the explicit-only branch also stores [] for reachableByUserSessions on a legacy approveDeclared set, not only for bots. Limit it to the bots family, or record the effect with a test.

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

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.

@bolichen97

Copy link
Copy Markdown
Contributor

A short reminder on dde59b3: my one point from the request-changes on b41b0ba is still open. dashboard/handlers/members_app.py still adds

WAKE_REF_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,64}\Z")

and checks WAKE_REF_RE.match(ref). This repo doesn't take new regex in product code. A module-level frozenset of the allowed characters, with 1 <= len(ref) <= 64 and all(ch in ALLOWED for ch in ref), does the same job. Then drop the import re and update the re-export in handlers/members.py and the mention in app_bot_wake.py. All checks are green on this head; I'll re-read the full diff and review again once that line changes.

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

Thanks for this. I checked head dde59b3, and two items still need changes before this can move on.

  1. website/src/pages/AppDetailBotGrants.tsx:98 and :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=1 and 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 declares permissions.bots on a crew with no Bots, and (b) the inline error after a failed load or save. Then let the UX review run again.
  2. src/kiro_crew/dashboard/handlers/members_app.py:50: the open change request on WAKE_REF_RE still applies. The regex is unchanged on this head. It is also listed in __all__, re-exported in handlers/members.py, and named in the app_bot_wake.py docstring. 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_declared now also stores [] for reachableByUserSessions on a legacy approveDeclared set, not only for bots. 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, removes wake, 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 declares bots, so reverting that call site would not turn any test red.

@buluoray

Copy link
Copy Markdown
Contributor Author

Re @bolichen97's review (WAKE_REF_RE): changed in 75425d948c. handlers/members_app.py now has no regex and no import re. It keeps a module-level WAKE_REF_CHARS = frozenset(string.ascii_letters + string.digits + "_.:-") and WAKE_REF_MAX_CHARS = 64, and is_wake_ref(ref) accepts a ref that is a str, has 1 <= len(ref) <= 64, and has every character in that set. The wake route calls it; behaviour is the same as before.

Every site that named the regex is updated: __all__ and the re-export in handlers/members.py (now WAKE_REF_CHARS, WAKE_REF_MAX_CHARS, is_wake_ref), the wake_prompt docstring in app_bot_wake.py, and the wake row in app-kit-platform.md §32c. New tests: test_a_wake_ref_is_one_to_64_allowed_characters (1 and 64 characters accepted; empty, 65 characters, a space, a tab, a newline, a non-ASCII letter, a full-width letter, None, an int and bytes refused), plus more refused bodies in test_wake_refuses_anything_but_an_opaque_ref (65 characters, a slash, a newline, a non-ASCII letter, a number, a list).

@buluoray

Copy link
Copy Markdown
Contributor Author

Re the review on dde59b3dcb (head is now 75425d948c, rebased on main):

  1. Stills of the card. The description now has a still of this head showing the inline error after a save that does not land (the save answered 500 bot_grants_not_saved; the error sits under the list and the ticks stay). The "You have no bots yet." state could not be shown from a real crew: every crew lists its default member and Mate, and Mate comes back even when removed from config.json, so the card always has at least two rows there. AppDetailBotGrants.test.tsx renders that state (no Save button, a "New bot" link to /members?create=1). The layout of the error state looked right in the still, so no layout change.
  2. WAKE_REF_RE. Replaced with WAKE_REF_CHARS (a frozenset) plus is_wake_ref, a length and character check, at every site that named it. Details in the reply above.

Optional items:

  • SDK level. Main took level 8 for directory entries in credentialMasks, so this PR now sets level 9 in app_sdk_level.py, sdkLevel.ts, api-reference.md and §32c, and the description says level 9.
  • _freeze_declared and reachableByUserSessions. On this rebased head the explicit-only freeze in _freeze_declared is main's code (693e3be1125, feat(app-kit): let desktop windows use declared shell capabilities #36349), not this PR's; this PR only adds a comment there. So nothing to narrow here.
  • A held wake after the grant goes. Now checked again at delivery: before mate_thread_wakes._flush starts a held app wake it calls app_bot_wake.still_granted, which keeps only apps that still hold wake and still have the Bot ticked (a disabled or uninstalled app reads as neither). Refs from any other app are dropped. Pinned by test_a_held_wake_is_dropped_once_the_app_loses_the_bot (untick, and wake taken back); it fails if the re-check is removed.
  • manager_install.py call site. test_an_install_and_a_first_registration_approve_no_declared_bot_scope installs a manifest that declares bots, and registers one, and checks that neither approves a Bot scope. It fails if install goes back to _declared_grant_entries.

@buluoray

Copy link
Copy Markdown
Contributor Author

Re GPT 6.1 and Opus 5.5 on 75425d948c (a wake that arrives during the grant check is lost or dropped): fixed in 0d6160ba0e. mate_thread_wakes._flush now hands still_granted a copy of the held refs, not the live entry. After the read it removes only the refs in that copy (_take_app_refs), so a wake that arrived meanwhile stays held and is checked on the next pass; if the Bot turned busy, the granted refs go back ahead of any new ones (_put_back_app_refs). Pinned by test_a_wake_that_arrives_during_the_grant_check_is_kept_and_delivered, which adds a second app's wake while the check runs and expects both delivered; it fails if the copy is removed.

@buluoray

Copy link
Copy Markdown
Contributor Author
  • fixed span=57afa941e2e8 -- Re GPT 6.1 on 0d6160ba0e (an app wake can start on a thread that began closing during the grant read): fixed in b522d42850. After still_granted returns, the app-wake branch now checks the same fence the worker-report turn uses (same slot, still a crewmate thread, not is_closing) and returns before it takes any ref, so nothing starts on a closing thread and the refs stay held. Pinned by test_a_thread_that_starts_closing_during_the_grant_check_gets_no_wake, which marks the thread closing during the read and expects no turn and the ref still held; it fails if the is_closing check is removed.

@buluoray

Copy link
Copy Markdown
Contributor Author

Where each open change request stands on the current head, e1dd0f8fb2 (the fix commits named in the earlier replies were rebased into it):

All checks pass on this head (83 pass, 0 fail) and every review lane passes. A re-review is requested.

bolichen97
bolichen97 previously approved these changes Nov 15, 2026

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

Thanks for the updates. I checked head e1dd0f8, and one item still needs a change.

  1. website/src/pages/AppDetailBotGrants.tsx:65, :98-103 and :126: the UX review on this head says it "cannot evaluate: missing the no-Bots empty state". When noBots is true, the card shows "You have no bots yet.", adds a "New bot" link to /members?create=1 and 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 because default is 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/members that returns {"members": []}, then let the UX review run again; or (b) remove the noBots branch 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, and is_wake_ref checks 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 in app_sdk_level.py, sdkLevel.ts and 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 parametrize test_wake_past_the_limit_is_429 over those outcomes.
  • dashboard/app_bot_wake.py:117: _load_thread runs 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.

@buluoray

Copy link
Copy Markdown
Contributor Author

Re the KiroCrewCaptain review on e1dd0f8fb2 (head is now 63f03a2a7e):

  1. No-Bots still (option a). The description now has a still of this head rendered in a pod with /api/members stubbed to answer {"members": []}. The card shows "You have no bots yet." and the "New bot" link to /members?create=1, with no Save button. The capture script also checked that no "Save bot access" button exists and that the link points to /members?create=1. The layout looked right, so no change.

Optional items, all in 63f03a2a7e:

  • Route mapping. test_each_wake_outcome_maps_to_its_status covers rate_limited and wake_queue_full (429 with Retry-After), NO_BOT (404), NO_THREAD (409 bot_unavailable), and started and queued (202).
  • _load_thread before the rate limit. request_wake now asks create_rate_limit.has_create_budget (read-only) before it loads a closed thread, so a wake that the budget refuses reopens nothing. Pinned by test_a_wake_past_the_budget_never_reopens_a_closed_thread; it fails if the check is removed.
  • Level 9 shared with feat(app-kit): tool gate honours installed apps' credential masks #37459 and feat(app-kit): let an app page open the person's chat it declares #37492. Agreed: whichever PR lands second renumbers the level in app_sdk_level.py, sdkLevel.ts and the docs. If this one lands second, I will renumber it on the rebase.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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:

  • bots is an explicit-only grant family. Install, first registration and the one-time import approve none of it, and an update holds a new scope back.
  • The owner's ticked list sits in a gateway-only record that is bound to installedAt. The owner-only route refuses an app token.
  • Every app-token miss goes through _app_bot_gate and gets the same audited 404.
  • The wake body takes only a bounded ref, and the gateway writes all the text the Bot reads. The flush re-checks the grant before delivery.

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:

  • dashboard/handlers/members_roster.py:344 and member_goals.py:190: once feat(memory): let an app manage Crew's memory with the owner's consent #37498 also lands, these early app branches skip its memory-admin bypass. The memory app's Bot picker would then get a 404 or the trimmed Bot shape. Whichever PR lands second should send a memory-admin request down the owner path, with a test, and the merge-order note should name feat(memory): let an app manage Crew's memory with the owner's consent #37498.
  • docs/app-kit/api-reference.md:147: the Bots section does not say that a queued wake and the rate budget live in memory and are lost when the gateway restarts. It also leaves out the 409 bot_unavailable answer.
  • The body and the members_app.py docstring say the Crew API draft has no wake route and no Bot status. The draft on main has both: POST /v1/crew/bots/{id}/wake with bots:wake, and a required status of idle or working. Correcting this helps whoever decides the design.

@buluoray

buluoray commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

Re First Principles on a0b9d7ffde:

  • Note (wake route vs the draft): right, and fixed in the description (no push). The line now says the wake route follows the draft's own POST /v1/crew/bots/{id}/wake design, whose body carries only a reference.
  • Blocker (public Bot seam with no consumer): not changed in code. Whether to ship the app-token Bot routes and level 9 before a named app calls them, or hold them until one does, is a product decision for a maintainer. It is not something a fix in this PR can settle, so this lane stays blocked until a maintainer records that decision.

@buluoray

Copy link
Copy Markdown
Contributor Author

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.

@buluoray

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles a0b9d7f owner-decision: Ship before a named app calls these routes; decision recorded at #32983 (comment)

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@buluoray recorded a owner-decision release (class owner-decision) for the first-principles AI finding on a0b9d7ffde3b7f38cacc5df7200a6273a0efa090.

Ship before a named app calls these routes; decision recorded at #32983 (comment)

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

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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:

  • bots is an explicit-only grant family. Install and first registration approve an empty list, and an update keeps only scopes the owner already approved.
  • The ticked-Bot record lives in the protected member records and is bound to installedAt.
  • /api/apps/{name}/bot-grants is owner-only.
  • Every app-token branch goes through one gate. That gate returns the same audited 404 on every miss, and an app with no bots scope behaves exactly as it does on main.
  • The wake body accepts only a validated ref, and the gateway writes all the prompt text.
  • At delivery, the flush re-checks the grant off the loop, keeps wakes that arrive during that read, and sends worker reports first. Race tests pin each of these.

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:

  • The spec and the members_app.py docstring say only the paths change when these routes move to the accepted Crew API. The contract also differs in four places: busy vs working, the ref charset (. and :), the wake response shape, and the rate (20 per 5 minutes vs 20 per hour). Either align the cheap parts or list each difference.
  • Open feat(memory): let an app manage Crew's memory with the owner's consent #37498 adds a memory-admin bypass to _deny_app_caller. The early app branch in member_goals.py would send that request to a 404. Whichever PR lands second should route memory-admin down the owner path and add a test. A merge-order note would help.
  • docs/app-kit/api-reference.md does not list the 409 bot_unavailable and 400 answers. It also does not say that a queued wake and the rate budget are lost on a gateway restart. One sentence on each would close the earlier note.

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

Approving fbc972c415.

  • My earlier blocking point is fixed: the wake ref check is now is_wake_ref with a frozenset of allowed characters and a 64-character cap, and there is no new regex in product code.
  • New since my last read: request_wake now asks the read-only has_create_budget before it loads the thread, so a wake the budget refuses never reopens a closed thread. The real allow_create still 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-core moved 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

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.

3 participants