Skip to content

feat(apps): permissions.browser grant, app_browser_sdk preview and ctx.browser (RFC #38322 step 1a) - #39018

Open
chenmingwei23 wants to merge 1 commit into
mainfrom
feat/app-sdk-browser-1a
Open

chenmingwei23 wants to merge 1 commit into
mainfrom
feat/app-sdk-browser-1a

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app can declare permissions.browser and the owner approves each verb on the app's page, behind a default-off preview, so step 1b of RFC #38322 can build the browser operations on a grant that already exists.

Implements step 1a of RFC #38322 (docs/request-for-change/rfc-app-sdk-browser.md, Migration plan row 1a). Today an app has no way to ask for the browser tabs of its own chats. Browser Collab gets them through out-of-tree patches, which every other app is denied.

Why it matters

Steps 1b and 1c add the page operations and the BrowserView component. Each of them needs a grant the owner can give and take back, and a switch that keeps the whole surface off until it is ready. Without this step they would each invent one.

Not a goal

  • No page operation: ctx.browser has no page(), slots(), navigate, click or screenshot yet. That is step 1b.
  • No front-end SDK component and no APP_SDK_LEVEL change. That is step 1c.
  • No change to the Bot's own browser tool, permissions.browserSites, or any default.

What changed (motivation -> approach -> change)

The RFC asks for a staged grant family like permissions.api and permissions.events. So the new family copies the nearest existing ones: desktopCapabilities for the verb list and browserSites (#38333) for "install approves nothing".

Part What it does
permissions.browser A list of verbs, view, read, act. Unknown entries are dropped, so a bad value grants less.
browser grant family Registered explicit-only in apps/point_grants.py and added to _OWNER_APPROVED_FAMILIES. Install approves no verb. An update that adds a verb holds that one back, by the existing staged-family rule.
app_browser_sdk preview "App browser access" in Settings > Developer > Feature previews, default off. Read through edition_locks.feature_previews, so LTS reads it as off.
ctx.browser apps/browser_sdk.BrowserSDK, kept on the context when the manifest declares the field. The AppContext.browser property returns it only while the preview is on, read at each access, so turning the preview on needs no restart. Its verbs() re-reads the preview, the manifest and the approved set on every call.
Owner surfaces The trust prompt and the CLI install summary list each verb in plain words, say install approves none, and say an app that is off can use none of them. The app page shows a box with each verb, tags the ones not approved, offers them in the shared "Approve new permissions" notice with one line saying that button turns each one on at once with no further prompt and that turning the app off stops them (the approved message uses the same plain words), and says when the preview is off.

Docs: manifest-reference.md, api-reference.md (ctx.browser), configuration.md, the feature map and section 46 of app-kit-platform.md. Strings are in every locale and en-XA is regenerated; the settings registry, UI index and config-baseline.json are regenerated.

Where: the preview name is in config/sections_dashboard.py and utils/previewFlags.ts, its switch in pages/settings/FeaturePreviewsSection.tsx; the verb words in components/appstore/browserVerbs.ts; the app page box in pages/AppDetailGrantBoxes.tsx; the approval call type in api/client/apps.ts; the strings in i18n/locales/en.manual.json and the other locale files.

Backwards compatibility

Compatible: a new optional manifest field and a new preview that is off. An app that does not declare permissions.browser gets no ctx.browser and its grants are unchanged.

Removes nothing: the diff only adds a field, a grant family, a preview and their readers.

Tests

  • test/test_app_browser_sdk.py: the family is staged and explicit-only; only known verbs are declared; an install holds no verb until the owner approves one; an update that adds act holds act back and keeps view and read; preview off means no ctx.browser and a kept SDK handle holds no verb; a preview turned on after the context was built gives ctx.browser with no restart; an app that is turned off holds no verb, and turning it on again restores the approved ones; an app without the field gets no ctx.browser; the install prompts name each verb. Removing "browser" from _OWNER_APPROVED_FAMILIES turns the install test red.
  • website/src/test/AppDetailPageCoverage.test.tsx: the app page lists only the held-back verb in the approval notice, tags it in the box, says the preview is off, and approves with browser: ['act']; a row with no browser grant (a store row) reads the App browser access switch itself.
  • website/src/test/TrustAppModalWorkerAutoApprove.test.tsx: the trust prompt names each known verb, drops an unknown one, and says the preview is off.
  • website/src/test/previewSurfaces.test.tsx: the new switch is drawn and is off by default.

Each new test was run three times in a row, serially, with the same result.

Manual verification

Run in a pod on this head, with a local test app page-pal that declares "browser": ["view", "read"], then an update to 1.1.0 that adds "act". The app row's browserGrant at each step:

Step browserGrant
Installed, preview off approved [], staged view, read, preview false
Preview on approved [], staged view, read, preview true
Owner approves on the app page approved view, read, staged []
Update adds act approved view, read, staged act

Screenshots / video

A narrated walk through the whole flow on the pod: install, the switch, the trust prompt, approval, and an update that adds act.

app-browser-access-demo.mp4

The app page right after install, preview off: both verbs tagged not approved, and the note that the switch is off.

App page after install, preview off

The new switch in Settings > Developer > Feature previews.

App browser access switch on

The trust prompt when the owner turns the app on: the verbs are listed, and install approves none.

Trust prompt lists the browser verbs

The app is on and both verbs still wait: the notice says what Approve new permissions does, and that it applies at once.

App on, verbs waiting for approval

After the owner approves, and after an update that adds act: only act waits.

App page after approval

Update holds act back

Related Issues

Part of #39017

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

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

No blocker. The blind reader read both primary controls correctly: the "App browser access" switch and "Approve new permissions". The problems below are wording problems.

Notes

  • An app's first browser request is shown in the notice built for app updates, so it says "Ignore this to keep Page Pal on the permissions you already approved" (shot-04) and "approve these new permissions here" (shot-01). The blind reader: "as far as I can see I never approved any" and "I cannot see any approve button". When nothing has been approved yet, use first-request wording, and point the disabled-app line at "Enable".
  • "Browser tabs of its own chats" and "this app's chats": the reader asked, "Does an app have chats of its own?" Name the chats where the user will see them, for example "chats you start from Page Pal".
  • In browser_verb_act, the reader could not tell which tab "that tab" means. Name it again: "Open pages in the browser tab of those chats, and click and type there for you."

[UX-REVIEWED] 2f98336

Description read

[DESCRIPTION-READ] 67a6521bcbd0f136bc93a7a5e59e59f837f7fae57cd6984ffe0e0c1a8e916259

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 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the change copies the existing staged, explicit-only grant pattern from browserSites and desktopCapabilities, removes nothing, sits behind a preview that is off by default, and the description includes screenshots and a recording of this revision.

Notes

  • When the live config snapshot is empty, preview_on() falls back to KiroCrewConfig.load() on every ctx.browser access and every verbs() call. Step 1b will put this on each page operation, so it should read the live snapshot only, or cache the load.

[DESIGN-REVIEWED] 2f98336

Description read

[DESCRIPTION-READ] 9541e45168073215849fa58c36012845945a4111efdf3002a10013fadac5cd54

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 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 2f98336acb10cbe9a77e549525276046f688e1ae — 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

Nothing blocks. Everything ships behind the app_browser_sdk preview, which is off by default. The leftovers are two zero-consumer stubs that are cheap to delete.

Notes

  • Item 4 — zero consumers: BrowserSDK.verbs() is the whole of ctx.browser. Grep for ctx\.browser|\.verbs\(\) finds only tests and docs, and no operation uses it until step 1b. Subtraction: delete BrowserSDK, browser_sdk_for and AppContext.browser/browser_sdk, and land them with step 1b's page(), the first real caller.
  • Item 9 — zero consumers: BROWSER_GRANT_FAMILIES = (GRANT_FAMILY,) is a one-element tuple exported in __all__. Grep for BROWSER_GRANT_FAMILIES finds 0 uses outside its own definition. Subtraction: delete it and the __all__ entry.

What this change ships

Inventory (9 items) — 6 justified

Intent: let an app ask for browser verbs on its own slots and let the owner approve each one, behind a preview that is off by default. This is an ADDITION.

  1. A manifest can declare permissions.browser: [view, read, act], and unknown entries are dropped — justified
  2. An install approves no verb, and an update holds back any verb it adds — justified
  3. A new "App browser access" switch in Feature previews, off by default — justified
  4. ctx.browser exists, but its only method is verbs() — zero consumers, step 1b is its first caller
  5. The trust prompt and the CLI install summary name each verb — justified
  6. The app page shows a verb box, tags verbs not yet approved, and approves them through the shared notice — justified
  7. App rows carry browserGrant with approved, staged and preview — justified
  8. The official catalog shows the declared browser verbs — undeclared
  9. The exported BROWSER_GRANT_FAMILIES tuple — zero consumers

[FIRST-PRINCIPLES-REVIEWED] 2f98336

Description read

[DESCRIPTION-READ] 308c4a0e622951ea73afc554211df21f35cc5eac1660dd820255bf67723f79cd

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 commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2f98336acb10cbe9a77e549525276046f688e1ae and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2f98336

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

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • The approval toast strips only an ASCII . from each verb sentence. In ja, zh-CN, hi and bn the sentence ends in 。 or ।, so the punctuation is doubled (AppDetailPage.tsx:1678). This is cosmetic.
  • app_browser_verbs skips the third_party_ceiling_closed check that app_browser_sites makes. Nothing in this PR gates on verbs(), so this needs the check when the step 1b page operations land.

[OPUS-REVIEWED] 2f98336

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

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

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/app-sdk-browser-1a branch from 696ea95 to 331fb49 Compare November 18, 2026 06:32
@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 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/app-sdk-browser-1a branch from 331fb49 to 1f0164a Compare November 18, 2026 06:47
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=4c10c25f096b ctx.browser stays None after the preview is turned on

fixed in 1f0164a: build_app_context now keeps a BrowserSDK whenever the manifest declares permissions.browser, and AppContext.browser is a property that reads the app_browser_sdk preview at each access. The RFC's 1a bar (preview off: ctx.browser absent) still holds, and a preview turned on after start needs no restart.
Test: test_a_preview_turned_on_after_start_needs_no_restart in test/test_app_browser_sdk.py.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=3ca05c9421ee a store row says the preview is off when it is on

fixed in 1f0164a: BrowserVerbsBox takes preview as optional. An installed app passes browserGrant.preview; a row without browserGrant (a store row) reads usePreviewFlag(PREVIEW_APP_BROWSER_SDK), as the trust prompt does.
Test: reads the App browser access switch for a row with no browser grant, in website/src/test/AppDetailPageCoverage.test.tsx.

@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 labels Nov 18, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • span=440807ba3e00 the browser-verb approval copy promises a per-verb step the button does not offer

fixed in 1f0164a, the copy route the finding offers: the trust prompt now says the owner approves them on the app's page and that turning the app off takes them back, matching the shared Approve new permissions button and its own disable note. The approved message names each verb in its plain sentence, not its id.
Not built here: a per-verb approve and revoke control. Every staged family (api, events, desktopCapabilities, browserSites) shares the one approval notice today, and RFC rfc-app-sdk-browser.md step 1a asks for the existing staged-family path, not a new control.
Notes: the Turn it on line and the Manifest key line are shared by every grant box on main and are left as they are.

@chenmingwei23
chenmingwei23 force-pushed the feat/app-sdk-browser-1a branch from 1f0164a to 6ca9979 Compare November 18, 2026 06:59
@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 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/app-sdk-browser-1a branch from 6ca9979 to 779cbbe Compare November 18, 2026 07:52
@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 labels Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/app-sdk-browser-1a branch from 779cbbe to 0771309 Compare November 18, 2026 08:07
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • browser_note says turning the app off takes the browser approvals back, but disable_app keeps them

fixed in 0771309: app_browser_verbs now also requires is_app_enabled, as browser_sites.app_browser_sites does, so an app that is off holds no verb and turning it on again restores what the owner approved. browser_note in every locale now says exactly that instead of promising a revoke.
Test: test_an_app_that_is_off_holds_no_verb_until_it_is_on_again in test/test_app_browser_sdk.py.

@chenmingwei23
chenmingwei23 force-pushed the feat/app-sdk-browser-1a branch from 0771309 to 2f98336 Compare November 18, 2026 08:37
@chenmingwei23

chenmingwei23 commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=440807ba3e00 Approve button for browser verbs is one the user won't dare press

fixed in 2f98336: the approval notice now has one line above the held-back browser verbs saying Approve new permissions turns each one on right away with no further prompt, and that turning the app off stops them until it is on again. The shared button label stays, because every staged family uses it.
Notes left as they are: the Turn it on line and the gateway word are shared copy on main. The enabled state with view and read still waiting is now a screenshot in the description.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants