Skip to content

feat: let an app read and clear its own bell notifications - #30911

Merged
bolichen97 merged 1 commit into
mainfrom
fix/26412-app-own-notifications
Nov 9, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/26412-app-own-notifications

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

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 only POST /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

  • Letting an app read or acknowledge another app's notes or the host's own notes.
  • Granting the new routes to app tokens implicitly: an app opts in through permissions.api like any other route.
  • Following the bell live inside the app page (the list is read on mount, on focus and after each ack).
  • Changing how the badge is counted or how 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.

Surface What it does
GET /api/notifications/own Returns {notifications, unread} for the caller app's notes only
POST /api/notifications/own/ack Marks one of the caller app's notes read; any other note reads as 404 and is left alone
useAppNotifications() (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 bell

Who 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 gets 403. 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/own in permissions.api, so the token scope check is unchanged. The handlers sit beside the push route in dashboard/handlers/notifications_push.py and are registered with it in mcp_routes.py, so both gateway entrypoints serve them. Every ack goes through the bell's own ack_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 current APP_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 404 and the SDK has no useAppNotifications export.

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 foreign app in the query is ignored), gets 404 acking 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 gets 403; each refusal leaves an audit record naming the real caller (the app for a token, dashboard for the owner).
  • website/src/app-sdk/index.coverage.test.tsx: the hook reads /api/notifications/own?app=<name>, reports loading then ready, ack posts the app name and re-reads the list, and ackAll posts one ack per unread note it holds (none for a read one), carries on past a note the host answers 404 for, and re-reads once.
  • test_dashboard_server_composition_contract_reach.py and test_json_object_body_guard.py gain the new route rows and the new body-read site.
  • Determinism: test_notifications_own.py green 20/20 at -n0 and 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_notifications_push.py and test_notification_unread_count.py; shuffled with test_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

  • 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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 00:16
@bolichen97
bolichen97 requested a review from CrysisDeu November 6, 2026 00:16
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d326bdd81dce54a5a7bdf720ec9382e6e23e48c1 — 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: the scoped routes cover a real boundary between apps that /api/notifications cannot cover. Granting that route would expose every app's notes and the host's own.

Notes

  • Item 4 — oversized: ackAll() is a client-side loop over ack ("acks each unread note the page holds, one at a time"). It adds no host capability, and an app can write the same loop in three lines over items and ack. Subtraction: drop ackAll from AppNotifications and useAppNotifications, and keep ack(ts) as the only way to clear a note.

What this change ships

Inventory (8 items) — 7 justified

Intent: let an app's page (and backend) show and clear exactly the bell notes behind its sidebar badge — ADDITION.

  1. An app backend can list its own bell notes via GET /api/notifications/own — justified
  2. An app can mark one of its own notes read via POST /api/notifications/own/ack; any other note answers 404 — justified
  3. The owner's dashboard names the app with app; a non-owner gets 403 and a missing name gets 400 — justified
  4. The SDK's ackAll() acks every unread note the page holds, one at a time — oversized
  5. The SDK exports useAppNotifications() (items, unread, status, ack), and the vendor stub re-exports it — justified
  6. Each refusal writes a security audit event under the real caller — justified
  7. App tokens reach the routes only through an opt-in permissions.api grant — justified
  8. The App Kit docs, the spec, the feature map and the route/body-cap pins list the new surface at seam level 4 — justified

[FIRST-PRINCIPLES-REVIEWED] d326bdd

Description read

[DESCRIPTION-READ] a04957206d5c3d689e145101ffdf1323acc55ed7738f50ce40dc469835ee5b03

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

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 .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 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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 ack_notification, so the bell stays the only thing that writes read state.

Notes

  • ackAll() sends one request per unread note and re-reads after each batch. If an app's note count grows, the simpler fix is to let POST /api/notifications/own/ack take a list of ts values, rather than sending more requests from the client.

[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 .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 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d326bdd

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d326bdd

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

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 00:43
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from a156cb6 to c62ebf2 Compare November 6, 2026 03:59
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • Unused own/unack route — zero consumers span=3f271f633597

removed in c62ebf2: POST /api/notifications/own/unack, its handler, its re-export, its test step and its doc mentions are gone; useAppNotifications() posts only own/ack and own/ack-all, the two routes kept.
The single ack also stops hand-rolling the flip, rewrite and broadcast: after the scope check it calls the bell's own state.ack_notification(ts), as the note on item 2 asked.

@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • Added notification handlers have no corresponding feature-map update span=8ef0489d1123

fixed in c62ebf2: the Notifications row in docs/feature-map/README.md now names the app-scoped list and clear (an app's page through useAppNotifications() in app-sdk/index.ts, its backend through a permissions.api grant) and lists GET /api/notifications/own, POST /api/notifications/own/ack and POST /api/notifications/own/ack-all.

@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97]

  • Failed persistence still reports a successful acknowledgement span=e1c59844cd41

Rebutted: not a defect this PR adds. The notification store's live record is the in-memory log, and its file rewrite is best-effort for every bell mutation on main: set_acknowledged, delete, resolve_skill_reviews, clear and api_notifications_ack_all all flip memory, await the same _rewrite_notifications_async and broadcast; clear documents memory and clients before the durable rewrite.
At c62ebf2 the single own ack calls the bell's own state.ack_notification(ts), so this route adds no writer of its own, and ack-all runs the bell's per-note ack-all sequence over the app's notes.
Both rewrite on every call, so the retry in the finding re-persists instead of being skipped.
Making that rewrite report failure would change the contract of every bell mutation, not this route; the goal (an app's page lists and clears its badge notes) does not need it.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from c62ebf2 to 6333d56 Compare November 6, 2026 06:19
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

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]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from 6333d56 to aface05 Compare November 6, 2026 09:11
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

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]

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 6, 2026
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026
@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from eeb3d5d to 0f3ff8a Compare November 7, 2026 07:57
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Backend Tests (3.12, 2) and Backend Tests (Windows) (2) fail on test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget. This PR does not touch kiro_crew.security; the same test fails on a clean origin/main checkout (0795ebc). The fix is #32183. This PR waits for it and is rebased once it merges. The AI review lanes on this head failed only on the CI token's API rate limit, not on a finding.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 7, 2026
@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from 0f3ff8a to eb18f75 Compare November 7, 2026 13:51
@bolichen97

