Repository navigation
feat(app-kit): let an app page open the person's chat it declares - #37492
Conversation
|
Decisions taken for this seam (campaign #26967, under the owner ruling in comment 6841699202):
|
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: a declared, gateway-checked create is a narrow seam that keeps the built-in's create unchanged, the disclosure has rendered evidence, and nothing is taken away. Notes
[DESIGN-REVIEWED] 18ed2be Description read[DESCRIPTION-READ] 58b32510d4d8811d28e7562c7ac8000e5811bc4510e1f81b3533ccecbe12a8b6 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 The seam fills a gap that blocks Code Review Sage's adoption. Two items are wider than the Goal needs, but both can be undone later. Notes
What this change shipsInventory (7 items) — 5 justifiedIntent: let an adopted app's page open the person's named follow-up chat without a broad
[FIRST-PRINCIPLES-REVIEWED] 18ed2be Description read[DESCRIPTION-READ] c4a0b689905bf1ce18d022b9478749c4174962832232ad6cf5c420ba6b68d799 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)UX-level review of UX-Verdict: PASS cannot evaluate: missing the second line of the chat box ("Chat keys start with sage-followup-. Memory: persistent."). The diff renders it on the trust prompt and on the detail page, but none of the four screenshots shows it. Evidence gaps
Notes
[UX-REVIEWED] 18ed2be Description read[DESCRIPTION-READ] ef3937b409bb56777ba299a3df2acdfb784dac0f51a33d536014f9c4c7135a52 That sha256 names everything this verdict read: the PR description, plus the 7 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 |
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: |
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: |
2e22649 to
2448ffc
Compare
|
|
|
|
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 14% chance that this change introduces a defect, above the 12% limit for approving on its own. Approve. The PR adds a narrow, declared seam ( I checked the regression risk to Sage's built-in follow-up:
An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
2448ffc to
74afc4d
Compare
|
CI reds on 2448ffc, all handled in 74afc4d (rebased onto 4c530d0):
|
74afc4d to
7bf4de0
Compare
27f9a5b to
cb85c2a
Compare
cb85c2a to
8aabeef
Compare
Code Review Sage's review panel opens a follow-up chat with the reviewer (its agent, a title, the Sage Review folder, persistent memory) through the dashboard's POST /api/chat/slots. An adopted copy reaches the host only through its scoped client, and declaring /api/chat/slots would hand its page every slot route, which adoption refuses as a widening. Owner ruling on #26967 (comment 6841699202) asks for an app chat slot seam instead. permissions.chatLaunch declares the one shape of chat a page opens: a key prefix (never a core one), the agents, an optional folder and the memory modes. useChatLauncher().createChat sends the ordinary create through the host with app_launch naming the app, and the create handler holds it to the declaration first: a person's request, an enabled app whose prefix no other installed app overlaps, only the launch fields, a key under the prefix, a declared agent, memory mode and folder, and no app-owned or non-chat slot or transcript another app owns or opened. Every refusal is one audited 403 that creates nothing; what passes is the ordinary create, so the chat stays the person's. The launcher shares the scoped client's one wire. The declaration is shown on the trust prompt, the detail page, the catalog disclosure and the install summary, and adoption refuses a copy that declares more than the wheel copy. Sage's wheel manifest declares its follow-up chat and its panel creates it through the seam with the same key, agent, title, folder and memory mode. App Kit seam level 10.
8aabeef to
18ed2be
Compare
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Reviewed head 18ed2be. A create without app_launch takes exactly the path it took before, and a create with it gets extra checks and nothing more: a person's request only, an enabled app that declares chatLaunch, no overlapping prefix from another installed app, only the launch fields, a declared key, agent, folder and memory mode, and a live-slot recheck before the mint. Code Review Sage's own follow-up always sends a key, agent, folder and memory mode its manifest declares, so it keeps working. The pin tool counts any chatLaunch declaration as a level-10 use, so a level-9 pin cannot rely on it, and the level-10 summaries in the spec, the API reference and both docstrings each name both seams. The launch, Sage parity, adoption-pin, seam-level mirror and slot-create folder tests pass on this head, and I found nothing that blocks.
The built-in's review panel opens a follow-up session with the reviewer (its agent, a title, the Sage Review folder, persistent memory) by creating the named chat slot through the dashboard's own POST /api/chat/slots. That path is outside this app's grant, so this copy could only continue a follow-up that already existed and said a new one could not be opened (PORTING.md gap 1). kirodotdev/KiroCrew#37492 adds the seam, App Kit level 10: a manifest's permissions.chatLaunch declares the one shape of chat a page opens, and useChatLauncher().createChat sends the ordinary create through the host, held to that declaration. It also declares the follow-up chat in the built-in's own manifest. This copy now: - declares the same permissions.chatLaunch (key prefix sage-followup-, both review agents, the Sage Review folder, persistent memory), so adoption is no widening; tests/test_manifest_chat_launch.py pins it to the follow-up's key derivation, agents, folder and memory mode with the host's own parser; - creates or reopens the follow-up through createChat with the same key, agent, title, folder and memory mode the built-in sends (title and folder only on a new session), then opens the key it answers; - feature-detects createChat on the launcher: on a host without it the panel offers only Continue, as before. The test dependency moves to Kiro Crew main 1dfee9ace2, which carries the seam's parser. On that host the redaction rule table masks a token only in its published format (kirodotdev/KiroCrew#37408), so the tests that plant a credential use the host's generated tokens, as the built-in's tests do. The app itself redacts through the host's passes and needs no change for it. PORTING.md marks gap 1 closed and lists both under fixes since the port. Part of kirodotdev/KiroCrew#26967. Co-authored-by: Bolin Chen <bolichen@amazon.com>
Code Review Sage now lives in its own repository under KiroCrewCaptain, ported up to the current wheel copy, #37492's chat launch included, with green CI on ubuntu, macOS and Windows. The row is the output of scripts/adoption_pin.py compute and is added to adoption-pins.json and the _SHIPPED_PINS table, so a host whose record is builtin-owned moves onto the app's own tree at its next restart and keeps data/, the app secret, the grants and enabled. minAppSdkLevel is 10, the level of the permissions.chatLaunch the repository declares exactly as the wheel copy does, so E9 holds nothing back and a host without the seam keeps the wheel copy. The wheel built-in app.json version moves to the pinned 0.9.5, since a first-adoption pin must equal it (D12). The owning spec records the adoption. Part of #26967
Problem / Motivation
Goal: An app's page can open a named, persistent chat for the person with an agent and in a folder its manifest declares, without a broad
/api/chat/slotsgrant, so Code Review Sage's follow-up chat keeps working once the app leaves core.Part of #26967. Authority: the owner ruling of 2026-11-13 on #26967 (comment 6841699202: grant each app what its built-in already uses, declared in the manifest and shown at install) and the seam-level decision (comment 6844003956: one level per open batch, feature-detected).
Code Review Sage's review panel opens a follow-up session with the reviewer through the dashboard's own
POST /api/chat/slots: the reviewer's agent, a title, theSage Reviewfolder, persistent memory. A built-in page calls that with the dashboard client. The adopted copy (KiroCrewCaptain/kirocrew-app-code-review-sage, PORTING.md gap 1) can only call the host through its scoped client, and declaring/api/chat/slotswould hand its page every slot route under that entry, which adoption refuses as a widening (E9). So the adopted copy can only continue a follow-up that already exists, never open a new one: a user-visible regression that holds its adoption pin.Why it matters
Without the seam, Code Review Sage cannot move out of core without losing "Open a follow-up session" for every user, and any other app that hands the person a conversation has to ask for the whole slot API. With it, an app declares exactly the one chat it opens (agents, folder, key prefix, memory mode), the owner sees that at install, and the gateway refuses anything else.
Not a goal
ctx.chat_slots(section 41).state.mutate_foldersfolder helper, or any other Sage gap in PORTING.md.chatLauncha staged grant held back on update (it adds no reach a page's code lacks; see the spec).adoption-pins.json, the catalog, or deleting any built-in.What changed (motivation → approach → change)
Goal → a declared, narrow create instead of a path grant. Options weighed: (a)
openChatcreating a missing slot client-side only, which the gateway could not check; (b)ctx.chat_slots, which makes the slot app-owned, changes its governance to the app's profile and its key to<app>-<id>, so existing follow-ups would stop continuing; (c) the ordinary create, marked as an app launch and held by the gateway to the app's manifest. (c) keeps the built-in's create byte-identical and puts the check where the folder and existing slots are known.permissions.chatLaunch(apps/chat_launch.py,Permissions.chatLaunch):keyPrefix,agents, optionalfolder, optionalmemoryModes. Fail-closed parse; a prefix that overlaps a core key namespace (chat-,cron-,workflow-,task-review-,member-) declares nothing.dashboard/app_chat_launch.py): aPOST /api/chat/slotscarryingapp_launch: <app>is checked right after the title check: a person's request, an enabled app that declares it, no other installed app (enabled or not) declaring an overlapping key prefix, only the launch fields, a key under the prefix, a declared agent, memory mode and folder, no app-owned or non-chat slot under the key, no other live slot with the key or its transcript up to letter case (slot_ownership.live_case_alias_reason, as an app's own create checks), no transcript that is unreadable or another app owns or opened; re-checked synchronously before the mint. One audited403 app_chat_launch_refused; otherwise the ordinary create. The prefix rule is what keeps one app off another's chats, including the ones Sage's built-in page opens, which record noembed_app(sending it would write the chat's record at create time and drop its resume pointer on uninstall, which the follow-up has never done).useChatLauncher().createChat({slotKey, agent, title?, folderId?, memoryMode?})(website/src/app-sdk/index.ts,website/src/app-sdk/scopedApi.ts) sends it through the host, naming the app, on the same wire as the scoped client (one session header, one refusal shape). App Kit seam level 10, the level feat(app-kit): tool gate honours installed apps' credential masks #37459 already raisedAPP_SDK_LEVELto on both sides (apps/app_sdk_level.py,website/src/app-sdk/sdkLevel.ts); this PR keeps it at 10 and adds its seam to the same level (level 9 is in the v0.13.0 release candidates, level 10 in no tag);scripts/adoption_pin.pycounts the declaration as a level-10 use, beside feat(app-kit): tool gate honours installed apps' credential masks #37459'scredentialMaskstool-gate use.website/src/components/appstore/TrustAppModal.tsx,trustGrants.ts,types.ts, newchatLaunch.ts), the detail page (website/src/pages/AppDetailGrantBoxes.tsx,AppDetailPage.tsx,appDetailPageTypes.ts) and the CLI install summary, plus the catalog pre-install disclosure; E9 refuses a copy declaring more than the wheel copy. Nine new strings inwebsite/src/i18n/locales/(en.manual.jsonand the 11 translated catalogs,en-XA.jsonregenerated).createAppChatSlot(website/src/api/client/chat.ts) with the same key, agent, title, folder and memory mode.createChatcontract and the shared level-10 entry in the seam-level list), manifest reference and getting-started.Backwards compatibility
Compatible: a create without
app_launchtakes exactly the path it took; Sage's create carries the same fields plusapp_launch, and its declaration covers every key, both agents, the folder and the memory mode it sends (test_manifest_chat_launch.py), including reopening follow-ups opened before this change (test_a_reopen_of_a_persons_chat_under_the_prefix_is_admitted).Removes nothing: no path, field, record or validator that main accepts is removed or tightened; the new gate applies only to bodies carrying the new
app_launchkey.Tests
test/test_app_chat_launch.py: parsing (valid, every malformed shape, core prefixes, the prefix list pinned to the core constants),covers_key,within,overlaps, manifest round-trip, disclosures (the install summary names the prefix and memory modes); the gate through the real create handler: an admitted launch is field-for-field the plain create and the person's slot; a reopen of a person's chat is admitted;embed_appis recorded; a bare launch defers its broadcast as the plain create does. Negative: 17 out-of-declaration bodies (undeclared app, invalid name, key outside the prefix or not normalized, undeclared agent, memory mode, folder, other app inembed_app, and each extra create option) each answer the uniform 403, create nothing and audit the reason; an app token is refused; another app's live slot and a live slot of another mode are left untouched; a live slot under the key in another letter case (the app's own, another app's or a person's) is left untouched, and one taken during the create's awaits is refused at the mint, while a person's live chat under exactly the key is reopened; an unreadable transcript and transcripts another app owns or launched are refused; a slot that takes the key during the create's awaits (injected at_app_claim_refused, after the gate) is refused at the mint;overlapping_declarersnames every other installed tree with an overlapping prefix (same, wider, narrower; not a disjoint one, a sidecar or one declaring nothing); an app declaring another app's prefix cannot retitle a chat the built-in path left with noembed_app, neither app launches while they overlap, and the remaining one does once the other is uninstalled. Each new handler test was checked against a mutation of the branch it pins (recheck removed, mode branch dropped, unreadable admitted, deferral tweak reverted, overlap scan off): each mutation reds exactly its test.test/test_code_review_sage_permission_parity.py: the wheel copy declares the chat; the repository copy declaring the same adopts; four wider declarations arepermission_widening; the registered built-in yields its declaration only while enabled.test/test_builtin_adoption_pins.py: the pin tool countschatLaunchas level 10.src/kiro_crew/apps/builtins/code_review_sage/tests/test_manifest_chat_launch.py: the declaration coversfollowup.slot_key, both review agents,FOLDER_NAME,persistent.website/src/test/appChatLaunch.test.tsx:createChat's exact body and session header without a declared/api/chat/slots, the 403 rejection, the trust prompt and detail page lines including the key prefix and every memory mode in the gateway's order, malformed declarations (an unknown or emptymemoryModesincluded) shown as none.CodeReviewSageReviewChat.test.tsxupdated to the seam call;ApiClient.refactor.surface.test.tslistscreateAppChatSlot.Proof: not provable -- other: new seam and feature tests, no defect fix to revert.
Determinism:
test/test_app_chat_launch.pypasses 20 times at-n0(10 more on this head, with the letter-case tests), 10 times at-n 4 --dist loadgroup --max-worker-restart=2besidetest_chat_slot_create_folder.pyandtest_app_chat_slot_sdk.py, and in a shuffled order (seed 8332). The new tests take no clock, sleep, port or thread; the mid-create race is injected by an awaited stub, not timed.Manual verification
On this head, rebased onto 2e25036: the black baseline gate, subprocess-encoding, isort, flake8, mypy on the gate module, line cap, comment-history, brand, harness parity, the flake-pattern ratchet and docs lint pass. Backend: the touched test files, the seam-level mirror, adoption pins, both credential-mask suites, manifest, facade-mirror guards, the MCP listing import budget, and the slot-create, adoption, trust, app-permission and catalog files pass (793, 384 and 417 tests in three
-n0runs, the first two on the head rebased onto 8beb3f2 after #37459, before the letter-case fix). Frontend: the chat launch, Code Review Sage, API surface, trust prompt, i18n and every scoped-client and launcher file pass (32 files, 684 tests),i18n-checkpasses anden-XA.jsonis current. An earlier head, rebased onto 4c530d0, also passed the repository semgrep rules on the diff (0 findings), withtsc -p tsconfig.app.jsonandeslint src/ --max-warnings 0clean, and the raw-fetch gate, protocol boundary and every App SDK provider file.scripts/local-gate.pyis not run on this host (its frontend leg fails on the registry login and its backend leg on a python without pytest); CI runs both suites.Screenshots / video
The trust prompt for an app declaring
permissions.chatLaunch(built dashboard, stubbed API; the repository copy of Code Review Sage, which declares what the wheel copy now does), dark and light. These predate one added line: under the description, both boxes now also sayChat keys start with sage-followup-. Memory: persistent.in the muted text style; nothing else in them moved.The detail page's permissions card, dark and light:
Related Issues
Part of #26967
Related seam already on main: #37426 (
useHostSessions, level 8) gives a page the person's live session list and a create, but admits each member only oncepermissions.apideclares every path it sends, so it needs the broad/api/chat/slotsthis seam avoids.Same batch: #37459 (
gate-adopted-masks, the agent tool gate's fence on installed apps' credential masks) landed level 10 first; this PR adds its seam to the same level.APP_SDK_LEVELstays 10 on both sides, and each level summary (app-kit-platform's level list and section 44, the api reference's seam-level list, theapp_sdk_level.pyand pin-scanner docstrings) is one level-10 entry naming both seams. Separate lanes that claim no level:desktop-host-serve(desktop window host serving an app from the chosen crew) anddesktop-host-prefs(desktop window host shortcuts and prefs store).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.