Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

feat(extension): a finished monitor, scheduled task or reminder shows as the computer's own notification, through the Browsentic app, while the browser is behind other windows or minimized; clicking it brings the tab back, and everything else keeps the card on the page

Shahriar8c875684e918
diff --git a/docs/guide/features/monitoring.md b/docs/guide/features/monitoring.md
index c4f67fc..9151b2b 100644
--- a/docs/guide/features/monitoring.md
+++ b/docs/guide/features/monitoring.md
@@ -45,13 +45,26 @@ given a watch on nothing.
| Default duration | 30 minutes |
| Maximum duration | 4 hours |
| While it runs | The tab is pinned; you can work anywhere else |
-| On completion | A browser notification, plus the run's own report |
+| On completion | A card on the page you are on, plus the run's own report. While the browser is behind other windows or minimized, the Browsentic app shows it as your computer's own notification instead; clicking it brings the tab back (see [Where a finished notice shows](#where-a-finished-notice-shows)) |
Sampling is debounced and rate-limited, with a five-second backstop tick so a page that stops
changing still gets checked.
---
+## Where a finished notice shows
+
+| The browser | The Browsentic app | Where it shows |
+| --- | --- | --- |
+| In front | Any | A card on the page you are on |
+| Behind other windows, or minimized | Running, with notifications allowed | Your computer's own notification, from the app. Click it to bring the tab back |
+| Behind, or minimized | Not running, or notifications off | A card on the page, or the browser's notification when no page can show one |
+
+The same goes for a scheduled task finishing and for a reminder. On a Mac, allow notifications for
+Browsentic in System Settings › Notifications; on Windows, in Settings › System › Notifications.
+
+---
+
## Stopping one
```
diff --git a/docs/guide/features/scheduling.md b/docs/guide/features/scheduling.md
index 3ccae33..bba28bd 100644
--- a/docs/guide/features/scheduling.md
+++ b/docs/guide/features/scheduling.md
@@ -137,8 +137,10 @@ If you only want to be told something at a set time, no agent is needed:
remind me to check the oven in twenty minutes
```
-That schedules a browser notification with the text and starts no agent. It works with the side
-panel closed.
+That schedules a notification with the text and starts no agent. It works with the side panel
+closed. While the browser is behind or minimized and the Browsentic app is running with
+notifications allowed, it comes from the app as your computer's own notification; see
+[Where a finished notice shows](monitoring.md#where-a-finished-notice-shows).
---
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 6bbf545..896d83e 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -583,6 +583,16 @@ loaded. If that is newer, it is held the same way, and **Update** reloads the ex
folder. `browsentic update` and the apps restart the Bridge before they rewrite the folder, so the
welcome often comes too early; the panel reads the manifest again whenever it opens or gets focus.
+## Notices while the browser is behind
+
+A finished monitor, scheduled task or reminder first asks `noticeOnDevice()` in `device-notices.ts`.
+While no browser window is focused and un-minimized, it sends the notice to the Bridge for the
+Browsentic app to show as the computer's own notification; a card on a page nobody is looking at
+helps no one. When the app takes it, the notice's tab is remembered in `storage.session` under
+`browsentic/noticeTabs` (the newest 30), and a click in the app brings that tab to the front. When
+it does not (the browser in front, no app, notifications off, a Bridge before protocol 24), the
+caller goes on to its card or the browser's own notification, as before.
+
## Pairing by itself
`auto-pair.ts` pairs the extension with Browsentic Bridge through the native host, with no code.
diff --git a/docs/internals/state.md b/docs/internals/state.md
index d7548e6..e1daacf 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -95,6 +95,9 @@ last attempt found and when, which spaces the next one, and `browsentic/staleKey
`storage.session` once the Bridge has said it holds no session for the stored key. The key itself
stays until a new one replaces it.
+**Notices the app showed** are `browsentic/noticeTabs` in `storage.session`: each notice's id and the
+tab a click brings back, the newest 30, gone with the browser.
+
**Blocked sites** are `browsentic/blockedSites` in `storage.local`: a list of up to 500 patterns that
the daemon never receives. Removing the extension removes it; each browser keeps its own.
diff --git a/docs/internals/transport.md b/docs/internals/transport.md
index a9c3370..35d558c 100644
--- a/docs/internals/transport.md
+++ b/docs/internals/transport.md
@@ -173,7 +173,7 @@ dialling. It never deletes the stored key; only pairing again or `disconnect` re
## Protocol version
-Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **23**). They used to have to match
+Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **24**). They used to have to match
exactly. A store copy updates when its browser decides to, not when the daemon does, so the
extension and the daemon are routinely a version apart, and the daemon accepts a **window**:
@@ -193,6 +193,25 @@ a change neither side can do without raises a minimum. A refusal must never stra
v0.8.0 store build unpairs on any refusal and does not retry, so no daemon may refuse protocol 22
until a store build that retries has replaced it.
+### Protocol 24: notices for the desktop app
+
+Protocol 24 lets a browser hand a finished monitor, scheduled task or reminder to the Browsentic app,
+which shows it as the computer's own notification. The extension does this only while no browser
+window is focused and un-minimized (`browserInFront()` in `device-notices.ts`), and only to a Bridge
+that speaks 24; the Bridge sends `openNotice` only to an extension that speaks 24.
+
+| Frame | From | What it carries |
+| --- | --- | --- |
+| `notice` | extension | `id` for the answer and the notice: its own `id`, `kind` (`monitor`, `task`, `timer`), `title`, `body` and `tone`. It does not count as the user being in that browser |
+| `noticeAck` | Bridge | `delivered`: whether an app that may show notifications took it. False, or no answer within 3 s, and the extension shows its own card or notification |
+| `openNotice` | Bridge | `noticeId`: someone clicked it in the app, so the extension brings that notice's tab to the front |
+
+The app sends `/control` `notices {watch:true, allowed}` on every socket and again when the
+computer starts or stops letting it notify; `notices-changed` tells it to call `takeNotices`, which
+hands over and forgets what is waiting (a notice nobody takes within five minutes is dropped). A click
+sends `openNotice`, which reaches the browser the notice came from. Agent-run connections are refused
+all three. Nothing about a notice is written to disk.
+
### Protocol 23: Android
Protocol 23 adds the frames that let a browser drive Chrome on an Android phone through the Bridge.
diff --git a/src/extension/entrypoints/background.ts b/src/extension/entrypoints/background.ts
index 7db1b99..b2a1331 100644
--- a/src/extension/entrypoints/background.ts
+++ b/src/extension/entrypoints/background.ts
@@ -27,6 +27,7 @@ import { servePhoneMirror } from '@/lib/bridge/phone-mirror';
import { servePhoneBackend } from '@/lib/bridge/phone-backend';
import { serveExtensionUpdates } from '@/lib/bridge/extension-update';
import { autoPair, holdAutoPair, releaseAutoPair, serveAutoPair } from '@/lib/bridge/auto-pair';
+import { serveDeviceNotices } from '@/lib/bridge/device-notices';
import { isAgentKind } from '@/lib/agents/catalog';
import { isPreferenceChange } from '@/lib/settings/preferences';
import {
@@ -266,6 +267,7 @@ export default defineBackground(() => {
void sweepFiles();
serveAutoPair();
+ serveDeviceNotices();
void connectDaemon().then(() => autoPair('alarm'));
browser.runtime.onStartup.addListener(() => void connectDaemon().then(() => autoPair('startup')));
diff --git a/src/lib/bridge/device-notices.test.ts b/src/lib/bridge/device-notices.test.ts
new file mode 100644
index 0000000..ea1b427
--- /dev/null
+++ b/src/lib/bridge/device-notices.test.ts
@@ -0,0 +1,73 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fakeBrowser } from 'wxt/testing';
+import type { DeviceNotice } from '@/lib/notices';
+
+const socket = vi.hoisted(() => ({ sendNotice: vi.fn(), opened: null as ((noticeId: string) => void) | null }));
+const toast = vi.hoisted(() => ({ goToTab: vi.fn() }));
+
+vi.mock('./socket', () => ({
+ sendNotice: socket.sendNotice,
+ onOpenNotice: (listener: (noticeId: string) => void) => {
+ socket.opened = listener;
+ return () => undefined;
+ },
+}));
+vi.mock('./toast', () => ({ goToTab: toast.goToTab }));
+
+const { browserInFront, noticeOnDevice, serveDeviceNotices } = await import('./device-notices');
+
+const done: DeviceNotice = { id: 'monitor:build', kind: 'monitor', title: 'Done: build', body: 'Finished after 3:12.', tone: 'live' };
+
+type Window = { id: number; focused: boolean; state: string };
+
+function windows(list: Window[]): void {
+ (fakeBrowser.windows as unknown as { getAll: () => Promise<Window[]> }).getAll = async () => list;
+ (fakeBrowser.windows as unknown as { update: (id: number, change: object) => Promise<object> }).update = vi.fn(async () => ({}));
+}
+
+beforeEach(() => {
+ fakeBrowser.reset();
+ socket.sendNotice.mockReset();
+ toast.goToTab.mockReset();
+});
+
+describe('browserInFront', () => {
+ it('is true only while some window is focused and not minimized', async () => {
+ windows([{ id: 1, focused: true, state: 'normal' }]);
+ expect(await browserInFront()).toBe(true);
+ windows([{ id: 1, focused: false, state: 'normal' }]);
+ expect(await browserInFront()).toBe(false);
+ windows([{ id: 1, focused: true, state: 'minimized' }]);
+ expect(await browserInFront()).toBe(false);
+ windows([]);
+ expect(await browserInFront()).toBe(false);
+ });
+});
+
+describe('noticeOnDevice', () => {
+ it('leaves the notice to the page while someone is looking at the browser', async () => {
+ windows([{ id: 1, focused: true, state: 'maximized' }]);
+ expect(await noticeOnDevice(done, 7)).toBe(false);
+ expect(socket.sendNotice).not.toHaveBeenCalled();
+ });
+
+ it('hands it to the app while the browser is behind, and falls back when the app will not take it', async () => {
+ windows([{ id: 1, focused: false, state: 'normal' }]);
+ socket.sendNotice.mockResolvedValueOnce(true).mockResolvedValueOnce(false);
+ expect(await noticeOnDevice(done, 7)).toBe(true);
+ expect(await noticeOnDevice({ ...done, id: 'monitor:other' }, 8)).toBe(false);
+ });
+
+ it('brings the notice’s own tab forward when it is clicked, or a window when it had none', async () => {
+ windows([{ id: 4, focused: false, state: 'minimized' }]);
+ serveDeviceNotices();
+ socket.sendNotice.mockResolvedValue(true);
+ await noticeOnDevice(done, 7);
+ await noticeOnDevice({ ...done, id: 'task:t1' });
+
+ socket.opened!(done.id);
+ await vi.waitFor(() => expect(toast.goToTab).toHaveBeenCalledWith(7));
+ socket.opened!('task:t1');
+ await vi.waitFor(() => expect(fakeBrowser.windows.update).toHaveBeenCalledWith(4, { focused: true }));
+ });
+});
diff --git a/src/lib/bridge/device-notices.ts b/src/lib/bridge/device-notices.ts
new file mode 100644
index 0000000..9a91564
--- /dev/null
+++ b/src/lib/bridge/device-notices.ts
@@ -0,0 +1,47 @@
+import { browser } from 'wxt/browser';
+import type { DeviceNotice } from '@/lib/notices';
+import { onOpenNotice, sendNotice } from './socket';
+import { goToTab } from './toast';
+
+/** Which tab each notice the app is showing belongs to, so a click brings that tab forward. */
+const NOTICE_TABS_KEY = 'browsentic/noticeTabs';
+const NOTICE_TABS_MAX = 30;
+
+/** A card on a page only helps while someone is looking at the browser: some window focused and not minimized. */
+export async function browserInFront(): Promise<boolean> {
+ const windows = await browser.windows.getAll({ windowTypes: ['normal'] }).catch(() => []);
+ return windows.some((window) => window.focused && window.state !== 'minimized');
+}
+
+/**
+ * Shows the notice as the computer's own notification, through the Browsentic app, when the browser is
+ * behind or minimized and the app may post one. False leaves the caller to its card or the browser's
+ * notification, which is everything else: the browser in front, no app, notifications not allowed, or a
+ * Bridge from before this.
+ */
+export async function noticeOnDevice(notice: DeviceNotice, tabId?: number): Promise<boolean> {
+ if (await browserInFront()) return false;
+ if (!(await sendNotice(notice))) return false;
+ if (tabId != null) await rememberTab(notice.id, tabId);
+ return true;
+}
+
+async function noticeTabs(): Promise<Record<string, number>> {
+ return ((await browser.storage.session.get(NOTICE_TABS_KEY))[NOTICE_TABS_KEY] as Record<string, number> | undefined) ?? {};
+}
+
+async function rememberTab(noticeId: string, tabId: number): Promise<void> {
+ const kept = Object.entries({ ...(await noticeTabs()), [noticeId]: tabId }).slice(-NOTICE_TABS_MAX);
+ await browser.storage.session.set({ [NOTICE_TABS_KEY]: Object.fromEntries(kept) });
+}
+
+async function bringForward(noticeId: string): Promise<void> {
+ const tabId = (await noticeTabs())[noticeId];
+ if (tabId != null) return goToTab(tabId);
+ const [window] = await browser.windows.getAll({ windowTypes: ['normal'] }).catch(() => []);
+ if (window?.id != null) await browser.windows.update(window.id, { focused: true }).catch(() => undefined);
+}
+
+export function serveDeviceNotices(): void {
+ onOpenNotice((noticeId) => void bringForward(noticeId));
+}
diff --git a/src/lib/bridge/monitor.ts b/src/lib/bridge/monitor.ts
index e0e6561..037f805 100644
--- a/src/lib/bridge/monitor.ts
+++ b/src/lib/bridge/monitor.ts
@@ -28,6 +28,8 @@ import {
} from '@/lib/monitor/events';
import { hostOf, originOf } from '@/lib/recordings/events';
import { showToast } from '@/lib/bridge/toast';
+import { noticeOnDevice } from '@/lib/bridge/device-notices';
+import type { NoticeTone } from '@/lib/notices';
import { onBlockedSitesChange, refusalFor, siteBlocked, tabUrls } from '@/lib/bridge/site-guard';
const MONITORS_KEY = 'browsentic/monitors';
@@ -516,21 +518,25 @@ function pathOf(url: string): string {
}
/**
- * A card drawn onto the page the user is on, which is the only surface they are certainly
- * looking at. The OS notification stays as the fallback for when no page will take one —
- * every tab is a chrome:// page, or the window has nothing open.
+ * The computer's own notification, through the Browsentic app, while the browser is behind or minimized;
+ * otherwise a card drawn onto the page the user is on. The browser's notification stays as the fallback
+ * for when no page will take one: every tab is a chrome:// page, or the window has nothing open.
*/
async function announce(state: MonitorState): Promise<void> {
const content = copyFor(state);
if (!content) return;
+ const tone: NoticeTone = state.phase === 'done' ? 'live' : 'warn';
+ const tabId = state.phase === 'tab-closed' ? undefined : state.tabId;
+ const notice = { id: `monitor:${state.monitorId}`, kind: 'monitor' as const, title: content.title, body: content.message, tone };
+ if (await noticeOnDevice(notice, tabId)) return;
const shown = await showToast(
{
toastId: state.monitorId,
- tone: state.phase === 'done' ? 'live' : 'warn',
+ tone,
title: content.title,
body: content.message,
- tabId: state.phase === 'tab-closed' ? undefined : state.tabId,
+ tabId,
},
state.tabId,
);
diff --git a/src/lib/bridge/socket.ts b/src/lib/bridge/socket.ts
index 60b7698..6792816 100644
--- a/src/lib/bridge/socket.ts
+++ b/src/lib/bridge/socket.ts
@@ -34,6 +34,7 @@ import type { SkillDraft } from '@/lib/skills/format';
import type { SiteMapDraft } from '@/lib/skills/site-map';
import type { TaskList, TaskOrder, TaskResult } from '@/lib/schedules/task';
import type { Approver, PairingMode, RefusalCode } from '@/lib/pairing';
+import { NOTICE_PROTOCOL, type DeviceNotice } from '@/lib/notices';
import { identify } from './identity';
import type { BridgeReach } from './native-pair';
import { invokeForHarness } from './invoke';
@@ -130,6 +131,10 @@ export type CdpEvent = Extract<SocketFrame, { t: 'cdpEvent' }>;
const cdpListeners = new Set<(event: CdpEvent) => void>();
const phoneClosedListeners = new Set<(serial: string, reason: PhoneClosedReason) => void>();
const closedListeners = new Set<() => void>();
+const openNoticeListeners = new Set<(noticeId: string) => void>();
+const pendingNotices = new Map<string, (delivered: boolean) => void>();
+/** The Bridge answers at once; past this the browser shows its own card instead. */
+const NOTICE_TIMEOUT_MS = 3_000;
const listen = <T>(listeners: Set<T>, listener: T): (() => void) => {
listeners.add(listener);
@@ -225,6 +230,25 @@ export function analyzeRecording(recording: RecordingPayload): Promise<ActionRes
const TITLE_TIMEOUT_MS = 20_000;
+/** Someone clicked a notice the Browsentic app showed for this browser. */
+export const onOpenNotice = (listener: (noticeId: string) => void) => listen(openNoticeListeners, listener);
+
+/** True when the Browsentic app took the notice to show as the computer's own; false sends the caller to its own card. */
+export function sendNotice(notice: DeviceNotice): Promise<boolean> {
+ const id = crypto.randomUUID();
+ if (!daemonSpeaks(NOTICE_PROTOCOL) || !post({ t: 'notice', id, notice })) return Promise.resolve(false);
+ return new Promise((resolve) => {
+ const timer = setTimeout(() => {
+ pendingNotices.delete(id);
+ resolve(false);
+ }, NOTICE_TIMEOUT_MS);
+ pendingNotices.set(id, (delivered) => {
+ clearTimeout(timer);
+ resolve(delivered);
+ });
+ });
+}
+
const pendingSessionNames = new Map<string, (result: ActionResult<{ title: string }>) => void>();
export function nameSession(session: { host?: string; messages: string[] }): Promise<ActionResult<{ title: string }>> {
@@ -794,6 +818,16 @@ async function handle(ws: WebSocket, raw: string, attempt: Attempt): Promise<voi
return;
}
+ case 'noticeAck': {
+ pendingNotices.get(frame.id)?.(frame.delivered === true);
+ pendingNotices.delete(frame.id);
+ return;
+ }
+
+ case 'openNotice':
+ for (const listener of openNoticeListeners) listener(frame.noticeId);
+ return;
+
case 'sessionName': {
pendingSessionNames.get(frame.id)?.(frame.result);
pendingSessionNames.delete(frame.id);
diff --git a/src/lib/bridge/task-notices.ts b/src/lib/bridge/task-notices.ts
index 8abac5d..1717779 100644
--- a/src/lib/bridge/task-notices.ts
+++ b/src/lib/bridge/task-notices.ts
@@ -3,6 +3,8 @@ import { TASK_APPROVAL_WAIT_MS, type RunOutcome, type TaskResult } from '@/lib/s
import type { ToastTone } from '@/lib/toast/events';
import type { TaskTag } from './tab-sessions';
import { goToTab, hideToast, showToast, showToastOn } from './toast';
+import { noticeOnDevice } from './device-notices';
+import type { NoticeTone } from '@/lib/notices';
const NOTIFICATION_PREFIX = 'browsentic-task:';
const DETAIL_CHARS = 90;
@@ -34,6 +36,8 @@ export function taskNoticeFor(tag: Pick<TaskTag, 'name' | 'notify'>, result: Tas
export async function announceTask(tag: TaskTag, result: TaskResult, tabId?: number): Promise<void> {
const notice = taskNoticeFor(tag, result);
if (!notice) return;
+ const tone: NoticeTone = notice.tone === 'warn' ? 'warn' : 'live';
+ if (await noticeOnDevice({ id: `task:${tag.id}`, kind: 'task', title: notice.title, body: notice.body, tone }, tag.keepTab ? tabId : undefined)) return;
const shown = await showToast({ toastId: `task:${tag.id}:${Date.now()}`, ...notice, tabId: tag.keepTab ? tabId : undefined }, tabId);
if (!shown) await notify(`${NOTIFICATION_PREFIX}${tag.id}`, notice.title, notice.body);
}
diff --git a/src/lib/bridge/timer.ts b/src/lib/bridge/timer.ts
index 437f977..99f2f13 100644
--- a/src/lib/bridge/timer.ts
+++ b/src/lib/bridge/timer.ts
@@ -1,4 +1,6 @@
import { browser } from 'wxt/browser';
+import type { NoticeTone } from '@/lib/notices';
+import { noticeOnDevice } from './device-notices';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import {
BUSY_RETRY_MS,
@@ -255,6 +257,7 @@ export async function finishTimer(
timerId,
`Timer ended: ${closed.label ?? 'scheduled job'}`,
'The conversation it was set in has closed, so it was cancelled.',
+ 'warn',
);
}
return closed;
@@ -329,7 +332,8 @@ export function serveTimers(): void {
});
}
-async function notify(timerId: string, title: string, message: string): Promise<void> {
+async function notify(timerId: string, title: string, message: string, tone: NoticeTone = 'live'): Promise<void> {
+ if (await noticeOnDevice({ id: `timer:${timerId}`, kind: 'timer', title, body: message, tone })) return;
await browser.notifications
?.create(`${NOTIFICATION_PREFIX}${timerId}`, {
type: 'basic',