Copy link
Copy Markdown
Contributor Author

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 PUT /api/agents text) and in the shard 2 line-budget test fixed on main (0f3ff8a -> eb18f75, base f58c3cf); CI re-running.

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

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]

@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from eb18f75 to bd7533e Compare November 8, 2026 23:43
@bolichen97

Copy link
Copy Markdown
Contributor Author

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 POST /api/notifications/own/ack-all: the SDK's ackAll() acks each unread note through POST /api/notifications/own/ack and skips a note the host answers 404 for. The design and first-principles dispositions below record why.

[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the own ack-all repeated the bell's per-note ack-all sequence (set acked, rewrite, broadcast)
resolution: removed -- this PR added that second writer of a note's read state; a per-note ack already clears the badge

removed in bd7533e: the note "Ack-all copies the bell's sequence" no longer applies. POST /api/notifications/own/ack-all and its loop are gone, so every ack of an app's note goes through DashboardState.ack_notification, the bell's own writer.
The SDK keeps ackAll() (issue #26412 asks for it): it acks each unread note it holds through POST /api/notifications/own/ack, then re-reads the list once.

[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: inventory item 3, the own ack-all, duplicated the bell's ack-all loop
resolution: removed -- this PR added the duplicate; a per-note ack already clears, so removal keeps the goal

removed in bd7533e: item 3 ("duplicate of the bell's ack-all loop") is deleted instead of shared. The /own/ack-all route, its handler and re-export are gone, and no second copy of the loop remains.
The SDK's ackAll() stays as issue #26412 asks, built on the per-note ack route, so the bell's ack_notification is the only writer.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 8, 2026
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
@bolichen97
bolichen97 force-pushed the fix/26412-app-own-notifications branch from bd7533e to d326bdd Compare November 9, 2026 00:11
@bolichen97

Copy link
Copy Markdown
Contributor Author

Seam level placed (head d326bdd, on main 41ba859): the own-notes routes and useAppNotifications() are new App Kit surface, so the docs now say which seam level carries them. They are level 4, the current APP_SDK_LEVEL. No release carries level 4 yet (no release branch or tag has apps/app_sdk_level.py), so they join level 4 and the level is not raised, the same way strictSession joined level 2 (app-kit-platform.md §30.1).

  • docs/app-kit/api-reference.md: the seam-level paragraph lists level 4 (the agentTools keys namespace / timeoutSeconds / result, and an app's own bell notes). The own-notes paragraph says both need APP_SDK_LEVEL >= 4 and shows the namespace-import check (sdk.APP_SDK_LEVEL >= 4 && sdk.useAppNotifications).
  • docs/app-kit/getting-started.md (the hook's row) and docs/system-specs/modules/app-notifications.md record the same level.
  • No code changes: this is bd7533e's tree rebuilt on current main plus those doc lines. The parallel driver's push removing own/ack-all is kept as it was. Its queued CI run was cancelled so this head gets one run.

Local gates on this head: related backend tests (216 passed, -n 4), the app-SDK and vendor-stub boundary vitest suites (5/5 with --sequence.shuffle), tsc -p tsconfig.app.json, black, isort, flake8, mypy, comment-history, brand, line-cap, feature-map, flake-pattern ratchet and docs lint all exit 0. Semgrep is not installed on this host, so CI's SAST job is the only Semgrep run.

Retrospective (--rounds exit 30, pr-level SEAM REPEAT): the blocked pushes were main reds, CI rate limits and conflicts, not findings in this code. Every mechanism stays as it is (own-app resolution, list, single ack through ack_notification, refusal audits, the SDK hook). The duplicate ack-all writer was already removed in bd7533e.
resolution: narrowed -- this push changes docs only (the seam level); no code changed

[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

This PR is driven by the built-in app separation campaign (#26967) from now on; other sessions please do not push to it.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ts with the foreign note first, and assert the ack returns 404 and leaves it unacked. Today nothing pins the first-match rule in notifications_push.py around 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-caller mark(action, body) into ack.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Apps cannot read or acknowledge their own bell notifications behind the sidebar badge

3 participants