Skip to content

feat(notifications): link agent notes to the session that sent them - #22966

Merged
unstablebrainiac merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:feat/notification-session-link
Oct 22, 2026
Merged

unstablebrainiac merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:feat/notification-session-link

Conversation

@unstablebrainiac

@unstablebrainiac unstablebrainiac commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A bell note an agent sends opens the chat that sent it.

A note an agent publishes with send_notification, or that send_message drops into the bell, does not say which session sent it. Its detail panel shows no Go to chat button, so getting back to the conversation means guessing from the title.

Why it matters

The bell is where unattended agents report. With several sessions running, a note that cannot lead back to its conversation sends the user hunting through the sidebar, or gets ignored.

Not a goal

  • A one-click Open session button on the bell card or the banner. That is a card layout change, left for a follow-up.
  • Linking a cron run that has no tab of its own to the chat that created the cron.
  • App pushes (POST /api/notifications/push) and the notes the gateway writes about a session. Both set their own fields already.

What changed (motivation → approach → change)

An agent's bell note opens the chat that sent it. The detail panel shows Go to chat while that tab is open, and Resume chat once it is closed. A mate's note opens its thread on the Members page, since the chat page does not show mate threads.

The gateway already knows the sender. Both routes read the caller's attested session key, to put a crewmate's face on the note and to apply that session's mute, then drop the key before the note is stored. Notes that keep a slot, such as cron results, heartbeat notes and crewmate messages, already get the detail panel's buttons.

So both routes stamp two fields from that same key, through one resolver, _publishing_session_meta in messaging_api/proactive_send.py: slot, the session's tab while the dashboard holds it, and history_key, that tab's transcript key. Neither comes from the request body. Go to chat reads slot. Resume chat in NotificationDetailPanel.tsx resumes with history_key, and with slot for a note that has none: a bare tab name names no transcript, so resuming chat-2-200 reads a chat-2-200 transcript that does not exist and opens an empty chat.

The chat page shows only ordinary chat tabs, and a mate's DM thread is not one. So both buttons on a note from a mate's thread open /members?member=<name>, the page that thread's sidebar row opens: Go to chat names the open slot's agent (an open thread that names none opens the bare Members page, as its row does), and Resume chat the note's member once the thread has closed, because the Members page holds the mate's one thread. The panel applies the row's rule itself, because only the sidebar may import the sidebar's row model (ChatSidebar.ownerComposition.test.ts). Crewmate message notes, which already carry the mate's thread as slot, get the same Go to chat.

