Ask for notifications from a sidebar card, record setup-guide events, and expose setupComplete

[brsbl]

Human comments

What was wrong

Nothing asks new users for browser or desktop notification permission, even though the push-notifications plugin is on by default. Agents finish or stall while the user is away, and nothing brings them back. We also can't see where people drop off in the setup guide, because server telemetry has no setup-guide or notification-prompt events. And Tips (#4991) needs one shared answer to "has this user finished setting up?"

What changed

Scope follows #5291: there is no "Finish setting up bb" banner or checklist. This PR adds no setting and no reopen state.

Notification card in the sidebar (SidebarNotificationsPrompt, rendered by AppSidebar above the sidebar footer)

• The first time a thread is running, a small card shows "Get a notification when this agent finishes or asks you a question, even in another tab." and a Notify me action. It uses the new shared SidebarNudge (@bb/shared-ui/sidebar-nudge): a bell icon tile, body text only, one action and a dismiss, with more room inside the card and from the sidebar edges. It is styled like the What's new card in Make What's new a built-in plugin with a sidebar card and an easy off switch #4981: no border, a subtle raised fill, and × to dismiss.
• The action requests browser or desktop permission from that click. × means "Not now".
• After either, the card never shows again on that device. It never shows once permission is decided, or when the push-notifications plugin is off. It is hidden while a sidebar-footer disclosure is open or the footer is being customized.
• Stacking with What's new: only one card shows at a time, and the notification card wins because it appears once and only while an agent is working. useSidebarNotificationsPrompt().visible holds the decision in AppSidebar; when Make What's new a built-in plugin with a sidebar card and an easy off switch #4981 lands, PluginSidebarFooterSections renders only while it is false.
• Browser permission state lives in one hook, useNotificationPermission.

Setup guide copy and hierarchy

• Agents step: the header pill reads "Agents" (the step id and events stay agent). The description names the checked machine when it isn't this computer. The footer reads "Don't see your agent? Install any ACP agent, like OpenCode, and bb should pick it up."
• Projects step: the subtitle reads "Repos you've worked in recently on {machine}. We picked this week's." It says "the most recent one" when nothing is from this week, matching the 7-day preselection.
  • New repos come first, under a quiet "{n} of {m} selected" header with Select all / Select none.
  • Already-added repos are a separate checked group instead of "Already added" text.
  • Paths and "Add a folder" are demoted.
• Plugins step: the title is "Give your agents more to work with". The list is Workflows, Browser Automation, Agent Annotations, GitHub, Ask User Question, File Editor, each with a first-session description. Prompt Library is dropped.
• Devices step: the title is "Check on agents away from your desk", with the subtitle "Optional. Also in Settings → Machines."
  • The mobile app is the primary card, led by the push reason, with one Get the app action. On a phone it links to that platform's build; elsewhere it opens an iPhone/Android menu. The card is hidden inside the mobile app.
  • Browser access and another machine are secondary rows.
  • The footer button reads Start your first thread.
• One done treatment: header steps, ready agents, connect "On" and added repos share one check mark in the theme's darker green (--diff-added). --success-foreground renders brown because Chrome mixes in the achromatic ink's 0 hue, so it isn't used.
• Events: onboarding_step_reached fires once per step instead of again on Back. Leaving the Devices route counts as skipped, not completed.

setupComplete for Tips

• useSetupComplete() returns true once the setup guide is finished or skipped (onboardingCompletedAt is set) and the user has created at least one thread.

Setup-guide and notification events (existing server-side PostHog telemetry: anonymous install id, respects telemetryEnabled / BB_TELEMETRY)

• New POST /api/v1/system/telemetry/events and sdk.system.experimental_recordTelemetryEvent, with an entry in docs/api_to_audit.md. The schema is a strict allow-list: unknown events or extra properties return 400.
• onboarding_started: whether an agent was installed or ready at first launch.
• onboarding_step_reached, onboarding_step_completed, onboarding_step_skipped: per step, with entry set to first_run or replay (Settings → Show setup guide).
• onboarding_finished: outcome is completed or skipped, plus last_step.
• notification_prompt_shown, notification_prompt_accepted, notification_prompt_dismissed, notification_prompt_denied: surface is sidebar.
• The Agent step's behavior is unchanged. Its completed/skipped event is derived from agent readiness in OnboardingFlow. The Projects and Plugins steps pass a separate onSkip so their Skip can be told apart; behavior is the same.
• The Settings privacy description, the telemetry section of docs/configuration.md, and /privacy now list what is sent.

Contracts

