Repository navigation
feat(app-kit): let an app open and drive its own chat slots - #36356
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the seam only adds things, is off unless Notes
[DESIGN-REVIEWED] 62a4870 Description read[DESCRIPTION-READ] c437c072dbc51f1a41d04d1e33c86fc1a884204c0f406927bf1ac41c51bc0c99 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 replaces private host names that the Spec Builder backend calls today, so it answers a named need. The Notes
What this change shipsInventory (6 items) — 5 justifiedIntent: let an installed app run its own visible dashboard chats through a public contract, so Spec Builder can leave core. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 62a4870 Description read[DESCRIPTION-READ] 00124aed363836188d465fefb2fb5cf0cc58cb00f9f9cc76181c6f550c7482ba That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks: the PR adds two information boxes and no new controls, both are shown in light and dark, and the blind reader understood them. Notes
[UX-REVIEWED] 62a4870 Description read[DESCRIPTION-READ] 8ce0511b03a0f9e03907da1e2c749aa6bb0dffb45680fe4fc14afb166930b15f 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: |
5fee8c1 to
7bcd172
Compare
|
span=6a034b31cd31 fixed in 7bcd172
|
|
span=6a034b31cd31 fixed in 7bcd172
|
|
span=6a034b31cd31 fixed in 7bcd172
|
|
span=470aa782bec1 fixed in 7bcd172
|
|
span=470aa782bec1 fixed in 7bcd172
|
|
span=470aa782bec1 fixed in 7bcd172
|
|
span=470aa782bec1 fixed in 7bcd172
|
Sensitive Change ReviewSensitive files changed:
|
7bcd172 to
c72ae6d
Compare
Sensitive change review
|
|
Seam level moved from 8 to 7, per the #26967 driver decision (comment 6844003956): every seam of the open batch is level 7, so this PR no longer has to land after #33589, and whichever of them merges first raises Because a level-7 host can lack any single seam of the batch, the api-reference and §40 tell an app to test for The same head also classifies the seam in the two source-tree registries the previous head's CI found it missing from ( |
Code change approver recommendation: A person should decideWhy: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 2331 lines, more than the 400 it may approve on its own. An additive App Kit seam that is off unless the manifest declares 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 |
e9b37ee to
e1e17a0
Compare
|
Rebased onto main 6d61070 (from 0e5b203) to pick up the Coverage Gate fix #36804; the diff itself did not change, so the body and every review disposition still describe it. Head is now e1e17a0. The reds on the previous head e9b37ee are not this PR's:
Locally on the rebased head: the five changed backend test files (264 passed), isort, flake8, mypy, black baseline, comment-history, brand-name and file-line-cap gates pass. |
Sensitive change review
|
e1e17a0 to
aa7d57e
Compare
|
self-added: no
|
Sensitive change review
|
An app whose worker is a visible dashboard chat (Spec Builder) reaches private gateway names to run it: the chat runner and its queue drain, the turn ceiling, the containment stamp, slot restore and archive, the compaction probe, the slot registry and AutoNudge. Owner ruling 4 of 2026-11-13 on #26967 asks for an app-owned chat slot API instead. ctx.chat_slots (App Kit seam level 8, permissions.chatSlots) is that seam. Keys are <app>-<id>, every slot operation refuses a slot that is not the app's, turns run through the gateway's own chat runner with the caller's provenance, a queued message is stamped and its pushed row redacted, stop and archive drop queued work first, and the AutoNudge view and arm call see and act on the app's own loops only, through the shared authorization chokepoint. The declaration is shown on the trust prompt, the detail page, the catalog disclosure and the CLI install summary; every trust prompt entry point now reads the declared grants through one helper. Adoption refuses a copy that declares it when the wheel copy does not, and Spec Builder's wheel manifest declares it.
aa7d57e to
62a4870
Compare
|
Rebased onto main 8a82f59 to clear a merge conflict: main added an exact On aa7d57e every lane was green (CI, all eight macOS shards, GPT, Opus, Design, First Principles, UX) except CodeQL |
Sensitive change review
|
|
Head 62a4870 is green ( |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
The review checked head 62a4870. Every host call the new ctx.chat_slots seam makes exists with the arguments it passes. Ownership is decided by the slot's _app stamp plus live identity, not by key prefix. Keys stay under the registry's fold length. Store reads run off the event loop. Archive hands off to the gateway's own close_slot. The review also ran test/test_app_chat_slot_sdk.py from this head (86 passed, repeats green under xdist) and found 15 of 19 single-line mutations of chat_slot_sdk.py caught. Well done: each public method replaces a private gateway call the built-in Spec Builder already makes, so nothing in the seam is speculative.
Security: the new permission is declared in the manifest, the wheel copy declares it first, an adopted copy that adds it over a wheel copy without it is refused as a widening (E9), and the trust prompt shows it. Turns the seam starts run as actor app through spawn_guarded_turn and run_background_turn. They keep the unattended-turn cap and Shared Crew admission, and they queue only typed messages with the person's origin. Titles pass outbound redaction and are withheld when redaction fails. The flag is disclosure only, like agentTurns. It is not a boundary against the app's trusted in-gateway code, and the module says so.
Optional:
- #36359 also adds
website/src/components/appstore/trustGrants.ts, with a different API (trustGrantsOf(manifest), which includesdesktop). Pick one owner and name the merge order in both bodies. Foldingdesktopinto the single helper would also make its "reaches every entry point" docstring true. - The reservation-release guard at
chat_slot_sdk.py:475has no pin. Deleting it lets a finished reservation setslot.task = Noneover a running turn, and all 86 tests still pass. A test that waits for the reservation's done callbacks before checkingslot.taskwould catch it. - Two more fences are pinned on one side only: restore's
owns(restored)refusal on a foreign live slot, and the E9chatSlotsgate when both the wheel and adopted copies declare the flag.
Problem / Motivation
Goal: An app can open and drive its own dashboard chat slots (turns and queue, restore and archive, stop, transcript, AutoNudge) through one generic, level-gated App Kit seam, so Spec Builder can leave core without reaching private gateway functions.
Spec Builder's worker is a visible dashboard chat. To run it, the built-in (and its external copy in
KiroCrewCaptain/kirocrew-app-spec-builder) calls private gateway names:chat_runner._run_chatand_start_next_queued_turn,turn_dispatch.bounded_chat_turn,session_control.containment_meta,chat_persistence.rehydrate_slot_from_history_asyncandsave_slot_off_loop,chat_utils._history_key_for,session_lifecycle.compaction_in_flight, the slot registry, and AutoNudge's service, maintenance view andauthorize_and_add_nudge. An installed app has no public way to get any of them, so a refactor of any one silently stops it. Owner ruling 4 of 2026-11-13 on #26967 (comment 6841699202: "decide directly; users' normal use must not be affected; grant what is needed") asks for an app-owned chat slot API as a generic seam.Why it matters
The campaign cannot move Spec Builder out of core (#26967) while its core function is a set of private host names. With the seam, the external copy runs on a public contract that keeps working across releases, and the safety the built-in has (slot identity, admission, redaction of text pushed to every dashboard, AutoNudge scoped to its own loops) is enforced by the host instead of re-implemented per app.
Not a goal
adoption-pins.jsonor the catalog.What changed (motivation → approach → change)
One seam owns every chat-slot operation an app needs, keyed and checked by the app's own name.
ctx.chat_slots(apps/chat_slot_sdk.py), present only whenpermissions.chatSlotsis the literaltrue. Keys are<app>-<id>(thectx.turnsgrammar), at most the registry's folded key length, but ownership is the slot's_app, never the prefix (an app name can extend another's).openrefuses a key whose live slot or saved transcript is someone else's, andrestorenever revives another owner's transcript; every call that acts on a slot refuses one that is not the app's (ChatSlotRefused), and the by-key ones also refuse a kept object that is not the live slot under its key. Turns start through the gateway's guarded start and chat runner as actorappunder the unattended-turn cap, as an app's own/api/chatturn does, with the caller's provenance, after a restored note hold is delivered;send(reservation=)starts the turn areserveheld. A queued message gets the containment stamp and a redactedqueuedrow, and keeps the person's origin only when it is typed, because the drain runs every entry as typed; a title is redacted before its push.stop_turnandarchivedrop queued work first;archivethen runs the gateway's own close (close_slot, what a tab's close button runs), which owns every save, deletion and same-key race and answersFalsewhen it did not commit. A saved transcript is read only when it records the app as owner. The AutoNudge view acts only on loops on slots the app owns, a refused removal answeringFalse;arm_nudgearms throughauthorize_and_add_nudgewith sourceapp:<app>.security_posture.pyclassifies the module as a non-egress redaction site.TrustAppModal.tsx), the detail page (AppDetailGrantBoxes.tsx,AppDetailPage.tsx), the catalog's pre-install disclosure and the CLI install summary name it. Every trust prompt entry point (AppDetailPage.tsx,useAppActions.ts,appDetailPageLocalSwitch.ts) now reads the declared grants through one helper (trustGrants.ts, with the types inappDetailPageTypes.tsandtypes.ts), so the local-source switch prompt also showsworkerAutoApproveand the user-session reach it missed. Adoption (E9) refuses a copy that declares it when the wheel copy does not; Spec Builder's wheel manifest declares it.website/src/i18n/locales/(en-XAregenerated).adoption_pin.py's level scan.compaction_in_flight's docstring (session_lifecycle_parts/stop_decline.py) lists the new caller.opencreates an app-owned slot (test_chat_follow_default_slot_kinds.py), and its saved-transcript read is plumbing, like the Spec Builder read it replaces (test_transcript_derivation_seam.py).Seam level 7, shared with #33589. Every seam of the open batch is level 7 (#26967, comment 6844003956). #33589 landed first and raised the level from 6 to 7, so this PR adds its rows to level 7 beside
agentReadOnlyDirsand changes no level line. A level-7 host can lack any one of them, so the docs tell an app to test forctx.chat_slotsitself. Spec Builder's external copy detects both seams it uses by the seam, not the level (agentReadOnlyDirsin KiroCrewCaptain/kirocrew-app-spec-builder#6, merged).Backwards compatibility
Compatible: the permission is new and off by default, so no installed app gets the seam until its manifest declares it; nothing a user does today changes. The E9 refusal applies only to an adopted manifest declaring the new key, which no shipped pin does.
Removes nothing: the change only adds a seam, a manifest key and a disclosure box.
Tests
test/test_app_chat_slot_sdk.pypins: presence only on a literaltrue; key grammar, including the longest key staying unfolded with file names that fit; title redaction, withholding and marking the slot for the next save; the restored hold delivered above the user row;sendstarting its own reservation and refusing an unread window untilopen; ownership refusals for every slot operation on a foreign or unscoped slot, leaving it untouched, and for a kept object whose key another app's slot now holds;openrefusing a held key or another owner's saved transcript, andrestoreleaving one unpublished;send's provenance,appactor, unattended-turn cap and guarded start; the queued stamp, redaction and withheld-on-failure row; a queued composed message dropping the person's origin; the reservation and its drain; stop and archive order (queue dropped first, cooperative stop skipped while compacting, a successor started meanwhile left running, archive through the gateway's close, a close that did not commit answeringFalse, and one archive run against the real state and close); transcript scoping (live owner, saved owner, off-loop window read); the AutoNudge view's slot-ownership scoping (a prefix-extending app's loop and a cold loop are invisible live), captured-loop removal, a removal the live service refused answeringFalse, the maintenance view's saved owners, andarm_nudge's source; the install summary and catalog disclosure.test/test_builtin_adoption_pins.py(level 7 for the key and the context seam) andtest/test_builtin_adoption_apply.py(E9 refuses a newchatSlots).website/src/test/TrustAppModalChatSlots.test.tsx: the trust prompt box,trustGrants(literaltrueonly), the detail page box.test_source_link_github_case.py, passes alone and touches nothing here); the related backend set (7082 passed: app context, manifest, permissions, catalog, adoption, decoupling, compaction stop, and the Spec Builder suite),tsc -p tsconfig.app.json, the i18n suite, black, isort, flake8, mypy on the touched modules, comment-history, brand, line-cap, docs lint, flake-pattern ratchet.asyncio.wait_for), waits are on signals (a done callback setting anasyncio.Event), no clock, port or sleep.test_app_chat_slot_sdk.py: 20 runs at-n0and 10 at-n 4 --dist loadgroup --max-worker-restart=2besidetest_app_agent_turn_sdk.pyandtest_app_context.py, all green; the 86 node ids shuffled with seed 36356, green.Manual verification
The trust prompt was rendered from the built dashboard with stubbed API answers (screenshots below). The external Spec Builder copy runs on the seam in KiroCrewCaptain/kirocrew-app-spec-builder#4 and #5, whose suite passes on both a host with and without it.
Screenshots / video
The trust prompt for an app that declares
permissions.chatSlots(built dashboard, stubbed API), dark and light:The detail page's permissions card, dark and light:
Related Issues
Part of #26967
Owner ruling: #26967 (comment)
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)