Caller slot history_key
A dashboard chat its own tab dashboard:<tab>
A cron run with its own tab cron-<id> cron:<id>
A cron run with no tab none none
A channel-born chat open in the dashboard its tab the channel's session key
A subagent running in its parent's process the parent's tab (it presents the parent's key) the parent's
An app, or a caller with no attested key none none

Only the sender's own tab counts. The banner skips a note whose slot is the chat on screen. That is right for the chat that wrote the note, which already shows the tool call. It would be wrong for the chat that created a cron, which never shows the cron's output: borrowing its tab would hide the cron's alert while the user sits there. A send_message that offers [OPTIONS:] choices links too, since it is the note most likely to need an answer. A closed cron tab resumes from its cron:<id> transcript, the way the History tab opens it.

docs/system-specs/modules/app-notifications.md documents the link, the feature map's Notifications row names it, and website/src/types/index.chat.ts adds history_key to the Notification type.

Backwards compatibility

Compatible: notes from the two agent routes gain two optional fields, slot, which cron, heartbeat and crewmate notes already carry, and history_key, which the tab hand-over note already carries. A note without history_key resumes by slot, as every note did. No request field, response field or validator changes.

One behaviour goes away: the banner for a note sent by the chat on screen. One changes: Go to chat on a crewmate message note went to the chat page, where a mate's thread does not show, and now opens that thread on the Members page, as the note's Open button does. Every reader of the new fields:

Reader: website/src/hooks/notificationBanner.ts:targetsCurrentView -- chat -- a note whose slot is the focused chat shows no banner, as a heartbeat note does; that chat shows the tool call and the note stays in the bell (NotificationBanner.test.tsx "suppresses a note about the chat on screen while the window is focused")
Reader: website/src/components/notifications/NotificationDetailPanel.tsx:directSlot -- chat -- Go to chat switches to slot, or opens a mate's thread on the Members page; Resume chat opens a closed mate thread there, else resumes with history_key, else slot (NotificationDetailPanel.resumeHistory.test.tsx, NotificationDetailPanel.memberNavigation.test.tsx)
Reader: website/src/components/notifications/notificationHandoff.prompt.ts:buildNotificationPrompt -- chat -- the hand-off prompt names the session by its tab (- Session: <slot>)
Reader: src/kiro_crew/dashboard/ws_event_scope.py:_decide_ws_event -- app -- a notification frame is judged by its notification scope; its slot is ignored for slot scoping and history_key is not read, so the frame reaches the same apps as before

Tests

  • test/test_notification_session_link.py (new): slot and history_key for each caller in the table, both routes stamping them, a request body that cannot choose them, an unattested caller that gets neither, a send_message offering choices that still links, and a closed session that resumes its messages through the real resume route by the note's history_key.
  • website/src/test/NotificationDetailPanel.resumeHistory.test.tsx (new): Resume chat resumes with history_key, and with slot for a note that has none.
  • website/src/test/NotificationDetailPanel.memberNavigation.test.tsx (new): Go to chat on an open mate thread opens /members?member=<name> without switching the chat pane, Resume chat on a closed one opens the same page without resuming a transcript, an open thread that names no mate opens the bare Members page, a closed one whose note names no mate resumes from history, and an ordinary chat still opens on the chat page.
  • test/test_dashboard_file_io.py: the two send_message tests that assert the exact state.notify call expect meta=None for a caller with no session.
  • test/test_proactive_send_source_line.py: its fake slot carries the key every real slot has, which the note's history_key reads.
  • Each of these breaks a test: dropping the link on either route, dropping the open-tab check, trusting the bare X-Session-Key header, linking only notes that can be muted, borrowing a cron's creator tab, dropping history_key, a panel that resumes by slot when the note has history_key, and a panel that sends a mate's note to the chat page from either button, names the wrong mate, sends an open thread that names no mate to the chat page, or sends a closed one whose note names no mate to the Members page.
  • Determinism: the Python tests ran 20 times at -n0, 10 at -n 4 --dist loadgroup beside test_notification_publisher_mute.py and test_notification_crewmate_member.py, and in a shuffled order (seed 7317, 84 passed); NotificationDetailPanel.memberNavigation.test.tsx ran 10 times, and the four NotificationDetailPanel test files ran shuffled together (seed 7317, 18 passed). All green.

Manual verification

Not run live. Both routes run under aiohttp's TestServer with the auth marks the middleware sets, and the closed-tab case runs end to end: the note is published through the agent route, the tab is removed, and the real resume route returns the session's messages. The panel's changes are which key Resume chat sends and which page a mate's note opens, each pinned by its test.

Screenshots / video

Captured from this branch's built SPA with the dashboard API stubbed, the method website/scripts/capture-notification-go-to-chat.mjs uses. Each note carries the fields the two routes stamp: slot and history_key, plus member on a mate's note. The capture script checks each state before it saves a frame, including that Resume Chat sends the history key dashboard:chat-12-1792700000 and not the tab name.

An agent's note while its chat is open shows one Go to Chat button:

Detail panel of an agent's note with its chat open, showing Go to Chat

The same note after its chat is closed shows Resume Chat, which reopens the chat with its transcript:

Detail panel of the same note with its chat closed, showing Resume Chat

The resumed chat showing both of its messages

A mate's note: Go to Chat opens that mate's thread on the Members page. Once the thread is closed, Resume Chat opens the same page.

Detail panel of a mate's note showing Go to Chat

The Members page open on the mate's thread

Related Issues

Closes #22941

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 added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 21, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

UX-level review of 28157c7df344a6380806904b614eeb8d89216693 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

cannot evaluate: missing a screenshot of the notification detail panel for an agent-sent note. The PR makes Go to chat / Resume chat appear on those notes and sends mate notes to the Members page, but attaches no images.

Evidence gaps

  • Go to chat on an agent's send_notification / send_message note (sender's tab open). The backend now stamps slot, so NotificationDetailPanel.tsx renders this button on notes where it never appeared before. Close the gap with a screenshot of the bell detail panel for such a note.
  • Resume chat on the same note after its tab is closed. This button now resumes by history_key. Close the gap with a screenshot of the panel, plus the resumed chat showing its transcript rather than an empty chat.
  • Go to chat / Resume chat on a mate-thread note, now opening /members?member=<name> instead of /chat. Close the gap with a screenshot of the panel and the Members page it lands on, showing the mate's thread selected.

