Repository navigation
feat: let an app read and clear its own bell notifications - #30911
Conversation
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: the scoped routes cover a real boundary between apps that Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: let an app's page (and backend) show and clear exactly the bell notes behind its sidebar badge — ADDITION.
[FIRST-PRINCIPLES-REVIEWED] d326bdd Description read[DESCRIPTION-READ] a04957206d5c3d689e145101ffdf1323acc55ed7738f50ce40dc469835ee5b03 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 to check. The diff adds two API routes and one SDK hook, and none of it renders anything a user sees, so a missing screenshot leaves no gap. [UX-REVIEWED] d326bdd Description read[DESCRIPTION-READ] bad53837b60f9f28eaec7b868d4fc0035b628940089eeebb61754cb2972ec2cb That sha256 names everything this verdict read: the PR description, plus the 3 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 |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. Each read and ack is scoped by the source stamp the host writes and an app cannot forge, and every ack goes through the bell's own Notes
[DESIGN-REVIEWED] d326bdd Description read[DESCRIPTION-READ] 493bdcef754f0fddbd9766880480ac83457ddf32cc6b4b4ef888cbfa16fcd9b5 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 |
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: |
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: |
a156cb6 to
c62ebf2
Compare
|
[operator: bolichen97]
|
|
[operator: bolichen97]
|
|
[operator: bolichen97]
|
c62ebf2 to
6333d56
Compare
|
Rebased: main moved in docs/app-kit/api-reference.md, test/test_dashboard_server_composition_contract_reach.py and files beside this change since this head went green (302b4fb -> d649c6b); CI re-running. The patch is unchanged (range-diff identical); the related backend tests pass on the new base. The previous round's reds were CI-side API rate limits with no reviewer verdict, so this push also re-runs those lanes. [operator: bolichen97] |
6333d56 to
aface05
Compare
|
Rebased: main moved in docs/feature-map/README.md (merge conflict in the Crew Members row next to this change's Notifications row; kept main's row) and docs/system-specs/modules/app-notifications.md since this head went green (d649c6b -> e7e3284); CI re-running. The patch is unchanged (range-diff shows only context lines); the related backend tests (262 passed, -n 4), black, isort, flake8, the feature-map, comment-history and brand gates and docs lint pass locally. [operator: bolichen97] |
eeb3d5d to
0f3ff8a
Compare
|
[operator: bolichen97] |
0f3ff8a to
eb18f75
Compare
|
Rebased: main moved in docs/feature-map/README.md (merge conflict, kept both: this PR's Notifications row text and main's new Crew Members Local gates on the new head: the PR's backend tests plus the line-budget and app-SDK mirror tests (82 passed), the PR's frontend test (9 passed), isort, flake8, black, mypy and tsc all exit 0. Local GPT and Opus reviews of this head found nothing blocking. |
|
Re-sync budget reset The base moved under this PR more times than the re-sync budget allows; a maintainer asked for one more round of re-syncs so it can be rebased and its conflicts resolved. [operator: bolichen97] |
eb18f75 to
bd7533e
Compare
|
Rebased: main moved in test/test_dashboard_server_composition_contract_reach.py (merge conflict in the MCP route-table pin; its row count and digest are recomputed from the rebased table) and docs/feature-map/README.md since this head went green (f58c3cf -> 6ff2493); CI re-running. The same push removes the server-side [operator: bolichen97] |
|
self-added: no
[operator: bolichen97] |
|
self-added: no
[operator: bolichen97] |
The sidebar badge counts an app's unacknowledged bell notes, but the app could not list or acknowledge them, so its page could not explain or clear the number. Add GET /api/notifications/own and POST .../own/ack, scoped to the notes the host stamped with the caller's app name: an app token is always its own app, and the owner's dashboard names the app its page is showing. An ack goes through the bell's own ack. An app reaches the routes through a permissions.api grant. The app SDK gets useAppNotifications() returning items, unread, ack and ackAll; ackAll acks each unread note it holds. Closes #26412
bd7533e to
d326bdd
Compare
|
Seam level placed (head d326bdd, on main 41ba859): the own-notes routes and
Local gates on this head: related backend tests (216 passed, Retrospective ( [operator: bolichen97] |
|
This PR is driven by the built-in app separation campaign (#26967) from now on; other sessions please do not push to it. |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Review of d326bdd found no blocking issue. On this head we read the full diff and ran test_notifications_own.py (3 passed). We also mutated the handler: letting a query or body app override the token identity reds 2 tests, and a hardcoded audit caller reds 1. The route table pin (344 to 347) and the body cap row match the new routes. The PR merges into main without conflicts. Well done: every ack goes through the bell's single writer, ack_notification, so the badge and the app page share one read state.
Security: the PR adds per-caller authz on two app-token routes, and the risk does not appear on this head. An app token reaches /api/notifications/own only through a declared permissions.api entry. Its identity comes from token auth and beats any app in the query or body. Ownership is checked against the host-stamped source: app:<name>. A note from another app and a missing note both return 404 and write an audit row. Non-app callers must pass require_owner_dashboard_request, and a teammate gets 403.
- Optional: add a test where two notes share one
tswith the foreign note first, and assert the ack returns 404 and leaves it unacked. Today nothing pins the first-match rule innotifications_push.pyaround line 321. - Optional: a successful read or ack writes no SEL grant row, while push does. Adding one would make the audit trail complete.
- Optional: answer the open notes on
ackAll()(issue #26412 asks for that shape), and fold the single-callermark(action, body)intoack.
Problem / Motivation
Goal: An app's own page can list and clear the bell notifications behind its sidebar badge.
The sidebar shows an app's badge as the count of its unacknowledged bell notifications (the ones the host stamped
source: "app:<name>"). The app itself could push those notes but could not read or acknowledge them: its backend had onlyPOST /api/notifications/push, and the app SDK had no notifications client. A user who clicks the badge opens the app and finds nothing that explains or clears the number. Apps work around it with their own log of what they pushed, which can never agree with the host count.Why it matters
Every app that uses notifications shows a number its own page cannot explain or clear. The badge is the host's promise that something in that app needs the user, so a page that cannot show what it means breaks that promise.
Not a goal
permissions.apilike any other route.useNavBadge()behaves.What changed (motivation → approach → change)
An app needs to see exactly the notes its badge counts, and nothing more. The host already stamps the producer onto every app note and an app cannot forge it, so that stamp is the scope.
GET /api/notifications/own{notifications, unread}for the caller app's notes onlyPOST /api/notifications/own/ack404and is left aloneuseAppNotifications()(app SDK, vendor stub){ items, unread, status, ack(ts), ackAll() }for the app's page;ackAll()acks each unread note the page holds, one at a time, skipping one already gone from the bellWho the caller is decides which app: an app token (or an app's own agent call) is always its own app, whatever the request names. Any other caller must be the owner's dashboard, where the app's page runs, and it names the app with
app; a relayed teammate or other non-owner gets403. Each refusal (another app's note, or no app named) writes a security audit event under the real caller, like the push route's refusals. App tokens reach these routes only when the app declares/api/notifications/owninpermissions.api, so the token scope check is unchanged. The handlers sit beside the push route indashboard/handlers/notifications_push.pyand are registered with it inmcp_routes.py, so both gateway entrypoints serve them. Every ack goes through the bell's ownack_notification, so the badge clears at once and there is one writer of a note's read state. The routes and the hook are App Kit seam level 4, the currentAPP_SDK_LEVEL, which no release carries yet, so the level is not raised; the App Kit docs list them in the seam-level paragraph and say a page that must also load on an older host reads the hook through a namespace import. The notifications spec, the App Kit docs and the feature map's Notifications row describe the routes and the hook; the MCP route-table pin and the request-body cap register gain the new rows.Backwards compatibility
Compatible: two new routes and one new SDK export; no existing route, field or hook changes, and an app that does not declare the path sees no difference. On a host below seam level 4 the routes answer
404and the SDK has nouseAppNotificationsexport.Removes nothing: the diff only adds routes, a hook and doc text.
Tests
test/test_notifications_own.py: an app token lists only its own notes (a foreignappin the query is ignored), gets404acking another app's or a system note, and its acks touch only its notes, with one rewrite and one broadcast per ack; the owner's dashboard reads and acks the app it names, needs a name (400), and a non-owner gets403; each refusal leaves an audit record naming the real caller (the app for a token,dashboardfor the owner).website/src/app-sdk/index.coverage.test.tsx: the hook reads/api/notifications/own?app=<name>, reportsloadingthenready,ackposts the app name and re-reads the list, andackAllposts oneackper unread note it holds (none for a read one), carries on past a note the host answers404for, and re-reads once.test_dashboard_server_composition_contract_reach.pyandtest_json_object_body_guard.pygain the new route rows and the new body-read site.test_notifications_own.pygreen 20/20 at-n0and 10/10 at-n 4 --dist loadgroup --max-worker-restart=2besidetest_notifications_push.pyandtest_notification_unread_count.py; shuffled withtest_notifications_push.py(seed 30911, 65 ids) green. The SDK test green 5/5 with--sequence.shuffle.Manual verification
N/A — the handlers are exercised end to end through aiohttp test servers, and the hook through a real React Query client; no UI renders differently.
Screenshots / video
Why no screenshot: the diff adds an SDK hook and API routes and changes no rendered pixel.
Related Issues
Closes #26412
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)