• All changes are additive: a new route and a new experimental SDK method. Plugin SDK is bumped to 0.6.40 for the new SDK member.
• The push-notifications plugin is unchanged.
• There is no server/daemon wire change, so HOST_DAEMON_PROTOCOL_VERSION is unchanged.

Screenshots

Before: 59a1fcc29f (merge base with main) · After: b75017c645 (PR head) · Captured at 2×

Branch web dev app (pnpm dev) in Chrome for Testing through BB Browser Automation, same data dir for both. The notification nudge is shown through its stored "shown" state, so the sidebar has no running thread. The setup guide was opened from Settings → Show setup guide and walked with Continue and Skip, so nothing was imported.

Screen / state	Viewport	Before	After
Home / notification nudge	Desktop · 1440×900 · light
Home / notification nudge	Desktop · 1440×900 · dark
Sidebar drawer / notification nudge	Mobile · 390×844 · light
Setup guide / Agents	Desktop · 1440×900 · light
Setup guide / Projects	Desktop · 1440×900 · light
Setup guide / Plugins	Desktop · 1440×900 · light
Setup guide / Devices	Desktop · 1440×900 · light
Setup guide / Agents	Mobile · 390×844 · light
Setup guide / Projects	Mobile · 390×844 · light
Setup guide / Plugins	Mobile · 390×844 · light
Setup guide / Devices	Mobile · 390×844 · light
Settings / Privacy & diagnostics	Desktop · 1440×900 · light

How you verified

• Tests added (they run in remote CI):
  • apps/server/test/system/telemetry-events.test.ts: forwards an allowed event; rejects unknown events and extra properties.
  • SidebarNotificationsPrompt.test.tsx: the card shows only once a thread runs and stays until answered; permission is requested only on a click; shown, accepted and dismissed events; hidden when permission is decided or push is off; no re-ask after Not now.
  • useSetupComplete.test.tsx: false before the guide is finished or skipped; false until a thread exists; true after both.
• Manual QA on the branch web dev app (Chrome for Testing):
  • The rows above.
  • The card's action requests permission once, and the card stays hidden after a hard reload.
  • Settings → Show setup guide replays the guide; each step in the table was driven through Continue/Skip.
  • POST /system/telemetry/events returns 200 for a valid event and 400 for an extra property.

Review: I ran one Slop Cop review and a scoped follow-up on moving the prompt into the sidebar. All P1s were fixed: the SDK method is experimental_ with an audit entry, and the prompt no longer re-asks after permission is decided.

P2 follow-ups, not done here:

• The card ignores the plugin's per-channel web/desktop switch.
• Its answered state doesn't sync to other open tabs until they reload.
• Its hook re-renders on every thread-list update.
• The telemetry route has no rate limit.

BB-Thread: Notification card, setup-guide events, setupComplete

AGENT GENERATED

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T19:11:16.122926Z	5c9eca4	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5c9eca4a82

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Prefix and audit the new plugin SDK method

SystemArea is inherited by both PluginBbSdk and PluginBrowserBbSdk, so this adds an unprefixed public plugin API at bb.sdk.system.recordTelemetryEvent and useSdk().system.recordTelemetryEvent. Rename it with an experimental_ prefix and add the required audit and Plugin Guide surface entries before exposing it to plugins.

AGENTS.md reference: AGENTS.md:L28-L30

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove the forbidden route comment

Remove this explanatory JSDoc block: it is a server-contract route comment, not a semantic tool directive or Plugin SDK declaration comment, so it violates the repository's prohibition on code comments.

AGENTS.md reference: AGENTS.md:L11-L11

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Respect the notification channel setting in the checklist

When the push-notifications plugin is enabled but the current client's webEnabled or desktopEnabled setting is false, this still offers permission and later reports “On for this device.” The plugin sender omits disabled channels and its in-thread prompt explicitly checks the per-channel setting, so granting browser permission here cannot make notifications arrive; derive visibility/completion from the active channel setting as well as plugin enablement.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Record checklist notification prompt impressions

Whenever this branch renders the checklist's “Turn on notifications” item, no notification_prompt_shown event is emitted even though subsequent clicks emit accepted, denied, or dismissed events with surface: "checklist". Consequently checklist opt-in analytics have outcomes without an impression denominator; record the shown event once when this item first becomes visible.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Emit onboarding start before the first reached event

On a normal uncached first run, agentStates is initially undefined, so the preceding effect skips onboarding_started while this effect immediately emits onboarding_step_reached; the start event is only sent after the provider query resolves. This reverses the intended funnel order—and omits the start entirely if that query never resolves—so gate or combine the first reached emission until the start payload is available.

Useful? React with 👍 / 👎.