Notes

  • The Go to chat label (go_to_chat) now leads to the Members page for mate notes. A mate-specific label would keep the promise for those notes, for example "Open thread with ".
  • A note sent by the chat that is on screen no longer shows a banner. That behaviour has no visible cue either, so a before/after screenshot of the bell would show the note still lands there.

[UX-REVIEWED] 28157c7

Description read

[DESCRIPTION-READ] 2a0a8f8f2a1325d19ac43454e86ab86498b7ae2b93745758708929baa14e6d5e

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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 28157c7df344a6380806904b614eeb8d89216693 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: both agent routes take the link from the sender's attested key through one resolver. An unattested caller gets no link, and so does a cron run with no tab of its own.

Notes

  • When the stored history_key is set, the Members-page decision checks the member- prefix on the bare slot. If no member is named, it falls back to history. These two inputs could disagree, so a server-stamped mate marker on the note would be sturdier.
  • No screenshot is attached. The Go to chat and Resume chat buttons already exist and only appear on more notes, so this is not a new or reshaped surface. The UX lane may still ask for a screenshot of an agent note's detail panel with the button showing.

[DESIGN-REVIEWED] 28157c7

Description read

[DESCRIPTION-READ] 694d406e1cc2ebe405ff69084d451a7f2abf46c5b1e48e40b7cc2a6d07b0a438

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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 28157c7df344a6380806904b614eeb8d89216693 via the fork AI-review pipeline — 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 new resolver is built from helpers that already exist (dashboard_slot_key, slot_history_key, attributable_session_key), and both agent routes use it.

What this change ships

Inventory (8 items) — 7 justified

Intent: a bell note an agent sends opens the chat that sent it. This is an ADDITION.

  1. A send_notification note shows Go to chat for the sender's open tab — justified
  2. A send_message bell copy links back the same way, including one that offers choices — justified
  3. Once that tab closes, Resume chat opens the sender's transcript instead of an empty chat — justified
  4. A note from a mate's thread opens /members?member=<name> from both buttons — justified
  5. Go to chat on an existing crewmate message note now opens the Members page instead of the chat page — rides along (declared; the thread does not show on the chat page)
  6. No banner for a note sent by the chat on screen — justified
  7. The spec section and the feature-map row describe the link — justified
  8. The Notification type gains history_key — justified

[FIRST-PRINCIPLES-REVIEWED] 28157c7

Description read

[DESCRIPTION-READ] e4eac4001f52111e50f9365ec0a5d62737bc3066a970873662406c026b3aefe0

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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 28157c7df344a6380806904b614eeb8d89216693 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 28157c7

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 28157c7df344a6380806904b614eeb8d89216693 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 28157c7

@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 Oct 22, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/notification-session-link branch from 6bf8496 to 27d6414 Compare October 22, 2026 01:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 Oct 22, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/notification-session-link branch from 27d6414 to ae0da04 Compare October 22, 2026 04:07
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 22, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/notification-session-link branch from ae0da04 to c477764 Compare October 22, 2026 05:46
@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 Oct 22, 2026
A note an agent publishes with send_notification, and the bell copy of
send_message, did not say which session published it, so the detail
panel offered no way back to the conversation. Both routes set the
note's slot and history_key from the caller's attested session key,
when the dashboard holds that session's tab. Go to chat reads slot.
Resume chat resumes with history_key: a bare slot name names no
transcript, so resuming by it opens an empty chat. A mate's note opens
its thread on the Members page instead, as its sidebar row does, since
the chat page does not show mate threads. A cron run with no tab of its
own gets no link: the banner hides a note whose slot is the chat on
screen, and the chat that created the cron never shows the cron's
output.
@unstablebrainiac
unstablebrainiac force-pushed the feat/notification-session-link branch from c477764 to 28157c7 Compare October 22, 2026 07:37
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 22, 2026
@unstablebrainiac
unstablebrainiac enabled auto-merge (squash) October 22, 2026 09:27
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 28157c7.

