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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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.tsindex 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.tsindex 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 = androidOsettleOffer();},(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 = androidOconst 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 = androidOcontrols.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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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',+ };+}