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(bridge): protocol 24 lets a browser hand a finished monitor, task or reminder to the Browsentic app, which takes it only while it may show notifications, and a click in the app reaches the browser it came from

Shahriar55fde2ee9767
diff --git a/src/daemon/control.ts b/src/daemon/control.ts
index 63fb48a..607a584 100644
--- a/src/daemon/control.ts
+++ b/src/daemon/control.ts
@@ -5,6 +5,7 @@ import type { AndroidState } from '@/lib/phone/types';
import type { Preferences } from '@/lib/settings/preferences';
import type { Source } from '@/lib/stores';
import type { Approver, BlockedBrowser, GrantOutcome, PairRequestSummary, PairedBy, PairingMode } from '@/lib/pairing';
+import type { QueuedNotice } from '@/lib/notices';
export interface BridgeStatus {
connected: boolean;
@@ -72,7 +73,13 @@ export type ControlRequest =
| { id: string; op: 'decide'; request: string; allow: boolean; label?: string }
| { id: string; op: 'pairing'; set?: PairingMode }
| { id: string; op: 'blocked' }
- | { id: string; op: 'label'; session: string; label: string };
+ | { id: string; op: 'label'; session: string; label: string }
+ /** The desktop app: `watch` makes it the one that shows notices, `allowed` whether the computer lets it. Sent again when that changes. */
+ | { id: string; op: 'notices'; watch?: boolean; allowed?: boolean }
+ /** Hands over every notice waiting to be shown, and forgets them. */
+ | { id: string; op: 'takeNotices' }
+ /** Someone clicked a notice: the browser it came from brings its tab to the front. */
+ | { id: string; op: 'openNotice'; notice: string };
export type ControlMessage =
| { id: string; op: 'describe'; tools: ToolDescriptor[]; reserved?: string[]; withheld?: ToolDescriptor[] }
@@ -91,9 +98,14 @@ export type ControlMessage =
| { id: string; op: 'pairing'; mode: PairingMode; approver: Approver; error?: string }
| { id: string; op: 'blocked'; blocked: BlockedBrowser[] }
| { id: string; op: 'label'; ok: boolean; error?: string }
+ | { id: string; op: 'notices'; ok: boolean; error?: string }
+ | { id: string; op: 'takeNotices'; notices: QueuedNotice[] }
+ | { id: string; op: 'openNotice'; ok: boolean }
| { event: 'manifest-changed' }
/** A browser asked to pair, or a request was decided or expired: read `pairRequests` again. */
| { event: 'pair-requests-changed' }
+ /** A notice is waiting: call `takeNotices`. */
+ | { event: 'notices-changed' }
/** config.json changed, from any side: read the preferences and the agent state again. */
| { event: 'settings-changed' }
| { event: 'android-changed'; state: AndroidState };
diff --git a/src/daemon/daemon.ts b/src/daemon/daemon.ts
index 872f453..2824341 100644
--- a/src/daemon/daemon.ts
+++ b/src/daemon/daemon.ts
@@ -59,6 +59,8 @@ import {
} from './auth-store';
import { MAX_PAIR_WAIT_MS, isPairingMode, type Approver, type GrantOutcome, type PairedBy, type RefusalCode } from '@/lib/pairing';
import { pairingDesk } from './pairing-desk';
+import { noticeDesk } from './notice-desk';
+import { NOTICE_PROTOCOL, asDeviceNotice } from '@/lib/notices';
import { desktopApp, launchDesktopApp } from './desktop-app';
import { AgentSession } from './agent/service';
import { androidOff, type Android } from './android/service';
@@ -263,6 +265,12 @@ export async function startDaemon({ version, idleExit = true, android = androidO
},
});
+ const notices = noticeDesk({
+ changed: () => {
+ for (const ws of notices.watchers()) send(ws as WebSocket, { event: 'notices-changed' });
+ },
+ });
+
const http = createServer((req, res) => {
if (!fromLoopback(req)) {
res.writeHead(403).end();
@@ -481,6 +489,12 @@ export async function startDaemon({ version, idleExit = true, android = androidO
settleOffer();
},
(request, source) => {
+ if (request.t === 'notice') {
+ const notice = asDeviceNotice(request.notice);
+ const delivered = !!notice && notices.offer(notice, { id: source.id, browser: source.label });
+ if (notice) log(`notice ${notice.id} from ${source.label}: ${delivered ? 'handed to the app' : 'no app to show it'}`);
+ return source.send({ t: 'noticeAck', id: request.id, delivered });
+ }
if (request.t === 'analyzeFile') {
void analyses
.start(request, readAgentConfig(), source)
@@ -996,6 +1010,23 @@ export async function startDaemon({ version, idleExit = true, android = androidO
const ok = typeof request.session === 'string' && typeof request.label === 'string' && labelSession(request.session, request.label);
return send(ws, { id: request.id, op: 'label', ok });
}
+ if (request.op === 'notices' || request.op === 'takeNotices' || request.op === 'openNotice') {
+ if (speaksForRun) {
+ log(`control ${client} tried to handle notices from inside an agent run; refused`);
+ if (request.op === 'takeNotices') return send(ws, { id: request.id, op: 'takeNotices', notices: [] });
+ return send(ws, { id: request.id, op: request.op, ok: false });
+ }
+ if (request.op === 'notices') {
+ if (request.watch) notices.watch(ws, request.allowed === true);
+ return send(ws, { id: request.id, op: 'notices', ok: true });
+ }
+ if (request.op === 'takeNotices') return send(ws, { id: request.id, op: 'takeNotices', notices: notices.take() });
+ const route = typeof request.notice === 'string' ? notices.routeOf(request.notice) : undefined;
+ const link = route ? links.get(route) : undefined;
+ const ok = !!link?.isOpen && link.speaks(NOTICE_PROTOCOL);
+ if (ok) link!.send({ t: 'openNotice', noticeId: request.notice });
+ return send(ws, { id: request.id, op: 'openNotice', ok });
+ }
if (request.op === 'revoke') {
const { session: id, origin } = request;
const revoked = revokeSessions((session) => (id ? sessionId(session) === id : !origin || session.origin === origin));
@@ -1012,6 +1043,7 @@ export async function startDaemon({ version, idleExit = true, android = androidO
controls.delete(ws);
settingsWatchers.delete(ws);
approvers.delete(ws);
+ notices.unwatch(ws);
unwatchAndroid(ws);
scheduleIdleExit();
};
diff --git a/src/daemon/extension-link.ts b/src/daemon/extension-link.ts
index b5a4fe9..297a235 100644
--- a/src/daemon/extension-link.ts
+++ b/src/daemon/extension-link.ts
@@ -142,7 +142,8 @@ export class ExtensionLink {
if (frame.t === 'pong') return;
if (frame.t === 'focus') return void (this.lastActive = touched());
if (isExtensionRequest(frame)) {
- this.lastActive = touched();
+ // A notice is sent because nobody is looking at this browser, so it says nothing about where the user is.
+ if (frame.t !== 'notice') this.lastActive = touched();
return this.onRequest?.(frame, this);
}
diff --git a/src/daemon/notice-desk.test.ts b/src/daemon/notice-desk.test.ts
new file mode 100644
index 0000000..38e59a3
--- /dev/null
+++ b/src/daemon/notice-desk.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { DeviceNotice } from '@/lib/notices';
+import { noticeDesk } from './notice-desk';
+
+const done: DeviceNotice = { id: 'monitor:m1', kind: 'monitor', title: 'Done: build', body: 'Finished after 3:12.', tone: 'live' };
+const from = { id: 'install-notice-chrome', browser: 'Google Chrome' };
+
+function desk() {
+ let clock = 1_000_000;
+ const changed = vi.fn();
+ return { desk: noticeDesk({ changed, now: () => clock }), changed, advance: (ms: number) => (clock += ms) };
+}
+
+describe('the notice desk', () => {
+ it('takes nothing while no app may show it, so the browser shows its own card', () => {
+ const { desk: built, changed } = desk();
+ expect(built.offer(done, from)).toBe(false);
+
+ built.watch({}, false);
+ expect(built.offer(done, from)).toBe(false);
+ expect(changed).not.toHaveBeenCalled();
+ });
+
+ it('queues a notice for an app that may show it, says so, and hands it over once', () => {
+ const { desk: built, changed } = desk();
+ built.watch({}, true);
+
+ expect(built.offer(done, from)).toBe(true);
+ expect(changed).toHaveBeenCalledOnce();
+ expect(built.take()).toEqual([{ ...done, browser: 'Google Chrome', at: 1_000_000 }]);
+ expect(built.take()).toEqual([]);
+ });
+
+ it('replaces a repeat of the same notice rather than stacking it', () => {
+ const { desk: built } = desk();
+ built.watch({}, true);
+ built.offer(done, from);
+ built.offer({ ...done, body: 'Finished after 3:13.' }, from);
+ expect(built.take().map((notice) => notice.body)).toEqual(['Finished after 3:13.']);
+ });
+
+ it('drops a notice nobody took within five minutes', () => {
+ const { desk: built, advance } = desk();
+ built.watch({}, true);
+ built.offer(done, from);
+ advance(5 * 60_000);
+ expect(built.take()).toEqual([]);
+ });
+
+ it('remembers which browser a notice came from after it was taken, for a click', () => {
+ const { desk: built } = desk();
+ built.watch({}, true);
+ built.offer(done, from);
+ built.take();
+ expect(built.routeOf(done.id)).toBe(from.id);
+ expect(built.routeOf('monitor:other')).toBeUndefined();
+ });
+
+ it('stops counting an app once it goes, or once notifications are turned off', () => {
+ const { desk: built } = desk();
+ const app = {};
+ built.watch(app, true);
+ expect(built.canShow()).toBe(true);
+ built.watch(app, false);
+ expect(built.canShow()).toBe(false);
+ built.watch(app, true);
+ built.unwatch(app);
+ expect(built.canShow()).toBe(false);
+ });
+});
diff --git a/src/daemon/notice-desk.ts b/src/daemon/notice-desk.ts
new file mode 100644
index 0000000..2ced413
--- /dev/null
+++ b/src/daemon/notice-desk.ts
@@ -0,0 +1,54 @@
+/**
+ * Holds the notices a browser hands over until the Browsentic app takes them. A notice is taken only
+ * while an app that may show notifications is watching; otherwise the browser is told no at once and
+ * shows its own card. Nothing here is written to disk: a notice is worth showing for minutes, not more.
+ */
+
+import type { DeviceNotice, QueuedNotice } from '@/lib/notices';
+
+const KEEP_MS = 5 * 60_000;
+const QUEUE_MAX = 20;
+/** Which browser each recent notice came from, so a click reaches it after the app has taken the notice. */
+const ROUTES_MAX = 50;
+
+export interface NoticeDesk {
+ watch(watcher: object, allowed: boolean): void;
+ unwatch(watcher: object): void;
+ canShow(): boolean;
+ watchers(): object[];
+ /** True when an app will show it. */
+ offer(notice: DeviceNotice, from: { id: string; browser?: string }): boolean;
+ take(): QueuedNotice[];
+ /** The browser a notice came from. */
+ routeOf(noticeId: string): string | undefined;
+}
+
+export function noticeDesk({ changed, now = Date.now }: { changed: () => void; now?: () => number }): NoticeDesk {
+ const allowedBy = new Map<object, boolean>();
+ let queue: QueuedNotice[] = [];
+ const routes = new Map<string, string>();
+
+ const canShow = () => [...allowedBy.values()].some(Boolean);
+
+ return {
+ watch: (watcher, allowed) => void allowedBy.set(watcher, allowed),
+ unwatch: (watcher) => void allowedBy.delete(watcher),
+ canShow,
+ watchers: () => [...allowedBy.keys()],
+ offer(notice, from) {
+ if (!canShow()) return false;
+ queue = [...queue.filter((queued) => queued.id !== notice.id), { ...notice, browser: from.browser, at: now() }].slice(-QUEUE_MAX);
+ routes.delete(notice.id);
+ routes.set(notice.id, from.id);
+ for (const oldest of [...routes.keys()].slice(0, Math.max(0, routes.size - ROUTES_MAX))) routes.delete(oldest);
+ changed();
+ return true;
+ },
+ take() {
+ const fresh = queue.filter((queued) => now() - queued.at < KEEP_MS);
+ queue = [];
+ return fresh;
+ },
+ routeOf: (noticeId) => routes.get(noticeId),
+ };
+}
diff --git a/src/daemon/remote-bridge.ts b/src/daemon/remote-bridge.ts
index 5e0ea84..ab9f066 100644
--- a/src/daemon/remote-bridge.ts
+++ b/src/daemon/remote-bridge.ts
@@ -9,6 +9,7 @@ import type { AgentKind, AgentState } from '@/lib/agents/catalog';
import type { AndroidState } from '@/lib/phone/types';
import { AWAIT_DEFAULT_TIMEOUT_MS } from '@/lib/monitor/events';
import type { Approver, BlockedBrowser, GrantOutcome, PairRequestSummary, PairingMode } from '@/lib/pairing';
+import type { QueuedNotice } from '@/lib/notices';
import type { Bridge, BridgeStatus, ControlMessage, ControlRequest, Described, SessionSummary } from './control';
const REQUEST_TIMEOUT_MS = 60_000;
@@ -18,6 +19,7 @@ export class RemoteBridge implements Bridge {
private readonly manifestListeners = new Set<() => void>();
private readonly androidListeners = new Set<(state: AndroidState) => void>();
private readonly pairRequestListeners = new Set<() => void>();
+ private readonly noticeListeners = new Set<() => void>();
private constructor(
private readonly socket: WebSocket,
@@ -94,6 +96,26 @@ export class RemoteBridge implements Bridge {
this.pairRequestListeners.add(listener);
}
+ /** Shows the browsers' notices from now on, while `allowed` says notifications will appear. */
+ async watchNotices(allowed: boolean): Promise<boolean> {
+ const reply = await this.request({ id: randomUUID(), op: 'notices', watch: true, allowed }, 5_000);
+ return !!reply && 'op' in reply && reply.op === 'notices' && reply.ok;
+ }
+
+ async takeNotices(): Promise<QueuedNotice[]> {
+ const reply = await this.request({ id: randomUUID(), op: 'takeNotices' }, 5_000);
+ return reply && 'notices' in reply ? reply.notices : [];
+ }
+
+ async openNotice(notice: string): Promise<boolean> {
+ const reply = await this.request({ id: randomUUID(), op: 'openNotice', notice }, 5_000);
+ return !!reply && 'op' in reply && reply.op === 'openNotice' && reply.ok;
+ }
+
+ onNoticesChanged(listener: () => void): void {
+ this.noticeListeners.add(listener);
+ }
+
async pair(): Promise<{ code: string; expiresAt: number }> {
const reply = await this.request({ id: randomUUID(), op: 'pair' });
if (reply && 'code' in reply) return reply;
@@ -180,6 +202,7 @@ export class RemoteBridge implements Bridge {
if (message.event === 'manifest-changed') for (const listener of this.manifestListeners) listener();
if (message.event === 'android-changed') for (const listener of this.androidListeners) listener(message.state);
if (message.event === 'pair-requests-changed') for (const listener of this.pairRequestListeners) listener();
+ if (message.event === 'notices-changed') for (const listener of this.noticeListeners) listener();
return;
}
this.pending.get(message.id)?.(message);
diff --git a/src/daemon/test/notices.test.ts b/src/daemon/test/notices.test.ts
new file mode 100644
index 0000000..4d401c2
--- /dev/null
+++ b/src/daemon/test/notices.test.ts
@@ -0,0 +1,109 @@
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
+import { CHROME_WEB_STORE } from '@/lib/stores';
+import type { SocketFrame } from '@/lib/actions/protocol';
+import type { DeviceNotice } from '@/lib/notices';
+import { clearAuth } from '../auth-store';
+import { startDaemon, type Daemon } from '../daemon';
+import { readLockfile } from '../lockfile';
+import { RemoteBridge } from '../remote-bridge';
+import { FakeBrowser, type Profile } from './fake-browser';
+
+const chrome: Profile = { origin: `chrome-extension://${CHROME_WEB_STORE.id}`, installId: 'install-notice-chrome1', browser: 'Google Chrome' };
+const done: DeviceNotice = { id: 'monitor:build', kind: 'monitor', title: 'Done: build', body: 'Finished after 3:12.', tone: 'live' };
+
+let daemon: Daemon;
+let opened: { close(): unknown }[] = [];
+
+beforeAll(async () => {
+ daemon = await startDaemon({ version: '0.0.0-test', idleExit: false });
+});
+
+afterAll(async () => {
+ await daemon?.stop();
+});
+
+afterEach(async () => {
+ for (const each of opened) each.close();
+ opened = [];
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ clearAuth();
+});
+
+async function control(runId?: string): Promise<RemoteBridge> {
+ const bridge = await RemoteBridge.connect(daemon.port, readLockfile()!.token, runId);
+ opened.push(bridge);
+ return bridge;
+}
+
+async function browserAt(profile: Profile): Promise<FakeBrowser> {
+ const { code } = await (await control()).pair();
+ const browser = await FakeBrowser.connect(daemon.port, profile, { kind: 'pair', code });
+ opened.push(browser);
+ return browser;
+}
+
+async function offer(browser: FakeBrowser, notice: DeviceNotice = done): Promise<boolean> {
+ const answer = await browser.ask({ t: 'notice', id: crypto.randomUUID(), notice });
+ return answer.t === 'noticeAck' && answer.delivered;
+}
+
+describe('notices for the Browsentic app', () => {
+ test('a browser hears no app is there to show them, and shows its own card', async () => {
+ expect(await offer(await browserAt(chrome))).toBe(false);
+ });
+
+ test('an app whose notifications are off takes none either', async () => {
+ await (await control()).watchNotices(false);
+ expect(await offer(await browserAt(chrome))).toBe(false);
+ });
+
+ test('an app that may show them is told, takes the notice once, with the browser it came from', async () => {
+ const app = await control();
+ let told = 0;
+ app.onNoticesChanged(() => told++);
+ await app.watchNotices(true);
+
+ expect(await offer(await browserAt(chrome))).toBe(true);
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ expect(told).toBe(1);
+ expect(await app.takeNotices()).toEqual([expect.objectContaining({ ...done, browser: 'Google Chrome' })]);
+ expect(await app.takeNotices()).toEqual([]);
+ });
+
+ test('a click brings the browser that sent it back with that notice', async () => {
+ const app = await control();
+ await app.watchNotices(true);
+ const browser = await browserAt(chrome);
+ await offer(browser);
+ await app.takeNotices();
+
+ expect(await app.openNotice(done.id)).toBe(true);
+ const [opened] = await browser.frames('openNotice');
+ expect(opened).toEqual({ t: 'openNotice', noticeId: done.id } satisfies SocketFrame);
+ expect(await app.openNotice('monitor:nobody')).toBe(false);
+ });
+
+ test('a notice that names no kind, title or body is taken by nobody', async () => {
+ await (await control()).watchNotices(true);
+ const browser = await browserAt(chrome);
+ expect(await offer(browser, { ...done, kind: 'other' as never })).toBe(false);
+ expect(await offer(browser, { ...done, title: 3 as never })).toBe(false);
+ });
+
+ test('an agent run can neither show nor take notices, nor open one', async () => {
+ const run = await control('run-under-test');
+ await run.describe();
+ expect(await run.watchNotices(true)).toBe(false);
+ expect(await offer(await browserAt(chrome))).toBe(false);
+ expect(await run.takeNotices()).toEqual([]);
+ expect(await run.openNotice(done.id)).toBe(false);
+ });
+
+ test('a browser on a protocol before notices is never sent a click it cannot read', async () => {
+ const app = await control();
+ await app.watchNotices(true);
+ const older = await browserAt({ ...chrome, protocolVersion: 23 });
+ await offer(older);
+ expect(await app.openNotice(done.id)).toBe(false);
+ });
+});
diff --git a/src/lib/actions/protocol.ts b/src/lib/actions/protocol.ts
index d0b07df..1465b59 100644
--- a/src/lib/actions/protocol.ts
+++ b/src/lib/actions/protocol.ts
@@ -10,11 +10,12 @@ import type { SkillCategory, SkillDraft } from '@/lib/skills/format';
import type { SiteMapDraft } from '@/lib/skills/site-map';
import type { TaskContext, TaskList, TaskOrder, TaskResult } from '@/lib/schedules/task';
import type { RefusalCode } from '@/lib/pairing';
+import type { DeviceNotice } from '@/lib/notices';
export const ACTION_CHANNEL = 'browsentic/action';
export const BRIDGE_CHANNEL = 'browsentic/bridge';
-export const SOCKET_PROTOCOL_VERSION = 23;
+export const SOCKET_PROTOCOL_VERSION = 24;
/** The first protocol with the Android frames: `androidInfo`, the phone requests, `cdpEvent` and `phoneClosed`. */
export const ANDROID_PROTOCOL = 23;
@@ -243,6 +244,12 @@ export type SocketFrame =
| { t: 'ping'; id: string }
| { t: 'pong'; id: string }
| { t: 'focus' }
+ /** A finished monitor, task or timer for the Browsentic app to show while the browser is behind. Protocol 24. */
+ | { t: 'notice'; id: string; notice: DeviceNotice }
+ /** Whether an app that may show notifications took it; false sends the browser back to its own card. */
+ | { t: 'noticeAck'; id: string; delivered: boolean }
+ /** Someone clicked that notice: bring its tab to the front. */
+ | { t: 'openNotice'; noticeId: string }
| { t: 'instruct'; id: string; text: string; context?: RunContext }
| { t: 'cancel'; id: string }
| { t: 'decision'; id: string; toolId: string; allow: boolean; remember?: boolean }
@@ -342,6 +349,7 @@ export const EXTENSION_REQUEST_FRAMES = [
'phoneClose',
'phoneLaunch',
'cdp',
+ 'notice',
] as const;
export type ExtensionRequest = Extract<SocketFrame, { t: (typeof EXTENSION_REQUEST_FRAMES)[number] }>;
diff --git a/src/lib/notices.ts b/src/lib/notices.ts
new file mode 100644
index 0000000..0e90a28
--- /dev/null
+++ b/src/lib/notices.ts
@@ -0,0 +1,45 @@
+/**
+ * Notices the browser hands to the Browsentic app, which shows them as the computer's own notifications
+ * while the browser is behind other windows or minimized. The browser keeps its own card and its own
+ * notification for everything else: no app, notifications not allowed, or the browser in front.
+ */
+
+/** The first protocol with `notice`, `noticeAck` and `openNotice`. */
+export const NOTICE_PROTOCOL = 24;
+
+export type NoticeKind = 'monitor' | 'task' | 'timer';
+
+export type NoticeTone = 'live' | 'warn';
+
+export interface DeviceNotice {
+ /** Stable for one event, so the app replaces rather than stacks a repeat. */
+ id: string;
+ kind: NoticeKind;
+ title: string;
+ body: string;
+ tone: NoticeTone;
+}
+
+export interface QueuedNotice extends DeviceNotice {
+ /** The browser it came from, as the app lists it. */
+ browser?: string;
+ at: number;
+}
+
+const TITLE_MAX = 120;
+const BODY_MAX = 400;
+const KINDS: readonly NoticeKind[] = ['monitor', 'task', 'timer'];
+
+export function asDeviceNotice(value: unknown): DeviceNotice | null {
+ const notice = value as Partial<Record<keyof DeviceNotice, unknown>> | null;
+ if (!notice || typeof notice.id !== 'string' || !notice.id || notice.id.length > 120) return null;
+ if (typeof notice.title !== 'string' || typeof notice.body !== 'string') return null;
+ if (!KINDS.includes(notice.kind as NoticeKind)) return null;
+ return {
+ id: notice.id,
+ kind: notice.kind as NoticeKind,
+ title: notice.title.slice(0, TITLE_MAX),
+ body: notice.body.slice(0, BODY_MAX),
+ tone: notice.tone === 'warn' ? 'warn' : 'live',
+ };
+}