The change itself looks sound. _publishing_session_meta stamps slot and history_key only from the caller's attested session key, and only for a tab the dashboard holds. A request body cannot point a note at another session. All checks are green, and Opus, GPT and First Principles have no open items.

What blocks: two lanes on this head have items with no reply.

  • UX asks for screenshots of three things: Go to chat on an agent note, Resume chat after the tab closes, and a mate note opening the Members page. The no-visual-delta waiver says the panel looks the same, but these buttons now appear on notes that never had them. UX also suggests a mate-specific label for Go to chat.
  • Design notes that the Members-page choice reads the bare slot prefix while Resume reads history_key, so the two could disagree.

What clears it: attach the screenshots, or reply to each item with a reason. If any item becomes a follow-up, link an issue for it.

I read the diff and CI. I did not run tests.

— crew-pr-reviewer (r120)

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 22, 2026
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author
  • UX headline, no screenshot of the panel for an agent-sent note: addressed

The description's Screenshots / video section now carries five frames from this branch's built SPA with the dashboard API stubbed. The capture script checks each state before it saves a frame.
Go to Chat on an agent's note with its chat open is the first frame. Resume Chat after the chat closes and the reopened chat with its transcript are the next two, and the script checks that the resume request sends the history key, not the tab name. A mate's note and the Members page it opens on that mate's thread are the last two; with the thread closed, Resume Chat opens the same page.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author
  • UX note on a mate-specific label for Go to Chat: kept

The click opens a chat with that mate: the Members page shows the mate's thread and its composer, the same thread the mate's sidebar row opens (the last frame). The note already shows the mate's face and name, so Go to Chat names what happens.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author
  • UX note on the banner a note from the on-screen chat no longer shows: kept

Only the pop-up card is skipped. shouldBannerNote returns false through targetsCurrentView when the window is focused on the chat the note's slot names, and every false there leaves the note in the bell with its unread dot (notificationBanner.ts). Cron and heartbeat notes already take this path, so the bell renders nothing new to capture.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author
  • Design note on the Members-page choice reading slot while Resume reads history_key: rebutted

The two cannot disagree. _publishing_session_meta takes both from the one slot the attested caller holds. While the thread is open, the panel reads that slot's mode; once it is closed, it reads the member- prefix, which only a mate thread can carry: slot_registry.py refuses a member- key for any other slot, and resume refuses to restore a mate thread's transcript under any other key.
The note already carries a server-stamped mate marker: member, set from the same attested key, whose name the closed-thread link uses. history_key is read only when the panel does not open the Members page.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author
  • Design note on the missing screenshot: addressed

The description's Screenshots / video section now carries five frames: Go to Chat and Resume Chat on an agent's note, the reopened chat with its transcript, and a mate's note with the Members page it opens.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving 28157c7.

The link back to the sender is safe. _publishing_session_meta takes slot and history_key only from the caller's attested session key, and only for a tab the dashboard holds, so a request body cannot point a note at another session (proactive_send.py#L147-L164). Every r120 item now has a reply. The five screenshots are in the description, and the label and banner notes have reasons. The Design rebuttal holds: slot_registry.py refuses a member- key for any non-member slot (slot_registry.py#L221), so the Members-page choice and history_key cannot disagree.

All lanes pass, and GPT and Opus report no findings. CI is green: 99 checks pass or are skipped, plus PR Readiness. The branch is 69 commits behind main, but a trial merge with current main is clean, and the new wiring in handlers/messaging.py survives #23052.

Reviewed head: 28157c7

— crew-pr-reviewer (r121)

@unstablebrainiac
unstablebrainiac merged commit 4ef2a92 into kirodotdev:main Oct 22, 2026
113 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Agent notifications should link back to the session that sent them

2 participants