From 9d79b4eef740fc6942748d122bf19f58e4c8eefd Mon Sep 17 00:00:00 2001 From: Kelvin Amoaba <97001695+AmoabaKelvin@users.noreply.github.com> Date: Sun, 1 Nov 2026 15:24:51 +0000 Subject: [PATCH] feat(notifications): separate agent needs-input alerts from finished alerts --- mobile/src/i18n/locales/en.json | 4 ++- .../NotificationDeliverySection.test.tsx | 1 + .../NotificationDeliverySection.tsx | 11 +++++++ .../mobile-notifications.test.ts | 26 +++++++++++++++-- .../src/notifications/mobile-notifications.ts | 2 ++ .../notification-delivery-preferences.test.ts | 3 ++ .../notification-delivery-preferences.ts | 3 ++ mobile/src/notifications/push-payload.ts | 6 +++- mobile/src/notifications/push-receive.test.ts | 27 +++++++++++++++++ mobile/src/notifications/push-receive.ts | 23 ++++++++++----- .../notifications/push-registration.test.ts | 2 +- .../ipc/notifications-macos-removal.test.ts | 1 + .../notifications-message-formatting.test.ts | 2 ++ ...otifications-permission-onboarding.test.ts | 1 + .../notifications-subject-retirement.test.ts | 1 + .../notification-delivery-service.test.ts | 20 +++++++++++++ .../notification-delivery-service.ts | 10 ++++--- ...otification-settings-normalization.test.ts | 15 ++++++++++ .../onboarding-normalization.ts | 5 ++++ ...ersistence-floating-terminal-trust.test.ts | 1 + .../runtime/push/push-delivery-policy.test.ts | 13 +++++++++ ...red-agent-session-mobile-attention.test.ts | 16 +++++++--- ...ructured-agent-session-mobile-attention.ts | 7 ++++- ...tured-agent-session-mobile-restore.test.ts | 1 + ...ed-agent-session-mobile-retirement.test.ts | 1 + .../runtime/terminal-agent-phone-push.test.ts | 2 ++ src/main/runtime/terminal-agent-phone-push.ts | 4 ++- .../use-onboarding-flow-persistence.test.ts | 2 ++ .../use-onboarding-flow-persistence.ts | 1 + .../settings/NotificationsPane.test.tsx | 1 + .../components/settings/NotificationsPane.tsx | 21 +++++++++++++- .../settings/notifications-search.ts | 29 +++++++++++++++++++ ...wser-link-materialization.test-fixture.tsx | 1 + src/renderer/src/i18n/locales/en.json | 11 +++++-- src/shared/mobile-push-alert.ts | 20 ++++++++++++- src/shared/mobile-push-contract.ts | 6 ++++ src/shared/notification-settings-defaults.ts | 1 + src/shared/notification-settings-types.ts | 2 ++ src/shared/notification-source-gate.ts | 27 +++++++++++++++++ .../rpc-contract/notifications-params.ts | 1 + ...ttention-host-read-retirement.unit.test.ts | 1 + ...attention-read-retirement.test-fixture.tsx | 1 + 42 files changed, 306 insertions(+), 27 deletions(-) create mode 100644 src/shared/notification-source-gate.ts diff --git a/mobile/src/i18n/locales/en.json b/mobile/src/i18n/locales/en.json index 55f35fafb9d4..43ce58e481e5 100644 --- a/mobile/src/i18n/locales/en.json +++ b/mobile/src/i18n/locales/en.json @@ -722,7 +722,9 @@ "sound": "Notification sound", "suppressWhileFocused": "Suppress while focused", "suppressWhileFocusedHint": "Skip alerts for the workspace open on this phone.", - "footer": "Alert types follow each paired desktop’s notification settings. Notifications pause after 7 days without using this app; open it and reconnect to resume." + "footer": "Alert types follow each paired desktop’s notification settings. Notifications pause after 7 days without using this app; open it and reconnect to resume.", + "onlyWhenAgentNeedsInput": "Only when an agent needs me", + "onlyWhenAgentNeedsInputHint": "Permission requests and questions. Skips finished agents." }, "desktopChannel": { "silentName": "Orca silent notifications", diff --git a/mobile/src/notifications/NotificationDeliverySection.test.tsx b/mobile/src/notifications/NotificationDeliverySection.test.tsx index bbfaf3b58441..2095755800f3 100644 --- a/mobile/src/notifications/NotificationDeliverySection.test.tsx +++ b/mobile/src/notifications/NotificationDeliverySection.test.tsx @@ -32,6 +32,7 @@ it('shows only phone-specific controls while desktop owns category eligibility', const switches = () => findAllByHostType(renderer.root, 'Switch') expect(switches().map((node) => node.props.accessibilityLabel)).toEqual([ 'Only when away from desktop', + 'Only when an agent needs me', 'Notification sound', 'Suppress while focused' ]) diff --git a/mobile/src/notifications/NotificationDeliverySection.tsx b/mobile/src/notifications/NotificationDeliverySection.tsx index 385f0ed9dc75..1d8c524b3152 100644 --- a/mobile/src/notifications/NotificationDeliverySection.tsx +++ b/mobile/src/notifications/NotificationDeliverySection.tsx @@ -46,6 +46,17 @@ export function NotificationDeliverySection({ value, disabled, onChange }: Props 'After 3 minutes without keyboard or mouse activity, or when locked.' ) )} + {row( + 'onlyWhenAgentNeedsInput', + t( + 'notifications.notificationDeliverySection.onlyWhenAgentNeedsInput', + 'Only when an agent needs me' + ), + t( + 'notifications.notificationDeliverySection.onlyWhenAgentNeedsInputHint', + 'Permission requests and questions. Skips finished agents.' + ) + )} {row('sound', t('notifications.notificationDeliverySection.sound', 'Notification sound'))} {row( 'suppressWhileViewing', diff --git a/mobile/src/notifications/mobile-notifications.test.ts b/mobile/src/notifications/mobile-notifications.test.ts index 51144921c668..2afeca3d37fa 100644 --- a/mobile/src/notifications/mobile-notifications.test.ts +++ b/mobile/src/notifications/mobile-notifications.test.ts @@ -14,7 +14,12 @@ const fallback = vi.hoisted(() => ({ completion: { completed: Promise.resolve(true), signal: new AbortController().signal }, eligible: vi.fn(), schedule: vi.fn(), - preferences: { onlyWhenDesktopAway: true, sound: true, suppressWhileViewing: true } + preferences: { + onlyWhenDesktopAway: true, + onlyWhenAgentNeedsInput: false, + sound: true, + suppressWhileViewing: true + } })) vi.mock('./push-token', () => ({ getDevicePushToken: fallback.token })) vi.mock('./push-registration', () => ({ @@ -167,7 +172,12 @@ beforeEach(() => { fallback.supported.mockReturnValue(true) fallback.eligible.mockResolvedValue(true) fallback.schedule.mockResolvedValue('local') - fallback.preferences = { onlyWhenDesktopAway: true, sound: true, suppressWhileViewing: true } + fallback.preferences = { + onlyWhenDesktopAway: true, + onlyWhenAgentNeedsInput: false, + sound: true, + suppressWhileViewing: true + } }) const liveAlert = { @@ -255,6 +265,18 @@ it.each([ expect(fallback.schedule).not.toHaveBeenCalled() }) +it('presents only agent questions when the phone wants nothing else, on any host', async () => { + fallback.token.mockResolvedValue(null) + fallback.preferences = { ...fallback.preferences, onlyWhenAgentNeedsInput: true } + emitAlert({ ...liveAlert, agentState: 'done' }) + emitAlert({ ...liveAlert, agentState: 'blocked', notificationSeq: 5 }) + await vi.waitFor(() => expect(fallback.schedule).toHaveBeenCalledOnce()) + // Foreground eligibility re-reads the kind from this data, so it must carry it. + expect(fallback.schedule.mock.calls[0][0]).toMatchObject({ + content: { data: { source: 'agent-task-complete', agentState: 'needs-input' } } + }) +}) + it('delegates foreground eligibility before scheduling', async () => { fallback.token.mockResolvedValue(null) fallback.eligible.mockResolvedValue(false) diff --git a/mobile/src/notifications/mobile-notifications.ts b/mobile/src/notifications/mobile-notifications.ts index 7470cf3d7bfa..2b2e74ab5974 100644 --- a/mobile/src/notifications/mobile-notifications.ts +++ b/mobile/src/notifications/mobile-notifications.ts @@ -96,6 +96,8 @@ export function subscribeToDesktopNotifications(client: RpcClient, hostId: strin worktreeId: event.worktreeId, paneKey: event.paneKey, executionHost: event.executionHost, + source: content.source, + ...(content.agentState ? { agentState: content.agentState } : {}), channelId } }, diff --git a/mobile/src/notifications/notification-delivery-preferences.test.ts b/mobile/src/notifications/notification-delivery-preferences.test.ts index 1e3e4b791138..f5e4f43a3364 100644 --- a/mobile/src/notifications/notification-delivery-preferences.test.ts +++ b/mobile/src/notifications/notification-delivery-preferences.test.ts @@ -38,6 +38,7 @@ it('persists only phone-specific delivery preferences', async () => { expect(await loadNotificationDeliveryPreferences()).toEqual(value) expect(notificationPreferencesFilter(value)).toEqual({ onlyWhenDesktopAway: false, + onlyWhenAgentNeedsInput: false, sound: false }) }) @@ -54,11 +55,13 @@ it('ignores unrelated stored preferences', async () => { ) expect(await loadNotificationDeliveryPreferences()).toEqual({ onlyWhenDesktopAway: false, + onlyWhenAgentNeedsInput: false, sound: false, suppressWhileViewing: false }) expect(notificationPreferencesFilter(await loadNotificationDeliveryPreferences())).toEqual({ onlyWhenDesktopAway: false, + onlyWhenAgentNeedsInput: false, sound: false }) }) diff --git a/mobile/src/notifications/notification-delivery-preferences.ts b/mobile/src/notifications/notification-delivery-preferences.ts index 7388fba77db0..a58e059fc152 100644 --- a/mobile/src/notifications/notification-delivery-preferences.ts +++ b/mobile/src/notifications/notification-delivery-preferences.ts @@ -4,12 +4,14 @@ import type { MobilePushFilter } from '../../../src/shared/mobile-push-contract' const KEY = 'orca:notificationDeliveryPreferences' export type NotificationDeliveryPreferences = { onlyWhenDesktopAway: boolean + onlyWhenAgentNeedsInput: boolean sound: boolean suppressWhileViewing: boolean } export const DEFAULT_NOTIFICATION_DELIVERY: NotificationDeliveryPreferences = { onlyWhenDesktopAway: true, + onlyWhenAgentNeedsInput: false, sound: true, suppressWhileViewing: true } @@ -44,6 +46,7 @@ export function notificationPreferencesFilter( ): MobilePushFilter { return { onlyWhenDesktopAway: value.onlyWhenDesktopAway, + onlyWhenAgentNeedsInput: value.onlyWhenAgentNeedsInput, sound: value.sound } } diff --git a/mobile/src/notifications/push-payload.ts b/mobile/src/notifications/push-payload.ts index 878772f29b52..556356209b2e 100644 --- a/mobile/src/notifications/push-payload.ts +++ b/mobile/src/notifications/push-payload.ts @@ -8,6 +8,8 @@ export type OrcaPushPayload = { readonly paneKey?: string readonly worktreeId?: string readonly executionHost?: string + readonly source?: string + readonly agentState?: string } function readString(value: unknown): string | undefined { @@ -38,6 +40,8 @@ export function readOrcaPushPayload(data: unknown): OrcaPushPayload | null { notificationEpoch: readString(record.notificationEpoch), paneKey: readString(record.paneKey), worktreeId: readString(record.worktreeId), - executionHost: readString(record.executionHost) + executionHost: readString(record.executionHost), + source: readString(record.source), + agentState: readString(record.agentState) } } diff --git a/mobile/src/notifications/push-receive.test.ts b/mobile/src/notifications/push-receive.test.ts index bcfd2d083690..36d42020c513 100644 --- a/mobile/src/notifications/push-receive.test.ts +++ b/mobile/src/notifications/push-receive.test.ts @@ -69,6 +69,33 @@ describe('shouldSuppressForegroundPush', () => { notificationEpoch: 'epoch-1' }) + it('drops an older host’s finished-agent push but keeps questions, bells and the push test', async () => { + storage.set( + 'orca:notificationDeliveryPreferences', + JSON.stringify({ onlyWhenAgentNeedsInput: true }) + ) + const alert = (seq: number, agentState: string) => + apnsData({ + hostFingerprint, + notificationSeq: seq, + notificationEpoch: 'epoch-1', + source: 'agent-task-complete', + agentState + }) + await expect(shouldSuppressForegroundPush(alert(1, 'finished'))).resolves.toBe(true) + await expect(shouldSuppressForegroundPush(alert(2, 'needs-input'))).resolves.toBe(false) + await expect( + shouldSuppressForegroundPush( + fcmData({ + hostFingerprint, + notificationSeq: 3, + notificationEpoch: 'epoch-1', + source: 'terminal-bell' + }) + ) + ).resolves.toBe(false) + }) + it('allows one eligible native push and suppresses an in-process duplicate', async () => { await expect(shouldSuppressForegroundPush(push())).resolves.toBe(false) await expect(shouldSuppressForegroundPush(push())).resolves.toBe(true) diff --git a/mobile/src/notifications/push-receive.ts b/mobile/src/notifications/push-receive.ts index d53e83d01f45..e57d3e42978b 100644 --- a/mobile/src/notifications/push-receive.ts +++ b/mobile/src/notifications/push-receive.ts @@ -7,7 +7,11 @@ import { resolveHostIdForFingerprint } from './push-host-fingerprint' import { readOrcaPushPayload, type OrcaPushPayload } from './push-payload' import type { NotificationBehavior } from 'expo-notifications' import { readNativeNotificationData } from './native-notification-data' -import { loadNotificationDeliveryPreferences } from './notification-delivery-preferences' +import { + loadNotificationDeliveryPreferences, + type NotificationDeliveryPreferences +} from './notification-delivery-preferences' +import { allowsMobilePushAlertKind } from '../../../src/shared/mobile-push-alert' const RECENT_FOREGROUND_PUSH_CAP = 512 const recentForegroundPushes = new Set() @@ -52,10 +56,9 @@ export async function foregroundNotificationBehavior(notification: { const payload = readOrcaPushPayload(data) const preferences = await loadNotificationDeliveryPreferences() // Preserve unknown notifications; recognized pushes fail closed when eligibility/dismissal checks cannot complete. - const ineligible = await shouldSuppressForegroundPush( - payload, - preferences.suppressWhileViewing - ).catch(() => payload !== null) + const ineligible = await shouldSuppressForegroundPush(payload, preferences).catch( + () => payload !== null + ) const suppressed = ineligible || (payload !== null && !claimForegroundPush(payload)) return { shouldShowBanner: !suppressed, @@ -67,7 +70,7 @@ export async function foregroundNotificationBehavior(notification: { export async function canPresentForegroundPush(payload: OrcaPushPayload): Promise { const preferences = await loadNotificationDeliveryPreferences() - return !(await shouldSuppressForegroundPush(payload, preferences.suppressWhileViewing)) + return !(await shouldSuppressForegroundPush(payload, preferences)) } async function resolvePushHostId(payload: OrcaPushPayload): Promise { @@ -77,7 +80,7 @@ async function resolvePushHostId(payload: OrcaPushPayload): Promise { if (!payload) { return false @@ -92,6 +95,10 @@ async function shouldSuppressForegroundPush( } return true } + // An older host ignores this registration filter, so its pushes are filtered here too. + if (!allowsMobilePushAlertKind(preferences, payload.source, payload.agentState)) { + return true + } const hostId = await resolvePushHostId(payload) // Suppress removed-host pushes: stale gateway registrations cannot route a useful tap and the phone can no longer disable them per host. if (!hostId) { @@ -100,7 +107,7 @@ async function shouldSuppressForegroundPush( if (!(await loadPushNotificationsEnabled())) { return true } - if (shouldSuppressNotificationWhileViewing(payload, hostId, suppressWhileViewing)) { + if (shouldSuppressNotificationWhileViewing(payload, hostId, preferences.suppressWhileViewing)) { return true } // Keep this last: a socket/native dismissal may land during any preference or host read. diff --git a/mobile/src/notifications/push-registration.test.ts b/mobile/src/notifications/push-registration.test.ts index c4992d7fd698..4711aee061cc 100644 --- a/mobile/src/notifications/push-registration.test.ts +++ b/mobile/src/notifications/push-registration.test.ts @@ -118,7 +118,7 @@ describe('push registration capability gating', () => { platform: 'ios', token: IOS_TOKEN.token, apnsEnvironment: 'production', - filter: { onlyWhenDesktopAway: true, sound: true } + filter: { onlyWhenDesktopAway: true, onlyWhenAgentNeedsInput: false, sound: true } }) expect(stored.registeredHostIds).toEqual(['host-1']) }) diff --git a/src/main/ipc/notifications-macos-removal.test.ts b/src/main/ipc/notifications-macos-removal.test.ts index db62734111aa..b85f0c63b9c6 100644 --- a/src/main/ipc/notifications-macos-removal.test.ts +++ b/src/main/ipc/notifications-macos-removal.test.ts @@ -55,6 +55,7 @@ function register(): void { notifications: { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false } diff --git a/src/main/ipc/notifications-message-formatting.test.ts b/src/main/ipc/notifications-message-formatting.test.ts index 5d619cc144f7..a557954879a6 100644 --- a/src/main/ipc/notifications-message-formatting.test.ts +++ b/src/main/ipc/notifications-message-formatting.test.ts @@ -67,11 +67,13 @@ describe('registerNotificationHandlers', () => { }) it('formats blocked and interrupted agent snapshots distinctly', async () => { + // oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the handlers read only getSettings().notifications from the store. registerNotificationHandlers({ getSettings: () => ({ notifications: { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: false, suppressWhenFocused: false } diff --git a/src/main/ipc/notifications-permission-onboarding.test.ts b/src/main/ipc/notifications-permission-onboarding.test.ts index fa4ae1e9034d..ca74eb12859a 100644 --- a/src/main/ipc/notifications-permission-onboarding.test.ts +++ b/src/main/ipc/notifications-permission-onboarding.test.ts @@ -66,6 +66,7 @@ describe('notifications:probeDelivery', () => { notifications: { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false } diff --git a/src/main/ipc/notifications-subject-retirement.test.ts b/src/main/ipc/notifications-subject-retirement.test.ts index 848302af6f62..c3374b5b7ae6 100644 --- a/src/main/ipc/notifications-subject-retirement.test.ts +++ b/src/main/ipc/notifications-subject-retirement.test.ts @@ -65,6 +65,7 @@ function register( notifications: { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: options.suppressWhenFocused } diff --git a/src/main/notifications/notification-delivery-service.test.ts b/src/main/notifications/notification-delivery-service.test.ts index d7257db4e021..3cdd90ad78f9 100644 --- a/src/main/notifications/notification-delivery-service.test.ts +++ b/src/main/notifications/notification-delivery-service.test.ts @@ -17,6 +17,7 @@ function makeSettings(overrides: Partial = {}): Notificati return { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false, customSoundId: 'system', @@ -117,6 +118,25 @@ describe('createNotificationDeliveryService', () => { expect(harness.order).toEqual(['tray', 'mobile']) }) + it('gates agent questions on needs-input and finished turns on task-complete', () => { + const harness = makeHarness(makeSettings({ agentTaskComplete: false })) + const service = createNotificationDeliveryService(harness.deps) + expect(service.dispatch(makeRequest({ agentState: 'blocked' }))).toEqual({ delivered: true }) + expect( + service.dispatch( + makeRequest({ agentState: 'done', worktreeId: 'wt-2', worktreeLabel: 'wt-2' }) + ) + ).toEqual({ delivered: false, reason: 'source-disabled' }) + + const quiet = makeHarness(makeSettings({ agentNeedsInput: false })) + expect( + createNotificationDeliveryService(quiet.deps).dispatch(makeRequest({ agentState: 'waiting' })) + ).toEqual({ delivered: false, reason: 'source-disabled' }) + expect(quiet.dispatchMobileNotification).toHaveBeenCalledWith( + expect.objectContaining({ desktopAllowed: false, agentState: 'waiting' }) + ) + }) + it('keeps the desktop source gates distinct per source', () => { const harness = makeHarness(makeSettings({ terminalBell: false })) const service = createNotificationDeliveryService(harness.deps) diff --git a/src/main/notifications/notification-delivery-service.ts b/src/main/notifications/notification-delivery-service.ts index 4893e0799ef6..73821f1e9e4a 100644 --- a/src/main/notifications/notification-delivery-service.ts +++ b/src/main/notifications/notification-delivery-service.ts @@ -10,6 +10,7 @@ import { buildNotificationOptions } from '../ipc/notification-options' import { translateMain } from '../i18n/main-i18n' import { reserveNotificationCooldown } from '../../shared/notification-burst-cooldown' import { toHostSessionPaneKey } from '../../shared/terminal-surface-id' +import { isNotificationSourceEnabled } from '../../shared/notification-source-gate' export type NotificationDeliveryDependencies = { readNotificationSettings: () => NotificationSettings @@ -78,10 +79,11 @@ export function createNotificationDeliveryService( request.notificationSourceId !== undefined && settings.mutedNotificationSourceIds.includes(request.notificationSourceId) // Machine mutes leave mobile eligibility and its cooldown unchanged. - const desktopAllowed = - settings.enabled && - (request.source !== 'agent-task-complete' || settings.agentTaskComplete) && - (request.source !== 'terminal-bell' || settings.terminalBell) + const desktopAllowed = isNotificationSourceEnabled( + settings, + request.source, + request.agentState + ) const notificationOptions = buildNotificationOptions(request, translateMain) diff --git a/src/main/persistence/applying-settings/notification-settings-normalization.test.ts b/src/main/persistence/applying-settings/notification-settings-normalization.test.ts index 90e33d5aa3f9..981ae9e3448c 100644 --- a/src/main/persistence/applying-settings/notification-settings-normalization.test.ts +++ b/src/main/persistence/applying-settings/notification-settings-normalization.test.ts @@ -47,3 +47,18 @@ describe('muted notification machines', () => { expect(persistedNotificationSettingsRepaired(persisted, normalized)).toBe(true) }) }) + +describe('agent needs-input notifications', () => { + it('inherits the old shared toggle on upgrade, then stands on its own', () => { + const { agentNeedsInput: _absentBeforeUpgrade, ...upgraded } = { + ...getDefaultNotificationSettings(), + agentTaskComplete: false + } + expect(normalizeNotificationSettings(upgraded).agentNeedsInput).toBe(false) + expect(normalizeNotificationSettings({}).agentNeedsInput).toBe(true) + expect( + normalizeNotificationSettings({ agentTaskComplete: false, agentNeedsInput: true }) + .agentNeedsInput + ).toBe(true) + }) +}) diff --git a/src/main/persistence/applying-settings/onboarding-normalization.ts b/src/main/persistence/applying-settings/onboarding-normalization.ts index 02046faa1510..d2a1fe64c677 100644 --- a/src/main/persistence/applying-settings/onboarding-normalization.ts +++ b/src/main/persistence/applying-settings/onboarding-normalization.ts @@ -49,6 +49,11 @@ export function normalizeNotificationSettings(value: unknown): NotificationSetti return { enabled: booleanOr(candidate.enabled, defaults.enabled), agentTaskComplete: booleanOr(candidate.agentTaskComplete, defaults.agentTaskComplete), + // Upgrades inherit the old shared toggle so turning completions off never starts new alerts. + agentNeedsInput: booleanOr( + candidate.agentNeedsInput, + booleanOr(candidate.agentTaskComplete, defaults.agentNeedsInput) + ), terminalBell: booleanOr(candidate.terminalBell, defaults.terminalBell), suppressWhenFocused: booleanOr(candidate.suppressWhenFocused, defaults.suppressWhenFocused), customSoundId, diff --git a/src/main/persistence/terminal-topology/persistence-floating-terminal-trust.test.ts b/src/main/persistence/terminal-topology/persistence-floating-terminal-trust.test.ts index 87d5ea3dc97b..6b7c838159f8 100644 --- a/src/main/persistence/terminal-topology/persistence-floating-terminal-trust.test.ts +++ b/src/main/persistence/terminal-topology/persistence-floating-terminal-trust.test.ts @@ -269,6 +269,7 @@ describe('Store', () => { expect(store.getSettings().notifications).toMatchObject({ enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: false, suppressWhenFocused: true, customSoundPath: '/Users/kaylee/Downloads/Note_block_pling.ogg', diff --git a/src/main/runtime/push/push-delivery-policy.test.ts b/src/main/runtime/push/push-delivery-policy.test.ts index 514b76b63d12..ef17a699c019 100644 --- a/src/main/runtime/push/push-delivery-policy.test.ts +++ b/src/main/runtime/push/push-delivery-policy.test.ts @@ -16,6 +16,19 @@ it('does not send or consume cooldown while the desktop is active', async () => expect(sends).toHaveLength(1) }) +it('drops finished-agent alerts for a phone that asked only for agent questions', async () => { + const reg = registration() + reg.filter = { ...reg.filter, onlyWhenAgentNeedsInput: true } + const { dispatcher, sends } = createHarness({ + devices: [{ deviceId: 'phone', pushRegistration: reg }] + }) + dispatcher.enqueue(notification({ agentState: 'done', emittedAt: 10_000 })) + dispatcher.enqueue(notification({ source: 'terminal-bell', worktreeId: 'b', emittedAt: 10_001 })) + dispatcher.enqueue(notification({ agentState: 'blocked', worktreeId: 'c', emittedAt: 10_002 })) + await flush() + expect(sends.map((send) => send.notification.agentState)).toEqual([null, 'needs-input']) +}) + it('expires per phone at the boundary, preserves leases across persistence, and permits renewal', async () => { vi.useFakeTimers({ toFake: ['Date'] }) vi.setSystemTime(50_000) diff --git a/src/main/runtime/structured-agent-session-mobile-attention.test.ts b/src/main/runtime/structured-agent-session-mobile-attention.test.ts index 30e156f98ac9..0f77f2228394 100644 --- a/src/main/runtime/structured-agent-session-mobile-attention.test.ts +++ b/src/main/runtime/structured-agent-session-mobile-attention.test.ts @@ -61,6 +61,7 @@ function settings(overrides: Partial = {}): NotificationSe return { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false, customSoundId: 'system', @@ -129,12 +130,19 @@ describe('structured attention mobile delivery', () => { expect(h.sent[0]?.title).toContain('needs input') }) - it('marks the push ineligible when agent notifications are off, as the desktop fan-out does', () => { - const h = harness({ + it('gates a prompt on the needs-input setting and a completion on the finished one', () => { + const finishedOff = harness({ readNotificationSettings: () => settings({ agentTaskComplete: false }) }) - h.delivery.deliver(PROMPT, SUMMARY) - expect(h.sent[0]).toMatchObject({ desktopAllowed: false }) + finishedOff.delivery.deliver(PROMPT, SUMMARY) + finishedOff.delivery.deliver(completion('success'), SUMMARY) + expect(finishedOff.sent.map((event) => event.desktopAllowed)).toEqual([undefined, false]) + + const needsInputOff = harness({ + readNotificationSettings: () => settings({ agentNeedsInput: false }) + }) + needsInputOff.delivery.deliver(PROMPT, SUMMARY) + expect(needsInputOff.sent[0]).toMatchObject({ desktopAllowed: false }) }) it('announces nothing for a completion with no verdict', () => { diff --git a/src/main/runtime/structured-agent-session-mobile-attention.ts b/src/main/runtime/structured-agent-session-mobile-attention.ts index 5a0adbc1d6f3..c3ed449098f2 100644 --- a/src/main/runtime/structured-agent-session-mobile-attention.ts +++ b/src/main/runtime/structured-agent-session-mobile-attention.ts @@ -20,6 +20,7 @@ import { structuredAgentSessionTabId } from '../../shared/agent-session/view/structured-agent-session-projection' import { getRepoIdFromWorktreeId } from '../../shared/worktree/id' +import { isNotificationSourceEnabled } from '../../shared/notification-source-gate' import { parseWorkspaceKey } from '../../shared/workspace-scope' import { buildNotificationOptions } from '../ipc/notification-options' import type { MobileNotificationDispatchEvent } from './runtime-mobile-notification-controller' @@ -120,7 +121,11 @@ export function createStructuredAttentionMobileDelivery( getRuntimeDesktopSurface().translateNotification ) // Apply the desktop fan-out preferences to phone delivery too. - const desktopAllowed = settings.enabled && settings.agentTaskComplete + const desktopAllowed = isNotificationSourceEnabled( + settings, + 'agent-task-complete', + news.agentState + ) deps.dispatch({ type: 'notification', emittedAt: deps.now(), diff --git a/src/main/runtime/structured-agent-session-mobile-restore.test.ts b/src/main/runtime/structured-agent-session-mobile-restore.test.ts index 093caffa86f9..5a4f9d54f1d8 100644 --- a/src/main/runtime/structured-agent-session-mobile-restore.test.ts +++ b/src/main/runtime/structured-agent-session-mobile-restore.test.ts @@ -29,6 +29,7 @@ function wire(host: StructuredAgentSessionHost, controller: RuntimeMobileNotific readNotificationSettings: () => ({ enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false, customSoundId: 'system', diff --git a/src/main/runtime/structured-agent-session-mobile-retirement.test.ts b/src/main/runtime/structured-agent-session-mobile-retirement.test.ts index ee81aac7ce3f..78084fcfbc84 100644 --- a/src/main/runtime/structured-agent-session-mobile-retirement.test.ts +++ b/src/main/runtime/structured-agent-session-mobile-retirement.test.ts @@ -87,6 +87,7 @@ describe('host prompt delivery and retirement', () => { readNotificationSettings: () => ({ enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false, customSoundId: 'system', diff --git a/src/main/runtime/terminal-agent-phone-push.test.ts b/src/main/runtime/terminal-agent-phone-push.test.ts index fd787d8128fd..b7bacea5b92f 100644 --- a/src/main/runtime/terminal-agent-phone-push.test.ts +++ b/src/main/runtime/terminal-agent-phone-push.test.ts @@ -64,6 +64,7 @@ function harness( readNotificationSettings: () => ({ enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: true, customSoundId: 'system', @@ -321,6 +322,7 @@ describe('TerminalAgentPhonePush', () => { readNotificationSettings: () => ({ enabled: false, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: true, customSoundId: 'system', diff --git a/src/main/runtime/terminal-agent-phone-push.ts b/src/main/runtime/terminal-agent-phone-push.ts index b30fd13285b0..e94ff3ed285e 100644 --- a/src/main/runtime/terminal-agent-phone-push.ts +++ b/src/main/runtime/terminal-agent-phone-push.ts @@ -6,6 +6,7 @@ import type { AgentStatusIpcPayload } from '../../shared/agent-status-ipc-payloa import type { AgentStatusOrchestrationContext } from '../../shared/agent-status-types' import { isCoordinatorOnlyNews, withApprovalTitle } from '../../shared/dispatched-worker-attention' import { reserveNotificationCooldown } from '../../shared/notification-burst-cooldown' +import { isNotificationSourceEnabled } from '../../shared/notification-source-gate' import type { NotificationDispatchRequest, NotificationSettings @@ -111,7 +112,8 @@ export class TerminalAgentPhonePush { } const settings = this.deps.readNotificationSettings() // The window's own fan-out gates the phone on these same preferences. - const desktopAllowed = settings?.enabled !== false && settings?.agentTaskComplete !== false + const desktopAllowed = + !settings || isNotificationSourceEnabled(settings, news.event.source, news.event.agentState) const now = this.deps.now() const burstKey = JSON.stringify([desktopAllowed, news.event.agentState, news.worktreeId]) if (!reserveNotificationCooldown(this.recentDispatches, burstKey, now)) { diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.test.ts b/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.test.ts index cfa721355107..14deef28de59 100644 --- a/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.test.ts +++ b/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.test.ts @@ -93,6 +93,7 @@ describe('onboarding flow persistence', () => { const notifications = buildCompletedOnboardingNotificationSettings({ enabled: false, agentTaskComplete: false, + agentNeedsInput: false, terminalBell: false, suppressWhenFocused: false, customSoundId: 'two-tone', @@ -105,6 +106,7 @@ describe('onboarding flow persistence', () => { expect(notifications).toEqual({ enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false, customSoundId: 'two-tone', diff --git a/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts b/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts index 4dc57b84c7fb..307e4946270c 100644 --- a/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts +++ b/src/renderer/src/components/onboarding/use-onboarding-flow-persistence.ts @@ -46,6 +46,7 @@ export function buildCompletedOnboardingNotificationSettings( ...notifications, enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true } } diff --git a/src/renderer/src/components/settings/NotificationsPane.test.tsx b/src/renderer/src/components/settings/NotificationsPane.test.tsx index c32bd3e8f13b..f60d351490f7 100644 --- a/src/renderer/src/components/settings/NotificationsPane.test.tsx +++ b/src/renderer/src/components/settings/NotificationsPane.test.tsx @@ -25,6 +25,7 @@ function createSettings(): GlobalSettings { notifications: { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: true, customSoundId: 'system', diff --git a/src/renderer/src/components/settings/NotificationsPane.tsx b/src/renderer/src/components/settings/NotificationsPane.tsx index 26578840ec26..94e66d584a18 100644 --- a/src/renderer/src/components/settings/NotificationsPane.tsx +++ b/src/renderer/src/components/settings/NotificationsPane.tsx @@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react' import type { GlobalSettings } from '../../../../shared/global-settings-types' import { Button } from '../ui/button' import { Separator } from '../ui/separator' -import { BellRing, Bot, EyeOff, Siren } from 'lucide-react' +import { BellRing, Bot, EyeOff, MessageCircleQuestion, Siren } from 'lucide-react' import { useAppStore } from '@/store' import { MacNotificationPermissionCard, @@ -147,6 +147,25 @@ export function NotificationsPane({ } /> + } + label={translate( + 'auto.components.settings.NotificationsPane.63fc5ec9d2', + 'Agent Needs Input' + )} + description={translate( + 'auto.components.settings.NotificationsPane.e1b1724793', + 'A coding agent asks for permission or has a question.' + )} + checked={notificationSettings.agentNeedsInput} + disabled={!notificationSettings.enabled} + onToggle={() => + void updateNotificationSettings({ + agentNeedsInput: !notificationSettings.agentNeedsInput + }) + } + /> + } label={translate('auto.components.settings.NotificationsPane.591fe605b9', 'Terminal Bell')} diff --git a/src/renderer/src/components/settings/notifications-search.ts b/src/renderer/src/components/settings/notifications-search.ts index 9f8dcb94cc5b..b5f1de5a64cc 100644 --- a/src/renderer/src/components/settings/notifications-search.ts +++ b/src/renderer/src/components/settings/notifications-search.ts @@ -57,6 +57,35 @@ export const getNotificationsPaneSearchEntries = createLocalizedCatalog(() => [ ...translateSearchKeyword('auto.components.settings.notifications.search.193e1f107c', 'task') ] }, + { + title: translate( + 'auto.components.settings.notifications.search.d46216d768', + 'Agent Needs Input' + ), + description: translate( + 'auto.components.settings.notifications.search.c9b2b656e0', + 'Notify when a coding agent asks for permission or has a question.' + ), + keywords: [ + ...translateSearchKeyword( + 'auto.components.settings.notifications.search.ca8faa40d7', + 'notifications' + ), + ...translateSearchKeyword( + 'auto.components.settings.notifications.search.7fa07e9600', + 'agent' + ), + ...translateSearchKeyword( + 'auto.components.settings.notifications.search.b8bf5471d1', + 'permission' + ), + ...translateSearchKeyword( + 'auto.components.settings.notifications.search.5b9dafd570', + 'question' + ), + ...translateSearchKeyword('auto.components.settings.notifications.search.009548060d', 'input') + ] + }, { title: translate('auto.components.settings.notifications.search.a5edee1d99', 'Terminal Bell'), description: translate( diff --git a/src/renderer/src/hooks/ipc-events/browser-link-materialization.test-fixture.tsx b/src/renderer/src/hooks/ipc-events/browser-link-materialization.test-fixture.tsx index 21aca6f038c8..b266bfe1b131 100644 --- a/src/renderer/src/hooks/ipc-events/browser-link-materialization.test-fixture.tsx +++ b/src/renderer/src/hooks/ipc-events/browser-link-materialization.test-fixture.tsx @@ -70,6 +70,7 @@ export function installBrowserLinkMaterializationProbe() { notifications: { enabled: false, agentTaskComplete: false, + agentNeedsInput: false, terminalBell: false, suppressWhenFocused: true, customSoundId: 'system', diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json index 6a4fb728f99e..8b13f99e7ef3 100644 --- a/src/renderer/src/i18n/locales/en.json +++ b/src/renderer/src/i18n/locales/en.json @@ -8493,7 +8493,9 @@ "98d70fb261": "Custom notification sound could not be played", "c83b05a055": "Notifications are not supported on this system", "6e6df3a09a": "Choose Custom File", - "76e02467b8": "Change Custom File" + "76e02467b8": "Change Custom File", + "63fc5ec9d2": "Agent Needs Input", + "e1b1724793": "A coding agent asks for permission or has a question." }, "OpenAiTranscriptionKeyDialog": { "fa83512e48": "Save Key", @@ -10765,7 +10767,12 @@ "host": "host", "remote": "remote", "ssh": "ssh", - "mute": "mute" + "mute": "mute", + "d46216d768": "Agent Needs Input", + "c9b2b656e0": "Notify when a coding agent asks for permission or has a question.", + "b8bf5471d1": "permission", + "5b9dafd570": "question", + "009548060d": "input" } }, "orchestration": { diff --git a/src/shared/mobile-push-alert.ts b/src/shared/mobile-push-alert.ts index 5d9685ff3ace..d6aa2fa7ba18 100644 --- a/src/shared/mobile-push-alert.ts +++ b/src/shared/mobile-push-alert.ts @@ -34,11 +34,29 @@ export function mapPushAgentState( return state === undefined || state === 'done' || state === 'finished' ? 'finished' : undefined } +export function isAgentNeedsInputAlert(source: string | undefined, agentState: string | undefined) { + return source === 'agent-task-complete' && mapPushAgentState(source, agentState) === 'needs-input' +} + +/** Drops finished-agent alerts only; bells and the push test follow the desktop's own settings. */ +export function allowsMobilePushAlertKind( + filter: MobilePushFilter, + source: string | undefined, + agentState: string | undefined +): boolean { + return ( + !filter.onlyWhenAgentNeedsInput || + source !== 'agent-task-complete' || + isAgentNeedsInputAlert(source, agentState) + ) +} + export function allowsMobilePushDelivery(filter: MobilePushFilter, event: AlertEvent): boolean { return ( event.type === 'notification' && event.desktopAllowed !== false && - (!filter.onlyWhenDesktopAway || event.desktopAway !== false) + (!filter.onlyWhenDesktopAway || event.desktopAway !== false) && + allowsMobilePushAlertKind(filter, event.source, event.agentState) ) } diff --git a/src/shared/mobile-push-contract.ts b/src/shared/mobile-push-contract.ts index 76cdc2841064..07d6448ac041 100644 --- a/src/shared/mobile-push-contract.ts +++ b/src/shared/mobile-push-contract.ts @@ -15,6 +15,7 @@ export type MobilePushApnsEnvironment = (typeof MOBILE_PUSH_APNS_ENVIRONMENTS)[n export type MobilePushFilter = { onlyWhenDesktopAway?: boolean + onlyWhenAgentNeedsInput?: boolean sound?: boolean } @@ -53,6 +54,8 @@ function parseFilter(value: unknown): MobilePushFilter | null { const filter = value as Partial if ( (filter.onlyWhenDesktopAway !== undefined && typeof filter.onlyWhenDesktopAway !== 'boolean') || + (filter.onlyWhenAgentNeedsInput !== undefined && + typeof filter.onlyWhenAgentNeedsInput !== 'boolean') || (filter.sound !== undefined && typeof filter.sound !== 'boolean') ) { return null @@ -61,6 +64,9 @@ function parseFilter(value: unknown): MobilePushFilter | null { ...(typeof filter.onlyWhenDesktopAway === 'boolean' ? { onlyWhenDesktopAway: filter.onlyWhenDesktopAway } : {}), + ...(typeof filter.onlyWhenAgentNeedsInput === 'boolean' + ? { onlyWhenAgentNeedsInput: filter.onlyWhenAgentNeedsInput } + : {}), ...(typeof filter.sound === 'boolean' ? { sound: filter.sound } : {}) } } diff --git a/src/shared/notification-settings-defaults.ts b/src/shared/notification-settings-defaults.ts index ac322dd9c33b..8b79a5c3e16e 100644 --- a/src/shared/notification-settings-defaults.ts +++ b/src/shared/notification-settings-defaults.ts @@ -4,6 +4,7 @@ export function getDefaultNotificationSettings(): NotificationSettings { return { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: false, suppressWhenFocused: true, customSoundId: 'system', diff --git a/src/shared/notification-settings-types.ts b/src/shared/notification-settings-types.ts index b4247f7560f7..bd5d053065af 100644 --- a/src/shared/notification-settings-types.ts +++ b/src/shared/notification-settings-types.ts @@ -8,7 +8,9 @@ import type { NotificationSourceId } from './notification-source' export type NotificationSettings = { enabled: boolean + /** An agent finished its turn; permission and question prompts use agentNeedsInput. */ agentTaskComplete: boolean + agentNeedsInput: boolean terminalBell: boolean suppressWhenFocused: boolean customSoundId: diff --git a/src/shared/notification-source-gate.ts b/src/shared/notification-source-gate.ts new file mode 100644 index 000000000000..2b7b8706c0df --- /dev/null +++ b/src/shared/notification-source-gate.ts @@ -0,0 +1,27 @@ +import { isAgentNeedsInputAlert } from './mobile-push-alert' +import type { NotificationSettings } from './notification-settings-types' + +type SourceGateSettings = Pick< + NotificationSettings, + 'enabled' | 'agentTaskComplete' | 'agentNeedsInput' | 'terminalBell' +> + +/** The desktop's per-source preferences; paired phones receive an alert only when this allows it. */ +export function isNotificationSourceEnabled( + settings: SourceGateSettings, + source: string, + agentState: string | undefined +): boolean { + if (!settings.enabled) { + return false + } + if (source === 'terminal-bell') { + return settings.terminalBell + } + if (source !== 'agent-task-complete') { + return true + } + return isAgentNeedsInputAlert(source, agentState) + ? settings.agentNeedsInput + : settings.agentTaskComplete +} diff --git a/src/shared/rpc-contract/notifications-params.ts b/src/shared/rpc-contract/notifications-params.ts index 180cfdaf2e40..83b20ba8bab9 100644 --- a/src/shared/rpc-contract/notifications-params.ts +++ b/src/shared/rpc-contract/notifications-params.ts @@ -28,6 +28,7 @@ export const NotificationGetMissedSinceParams = z.object({ export const NotificationPushFilterParams = z.object({ onlyWhenDesktopAway: z.boolean().optional(), + onlyWhenAgentNeedsInput: z.boolean().optional(), sound: z.boolean().optional() }) diff --git a/tests/e2e/structured-attention-host-read-retirement.unit.test.ts b/tests/e2e/structured-attention-host-read-retirement.unit.test.ts index d9a412eebf91..49aea0cf6f5f 100644 --- a/tests/e2e/structured-attention-host-read-retirement.unit.test.ts +++ b/tests/e2e/structured-attention-host-read-retirement.unit.test.ts @@ -85,6 +85,7 @@ function attentionPath(directory: string) { readNotificationSettings: () => ({ enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: false, customSoundId: 'system', diff --git a/tests/e2e/structured-attention-read-retirement.test-fixture.tsx b/tests/e2e/structured-attention-read-retirement.test-fixture.tsx index 71f0a3ec1cab..e9323f86b515 100644 --- a/tests/e2e/structured-attention-read-retirement.test-fixture.tsx +++ b/tests/e2e/structured-attention-read-retirement.test-fixture.tsx @@ -51,6 +51,7 @@ export const REMOTE_TARGET = { kind: 'environment', environmentId: 'relay-host' export const NOTIFICATION_SETTINGS: NotificationSettings = { enabled: true, agentTaskComplete: true, + agentNeedsInput: true, terminalBell: true, suppressWhenFocused: true, customSoundId: 'system',