Add agent completion notifications (#198)

Author: Xinyuexyyyyy

CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased]
 
 ### 🚀 Added
+- Agent: system notifications now fire when agents finish work and return to standby. (#198)
 - Settings: left-sidebar search helps users locate settings and jump directly to the matching section. (#192)
 - CLI: add canvas node control commands for creating, listing, reading, deleting, updating supported node types, and focusing nodes or Spaces. (#193)
 - Workspace canvas: experimental website window nodes with opt-in settings, shared-session profile modes, snapshot-backed warm/cold lifecycle, and in-canvas navigation handling. (#141)

src/app/preload/index.d.ts

@@ -55,6 +55,8 @@ import type {
   SuggestWorktreeNamesInput,
   SuggestWorktreeNamesResult,
   SetWindowChromeThemeInput,
+  ShowSystemNotificationInput,
+  ShowSystemNotificationResult,
   TerminalDataEvent,
   TerminalExitEvent,
   TerminalSessionMetadataEvent,
@@ -255,6 +257,9 @@ export interface OpenCoveApi {
   }
   system: {
     listFonts: () => Promise<ListSystemFontsResult>
+    showNotification: (
+      payload: ShowSystemNotificationInput,
+    ) => Promise<ShowSystemNotificationResult>
   }
   worker: {
     getStatus: () => Promise<WorkerStatusResult>

src/app/preload/index.ts

@@ -58,6 +58,8 @@ import type {
   SuggestWorktreeNamesInput,
   SuggestWorktreeNamesResult,
   SetWindowChromeThemeInput,
+  ShowSystemNotificationInput,
+  ShowSystemNotificationResult,
   TerminalDataEvent,
   TerminalExitEvent,
   TerminalSessionMetadataEvent,
@@ -453,6 +455,10 @@ const opencoveApi = {
   },
   system: {
     listFonts: (): Promise<ListSystemFontsResult> => invokeIpc(IPC_CHANNELS.systemListFonts),
+    showNotification: (
+      payload: ShowSystemNotificationInput,
+    ): Promise<ShowSystemNotificationResult> =>
+      invokeIpc(IPC_CHANNELS.systemShowNotification, payload),
   },
   worker: {
     getStatus: (): Promise<WorkerStatusResult> => invokeIpc(IPC_CHANNELS.workerGetStatus),

src/app/renderer/browser/browserOpenCoveApi.ts

@@ -1,4 +1,9 @@
-import type { ListSystemFontsResult, WorkspaceDirectory } from '@shared/contracts/dto'
+import type {
+  ListSystemFontsResult,
+  ShowSystemNotificationInput,
+  ShowSystemNotificationResult,
+  WorkspaceDirectory,
+} from '@shared/contracts/dto'
 import { BrowserPtyClient } from './BrowserPtyClient'
 import { invokeBrowserControlSurface } from './browserControlSurface'
 import type { ControlSurfaceInvokeRequest } from '@shared/contracts/controlSurface'
@@ -340,6 +345,33 @@ export function installBrowserOpenCoveApi(): void {
     },
     system: {
       listFonts: async (): Promise<ListSystemFontsResult> => ({ fonts: [] }),
+      showNotification: async (
+        payload: ShowSystemNotificationInput,
+      ): Promise<ShowSystemNotificationResult> => {
+        if (typeof window === 'undefined' || !('Notification' in window)) {
+          return { shown: false }
+        }
+
+        if (Notification.permission === 'default') {
+          await Notification.requestPermission()
+        }
+
+        if (Notification.permission !== 'granted') {
+          return { shown: false }
+        }
+
+        const title = payload.title.trim()
+        if (title.length === 0) {
+          return { shown: false }
+        }
+
+        const notification = new Notification(title, {
+          body: typeof payload.body === 'string' ? payload.body : undefined,
+          silent: payload.silent ?? false,
+        })
+        void notification
+        return { shown: true }
+      },
     },
     worker: {
       getStatus: async () => unsupportedWorkerStatus(),

src/app/renderer/i18n/locales/en.settingsPanel.ts

@@ -142,9 +142,14 @@ export const enSettingsPanel = {
   },
   notifications: {
     title: 'Notifications',
+    systemNotifications: {
+      enabledLabel: 'System notifications',
+      enabledHelp:
+        'Show a native system notification when an agent transitions from working to standby.',
+    },
     agentStandbyBanner: {
-      enabledLabel: 'Agent standby banner',
-      enabledHelp: 'Show a top-right banner when an agent transitions from working to standby.',
+      enabledLabel: 'Top-right banner',
+      enabledHelp: 'Show an in-app banner when an agent transitions from working to standby.',
       contextTitle: 'Banner context',
       contextHelp: 'Choose what context chips are shown in the banner.',
       showTask: 'Show task',

src/app/renderer/i18n/locales/en.ts

@@ -84,7 +84,7 @@ export const en = {
     sidebar: 'Sidebar',
     minimap: 'Minimap',
     theme: 'Theme',
-    agentStandbyBanner: 'Agent standby banner',
+    agentStandbyBanner: 'Top-right banner',
     on: 'On',
     off: 'Off',
   },

src/app/renderer/i18n/locales/zh-CN.settingsPanel.ts

@@ -141,9 +141,13 @@ export const zhCNSettingsPanel = {
   },
   notifications: {
     title: '通知',
+    systemNotifications: {
+      enabledLabel: '系统通知',
+      enabledHelp: '当 Agent 从工作状态变为待命时，显示原生系统通知。',
+    },
     agentStandbyBanner: {
-      enabledLabel: 'Agent 完成提醒',
-      enabledHelp: '当 Agent 从工作状态变为待命时，在右上角显示提醒横幅。',
+      enabledLabel: '右上角横幅',
+      enabledHelp: '当 Agent 从工作状态变为待命时，显示应用内右上角横幅。',
       contextTitle: '横幅信息',
       contextHelp: '控制右上角提醒横幅中显示的上下文信息。',
       showTask: '显示任务',

src/app/renderer/i18n/locales/zh-CN.ts

@@ -86,7 +86,7 @@ export const zhCN = {
     sidebar: '侧边栏',
     minimap: '缩略图',
     theme: '主题',
-    agentStandbyBanner: 'Agent 完成提醒',
+    agentStandbyBanner: '右上角横幅',
     on: '已开启',
     off: '已关闭',
   },

src/app/renderer/shell/hooks/useAgentStandbyNotifications.ts

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useTranslation } from '@app/renderer/i18n'
 import type { AgentStandbyNotification } from '../components/AppNotifications'
 import type { GitHubPullRequestSummary, GitWorktreeInfo } from '@shared/contracts/dto'
 import type { WorkspaceState } from '@contexts/workspace/presentation/renderer/types'
@@ -116,6 +117,31 @@ function updateNotification(
   return didChange ? next : previous
 }
 
+export function formatAgentStandbySystemNotification(
+  notification: Pick<
+    AgentStandbyNotification,
+    'title' | 'workspaceName' | 'taskTitle' | 'spaceName'
+  >,
+  labels: {
+    standby: string
+    task: string
+    space: string
+  },
+): { title: string; body: string } {
+  const summary = notification.workspaceName
+    ? `${labels.standby} · ${notification.workspaceName}`
+    : labels.standby
+  const contextLines = [
+    notification.taskTitle ? `${labels.task}: ${notification.taskTitle}` : null,
+    notification.spaceName ? `${labels.space}: ${notification.spaceName}` : null,
+  ].filter((line): line is string => !!line)
+
+  return {
+    title: notification.title,
+    body: [summary, ...contextLines].join('\n'),
+  }
+}
+
 export function useAgentStandbyNotifications({
   maxVisible = 5,
 }: {
@@ -124,11 +150,15 @@ export function useAgentStandbyNotifications({
   notifications: AgentStandbyNotification[]
   dismiss: (id: string) => void
 } {
+  const { t } = useTranslation()
   const platform =
     typeof window !== 'undefined' && window.opencoveApi?.meta?.platform
       ? window.opencoveApi.meta.platform
       : undefined
   const workspaces = useAppStore(state => state.workspaces)
+  const areSystemNotificationsEnabled = useAppStore(
+    state => state.agentSettings.systemNotificationsEnabled,
+  )
   const isStandbyBannerEnabled = useAppStore(state => state.agentSettings.standbyBannerEnabled)
   const showBranch = useAppStore(state => state.agentSettings.standbyBannerShowBranch)
   const showPullRequest = useAppStore(state => state.agentSettings.standbyBannerShowPullRequest)
@@ -243,7 +273,7 @@ export function useAgentStandbyNotifications({
 
   const handleAgentEnteredStandby = useCallback(
     (payload: AgentStandbyNotificationPayload) => {
-      if (!isStandbyBannerEnabled) {
+      if (!isStandbyBannerEnabled && !areSystemNotificationsEnabled) {
         return
       }
 
@@ -276,6 +306,21 @@ export function useAgentStandbyNotifications({
           createdAt: Date.now(),
         }
 
+        if (areSystemNotificationsEnabled && window.opencoveApi?.meta?.isTest !== true) {
+          const nativeNotification = formatAgentStandbySystemNotification(next, {
+            standby: t('agentRuntime.standby'),
+            task: t('settingsPanel.nav.tasks'),
+            space: t('commandCenter.sections.spaces'),
+          })
+          void window.opencoveApi?.system
+            ?.showNotification(nativeNotification)
+            .catch(() => undefined)
+        }
+
+        if (!isStandbyBannerEnabled) {
+          return previous
+        }
+
         if (!shouldResolveBranch && !shouldResolvePullRequest) {
           const updated = [next, ...previous]
           return updated.length > maxVisible ? updated.slice(0, maxVisible) : updated
@@ -286,10 +331,12 @@ export function useAgentStandbyNotifications({
       })
     },
     [
+      areSystemNotificationsEnabled,
       isStandbyBannerEnabled,
       maxVisible,
       shouldResolveBranch,
       shouldResolvePullRequest,
+      t,
       workspacesById,
     ],
   )

src/contexts/settings/domain/agentSettings.defaults.ts

@@ -42,6 +42,7 @@ export const DEFAULT_AGENT_SETTINGS: AgentSettings = {
   focusNodeOnClick: true,
   focusNodeTargetZoom: 1,
   focusNodeUseVisibleCanvasCenter: true,
+  systemNotificationsEnabled: true,
   standbyBannerEnabled: true,
   standbyBannerShowTask: true,
   standbyBannerShowSpace: true,