Repository navigation
feat(app-kit): let desktop windows use declared shell capabilities - #36349
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the three seams reuse the existing explicit-only grant family, the shell serves only what is both declared and approved, and the one take-away is listed as Breaking. Notes
[DESIGN-REVIEWED] bbcd433 Description read[DESCRIPTION-READ] 27973713423b61e6efaaf88fd73706e68bfdbc0d303634a09a5155fa5cab946d 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 traces back to the #26967 owner ruling or to a documented invariant. The one note is a gateway-switcher copy that has to exist until Mochi's shell code leaves core. Notes
What this change shipsInventory (9 items) — 8 justifiedIntent: let an external desktop app's own windows capture the screen, reveal or open local files and switch gateways, but only when the app declares it and the owner approves it, so Mochi can leave core. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] bbcd433 Description read[DESCRIPTION-READ] 54a112952b9231bd995ff8167f6883b876d3790a7e06ee123e0086435cbfeb5f 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: both screenshots show the new capability lines, in the trust prompt and on the app page with a held-back permission, and the blind reader read them correctly. Notes
[UX-REVIEWED] bbcd433 Description read[DESCRIPTION-READ] 3377add4753423dedfaa980d4a1546eda5b191b56e298077b4c7458e78e6266f That sha256 names everything this verdict read: the PR description, plus the 5 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 findings (all downgraded on adjudication)GPT 6.1 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- website/electron/app-window-host.js:1080 -- Failed revalidation opens newly declared windows on an unchecked crew
Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1: harm is LOW. It needs four things at once: an app holding False positive or not applicable? A repository writer can comment: |
063390f to
8abdba1
Compare
|
self-added: yes
|
|
self-added: yes
|
|
8abdba1 to
a9de3df
Compare
|
self-added: yes
|
|
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own. Adds permissions.desktopCapabilities (screenCapture, localFiles, gatewayChoice) as an explicit-only staged grant family, disclosed at install and on the app page and approved through the existing owner-gated consent path, which loops over every registered family. The Electron window host serves a capability only when the app declares it and the owner approved it, re-checked on every call. A window served by a remote crew gets only what both gateways approved. Remote tokens come from core's connected-only connect, and the crew's port is re-confirmed against core's registry before every remote load. Local-file rules are unchanged and now shared with Mochi. The _freeze_declared tightening is disclosed as Breaking and tested. The tests are extensive. The remaining issue found (stale target kept when a crew doesn't answer, causing window flapping) is low-harm and self-healing, so non-blocking. Approve, with CI still to go green. 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 |
a9de3df to
70fac54
Compare
|
self-added: no
|
|
self-added: yes
|
feaf406 to
a6eccfa
Compare
|
Moved onto origin/main 6de8528 (#37171), which fixes the main red |
An app's hosted desktop window could only shape its own windows. Mochi needs three shell features (screen capture for its snip, reveal and open a local file, and choosing among the operator's gateways), so it could not move onto the window host. permissions.desktopCapabilities names them (screenCapture, localFiles, gatewayChoice). It is an explicit-only staged grant family: an install approves what it declares, an update that adds one waits for the owner, and the trust prompt, catalog projection, detail page and CLI summary show it. The app row carries desktopCapabilitiesGrant, and the shell serves declared and approved only. The window host (bridge level 2) registers a screenCapture window as a capture surface, serves revealFile/openImage through the new shared app-local-files.js, and lists and switches crews through app-window-gateways.js, which rides only tunnels core reports connected and loads a crew only where the same app is enabled. A reused crew is re-read from core's registry on every tick and before any window loads from it, so a crew that gave up its local port is never sent its token. A window whose served set changes is closed. Mochi's manifest declares the three it already uses, and its reveal and open-image handlers run the shared module. The manifest key shares App Kit seam level 7 with the other seams of this release. Part of #26967
a6eccfa to
bbcd433
Compare
|
self-added: no
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. On this head the review checked these points:
- The new
desktopCapabilitiesfamily is explicit-only._freeze_declaredgives explicit-only families nothing when it freezes a legacyapproveDeclaredrecord. The Breaking note forreachableByUserSessionsmatches the tags. - The shell serves only declared ∩ approved, at every read. A window a crew serves gets only what both gateways approved.
- A crew's token goes to a port only after core's registry still shows that crew connected there.
- Mochi's runtime is unchanged, because it has no
desktopblock. - The new Electron host, gateway and local-file tests passed three runs in a row. Each mutation named in the body reds the test it names.
Done well: the local-file rules now live in one module. Mochi's handlers and the new host both use it, with the same checks in the same order.
Security: the new capabilities give apps screen capture, local file reveal and open, and gateway choice. An app gets them only through the existing owner consent path, and they are shown at install and on the app page. Windows served from a remote crew hold only the capabilities approved on both gateways. The one blocking lane finding was downgraded on adjudication. It covers a crew that does not answer, which can open an added window on a crew whose manifest was not checked. No credential leaks: the port is confirmed again before the load, and the token goes to the same crew. The next answering tick moves the windows back.
Optional:
website/electron/app-window-host.js:1248:revealFile,openImageandchooseGatewaydo not require a user action, unlikeopenExternal, which usesactingSender. Abackgroundwindow could call them on a timer. You could gate them the same way, or say in the spec why an unattended page may call them.website/electron/app-window-host.js:398:void reconcileOnce()joins the tick already running, so the re-resolve waits for the next 5 s tick.reconcileAfterCurrent()would make it happen "at once", as the comment says.- Two test gaps. No test covers the non-answer branch at :1080 that the
resolveTargetsdocstring describes. No test asserts the capture-trust origin for a crew-servedscreenCapturewindow (:640). The reuse-window tests could also passnowinstead of setting_targets.get(...).at.
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there; bound first and kept only when it registered. - prefs() / setPref(): each app's own small prefs on this computer, whichever gateway serves the window, bounded in size and in writes (32 at once, then one per 250 ms); the store is held in memory, so reads touch no disk. - A shell owner that is an app's own shell code reserves { app: true } and the host serving that app id may bind those chords; Mochi's reservation is marked so. - desktop.legacyMachinePrefs: a one-time, read-only import of the built-in's <app>-machine.json (a regular file of at most 256 KiB, a link not followed) into the host store, before the targets resolve, seeding the gateway choice and the bindings, never overwriting what the host has. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code reserves { app: true } and the host serving that app id may bind those chords; Mochi's reservation is marked so. - desktop.legacyMachinePrefs: a one-time, read-only import of the built-in's <app>-machine.json (a regular file of at most 256 KiB, a link not followed) into the host store, before the targets resolve, seeding the gateway choice and the bindings and reading no other key, never overwriting what the host has or a gateway the user chose through the host while the import was pending ("self" included). Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code reserves { app: true } and the host serving that app id may bind those chords; Mochi's reservation is marked so. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code may reserve { app: true } so the host serving that app id may bind those chords. Mochi keeps a plain reservation until its built-in steps aside (#37454), so the two never register the same chords. One binding is one chord whatever its spelling, so a respelled rebind keeps the chord with its holder. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code may reserve { app: true } so the host serving that app id may bind those chords. Mochi keeps a plain reservation until its built-in steps aside (#37454), so the two never register the same chords. One binding is one chord whatever its spelling, so a respelled rebind keeps the chord with its holder. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code may reserve { app: true } so the host serving that app id may bind those chords. Mochi keeps a plain reservation until its built-in steps aside (#37454), so the two never register the same chords. One binding is one chord whatever its spelling, so a respelled rebind keeps the chord with its holder. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
Problem / Motivation
Goal: A desktop app's own windows can capture the screen, reveal or open a local file, and switch among the operator's gateways, each only when the app declares it and the owner approved it, so Mochi can move onto the generic desktop window host.
The window host from #32654 lets an app's page shape only its own windows. Mochi's snip, its "show in Finder" and image viewer links, and its instance switcher (SSH crews included) reach the shell through Mochi's own main-process code, which no external app may ship. Owner ruling on #26967 (comment 6841699202, 2026-11-13, item 3) approves these as generic, manifest-declared, install-disclosed shell seams.
Why it matters
Mochi cannot leave core (#26967) while the features its users rely on exist only as Mochi-specific shell code. Without a declared seam, an external Mochi would lose screen snips, file links and its remote-crew switcher.
Not a goal
website/electron/mochi/or creating Mochi's app repository.What changed (motivation → approach → change)
Goal: Mochi's three shell features as app-agnostic, declared seams of the window host.
Approach: one grant family, modeled on
permissions.reachableByUserSessions(#34837), so disclosure, staging and approval reuse the existing machinery; the shell stays the enforcement point and serves onlydeclared ∩ approved.permissions.desktopCapabilities(screenCapture,localFiles,gatewayChoice; unknown entries dropped) inapps/desktop_capabilities.py. Explicit-only staged grant family: an install approves it, an update that adds one waits, a set stored before the key approves none, a built-in's packaged declaration is approved. App rows carrydesktopCapabilitiesGrant. Disclosed in the catalog projection and the CLI install summary. The key shares App Kit seam level 7 with the other seams of this release, andscripts/adoption_pin.pymaps it there.screenCapturewindow is registered withcapture-trust.js.revealFileandopenImagerun the newapp-local-files.js.listGatewaysandchooseGatewayrun the newapp-window-gateways.js: it rides only tunnels core reports connected, asks core's connected-onlyconnectfor the token, loads a crew only where the same app is enabled, declares every window this computer opens and hasgatewayChoiceapproved (so its windows can always come back), keeps the windows on a non-answer, and shows the page no host name, port or credential. A reused crew is re-read from core's registry on every tick and before any window loads or reloads from it, and re-resolved when the app's windows here change; a crew no longer connected on its port is dropped, so a port another crew took over is never sent its token. A window a crew serves gets only the capabilities the app holds on both gateways (approved here and in that crew'sdesktopCapabilitiesGrant), so another gateway's bundle never gets one its own owner did not approve. The choice is kept per app in the shell store. A window whose served set changes is closed. The two new modules are inbuild.files(website/electron/package.json).TrustAppModal.tsx) and the app page (AppDetailGrantBoxes.tsx,AppDetailPage.tsx, row types, theenableAppconsent type inapi/client/apps.ts) show each capability fromdesktopCapabilityLineincomponents/appstore/desktopCapabilities.ts;trustGrants.tscarries the declaration to every place that opens the trust prompt; "Approve new permissions" approves a held-back one. The page's staged-grant reading moves toappDetailPageStagedGrants.ts, keepingAppDetailPage.tsxunder the line cap. New strings in all 12website/src/i18n/locales/*.json(en.manual.jsonfor English,en-XA.jsonregenerated).desktopWindow/desktopWindowTarget.tstypes the level 2 calls.app-local-files.jswith identical rules.Specs: app-kit-platform §35, mochi.md, manifest and API references, electron README; the App detail row of
docs/feature-map/README.mdlistsappDetailPageStagedGrants.ts.Backwards compatibility
The key is new and optional. An app that does not declare it, a gateway that predates it (no grant row) and every existing window get exactly what they had. Mochi's shell code does not read the grant, so Mochi behaves as before.
Breaking: an app record still stored as "approve what is declared" (an install from before approved sets that the gateway has not read since the upgrade) no longer approves an explicit-only family (
point_grants.explicit_only_grant_families():reachableByUserSessionsand the new key) when its first read freezes it. Those wait on the app page's "Approve new permissions", because no owner was shown them before approved sets existed. A set already frozen or stored is untouched. No current user loses a working app session:reachableByUserSessionsships only in v0.13.0-rc.1, whose first read already froze such a record with its declared verbs into a stored set this change leaves alone, and on stable 0.12.x the key grants nothing to lose. Writer sweep on origin/main @ 6c8b798:_import_app_tree_grantsinapps/manager_records.pyis the only production writer ofapproveDeclared(_write_approve_declaredhas test callers only); the protected grant store has no writer outside the gateway.Reader: src/kiro_crew/apps/user_session_reach.py:_approved -- chat -- test_a_record_from_before_approved_sets_approves_none_of_them
Reader: src/kiro_crew/apps/desktop_capabilities.py:_approved -- app -- test_a_record_from_before_approved_sets_approves_none_of_them
Tests
test/test_app_desktop_capabilities.py: the parse, the explicit-only family, catalog and CLI disclosure, install approving, an update staging and the owner approving, a pre-key set approving none, a record from before approved sets approving no explicit-only family when frozen (apps/manager_records.py:_freeze_declared), Mochi's declaration, a built-in approved as packaged.test/test_builtin_adoption_pins.py: the key maps to level 7.website/electron/test/app-window-host.test.js: refused when undeclared, staged or on a gateway with no grant row;localFilesandscreenCaptureserved only to the holding app; withdrawal closes the window; choosing a crew moves the windows there and back; app off there falls back; a non-answer keeps them; a crew whose manifest lacks the window keeps it here; a stored crew that does not answer at start opens on this computer, then moves once it answers; a crew that gave up its port inside the 60 s reuse is never sent its token, neither by a newly opened window nor by the next tick; a crew's window holds only what the crew also approved (no screen, no file calls otherwise), reopens holding a capability the crew approves, and closes when the crew withdraws it; a window added here inside the 60 s reuse is checked against the crew's manifest, so a crew still on the older one leaves the windows on this computer; a crew that has not approvedgatewayChoicenever takes the windows, and the page there can still choose.app-window-gateways.test.js: every connect is connected-only; a crew disconnected after the listing, whose manifest lacks one of this computer's windows, or whose owner has not approvedgatewayChoicethere falls back to this computer;confirmreads a crew as itself only while core shows it connected on the same port; a crew's target carries what the app declares and approved there, nothing else.app-local-files.test.js,app-window-host-rules.test.js,app-window-preload.test.js,app-window-host-independence.test.js.TrustAppModalWorkerAutoApprove.test.tsx,AppDetailPageCoverage.test.tsx: disclosure, staged line, approval payload, trust target.Mutation check: removing either port re-check (before a remote load, or on the tick) reds exactly its own new host test.
Determinism: the Python file 30x
-n0, once shuffled (seed 4207), and-n 4 --dist loadgroup --max-worker-restart=2, green. The Electron gateway and host files 5x green (node 22 has no shuffle flag; the host tests wait on the host's own pending loads, never a timer). Vitest files 5x with--sequence.shuffle, green.Local gates on this head: isort, flake8, black gate,
mypy src/kiro_crew(clean), comment-history, brand, file-line cap, harness parity, docs-lint, the flake-pattern ratchet,tsc -p tsconfig.app.json, eslint on changed files, 4,602 related backend tests, 13 related Vitest files (298 tests), and theapp-*and Mochi Electron files (375 of 376;petOverlays.test.jscannot loadelectron, which this host'snode_moduleslacks). Mutation check: dropping thegatewayChoicerequirement on a crew reds the new host test and the resolver's definite-no cases; serving a crew's window this computer's set reds the both-gateways host test; reusing a crew target across a changed window set reds the window-added test. Semgrep is not installed on this host; CI's SAST runs it.Manual verification
Rendered the trust prompt and the app page from a built bundle with stubbed APIs (screenshots below). The Electron windows themselves were exercised through the host's injected-Electron tests only; no live desktop session was run.
Screenshots / video
Trust prompt for an app declaring all three:
App page with one capability held back by an update:
Related Issues
Part of #26967
Owner ruling: #26967 (comment)
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)