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(monitor): watch a page's progress signals from the content script

Shahriar4368b6f94b01
diff --git a/entrypoints/content.ts b/entrypoints/content.ts
index 8efc5ae..9a419e3 100644
--- a/entrypoints/content.ts
+++ b/entrypoints/content.ts
@@ -1,4 +1,5 @@
import { exposeActions } from '@/lib/actions/host';
+import { exposeMonitor } from '@/lib/monitor/watch';
import { exposeRecorder } from '@/lib/recordings/host';
export default defineContentScript({
@@ -9,5 +10,6 @@ export default defineContentScript({
world.__browsenticActions = true;
exposeActions();
exposeRecorder();
+ exposeMonitor();
},
});
diff --git a/lib/actions/protocol.ts b/lib/actions/protocol.ts
index 2665587..a5b36c2 100644
--- a/lib/actions/protocol.ts
+++ b/lib/actions/protocol.ts
@@ -1,4 +1,5 @@
import type { ToolDescriptor } from './manifest';
+import type { MonitorSample } from '@/lib/monitor/events';
import type { RecordedEvent } from '@/lib/recordings/events';
import type { RecordingWorkflow } from '@/lib/recordings/workflow';
import type { SkillDraft } from '@/lib/skills/format';
@@ -30,7 +31,9 @@ export type BridgeRequest =
| { channel: typeof BRIDGE_CHANNEL; op: 'nameSession'; sessionId: string }
| { channel: typeof BRIDGE_CHANNEL; op: 'recordEvents'; events: RecordedEvent[] }
| { channel: typeof BRIDGE_CHANNEL; op: 'recordingState' }
- | { channel: typeof BRIDGE_CHANNEL; op: 'analyzeRecording'; recordingId: string };
+ | { channel: typeof BRIDGE_CHANNEL; op: 'analyzeRecording'; recordingId: string }
+ | { channel: typeof BRIDGE_CHANNEL; op: 'monitorSample'; monitorId: string; sample: MonitorSample }
+ | { channel: typeof BRIDGE_CHANNEL; op: 'monitorState' };
export type ActionResult<T = unknown> =
| { ok: true; data: T }
diff --git a/lib/monitor/events.ts b/lib/monitor/events.ts
new file mode 100644
index 0000000..40d2130
--- /dev/null
+++ b/lib/monitor/events.ts
@@ -0,0 +1,130 @@
+import type { Target } from '@/lib/actions/page/dom';
+
+export const MONITOR_CHANNEL = 'browsentic/monitor';
+
+export const MAX_MONITORS = 3;
+export const DEFAULT_MONITOR_TIMEOUT_MS = 30 * 60_000;
+export const MAX_MONITOR_TIMEOUT_MS = 4 * 60 * 60_000;
+export const AWAIT_DEFAULT_TIMEOUT_MS = 2 * 60_000;
+export const AWAIT_MAX_TIMEOUT_MS = 10 * 60_000;
+export const STALL_WARN_MS = 2 * 60_000;
+export const SAMPLE_MIN_INTERVAL_MS = 3_000;
+export const EVAL_DEBOUNCE_MS = 500;
+export const BACKSTOP_INTERVAL_MS = 5_000;
+export const MAX_LOGS = 50;
+export const MAX_SAMPLES = 24;
+export const MAX_DONE_KEPT = 6;
+export const LOG_MIN_PERCENT_STEP = 5;
+export const LOG_MIN_INTERVAL_MS = 30_000;
+export const MAX_TEXT_SCAN_CHARS = 30_000;
+export const STATUS_LOG_TAIL = 5;
+
+export const WATCH_ALARM = 'browsentic/monitor-watch';
+export const TIMEOUT_ALARM_PREFIX = 'browsentic/monitor-timeout:';
+
+export const timeoutAlarm = (monitorId: string): string => `${TIMEOUT_ALARM_PREFIX}${monitorId}`;
+
+export const NOTIFICATION_PREFIX = 'browsentic-monitor:';
+
+export type UntilKind =
+ | 'element-appears'
+ | 'element-vanishes'
+ | 'text-matches'
+ | 'progress-reaches'
+ | 'title-matches';
+
+export interface MonitorUntil {
+ kind: UntilKind;
+ target?: Target;
+ pattern?: string;
+ threshold: number;
+}
+
+export interface MonitorSample {
+ t: number;
+ percent?: number;
+ matched?: boolean;
+ text?: string;
+}
+
+export interface MonitorLogEntry {
+ t: number;
+ text: string;
+}
+
+export type MonitorPhase = 'watching' | 'done' | 'timeout' | 'stopped' | 'tab-closed' | 'tab-navigated';
+
+export interface MonitorState {
+ monitorId: string;
+ tabId: number;
+ host: string;
+ label?: string;
+ until: MonitorUntil;
+ startedAt: number;
+ elapsedMs: number;
+ timeoutMs: number;
+ phase: MonitorPhase;
+ percent?: number;
+ etaMs?: number;
+ stalledForMs?: number;
+ logs: MonitorLogEntry[];
+ message?: string;
+}
+
+const NEEDS_TARGET: readonly UntilKind[] = ['element-appears', 'element-vanishes', 'progress-reaches'];
+const NEEDS_PATTERN: readonly UntilKind[] = ['text-matches', 'title-matches'];
+
+export function requiredFieldsError(until: MonitorUntil): string | null {
+ if (NEEDS_TARGET.includes(until.kind) && !until.target?.selector && !until.target?.text) {
+ return `until.kind "${until.kind}" needs a "target" with a selector or text — page.findProgress lists candidates with their selectors`;
+ }
+ if (NEEDS_PATTERN.includes(until.kind)) {
+ if (!until.pattern) {
+ return `until.kind "${until.kind}" needs a "pattern" — a regular expression for the text that marks completion, e.g. "upload complete|processing finished"`;
+ }
+ try {
+ new RegExp(until.pattern, 'i');
+ } catch (error) {
+ return `until.pattern is not a valid regular expression: ${error instanceof Error ? error.message : String(error)}`;
+ }
+ }
+ return null;
+}
+
+export function describeUntil(until: MonitorUntil): string {
+ const targetLabel = until.target?.text ?? until.target?.selector ?? '';
+ switch (until.kind) {
+ case 'element-appears':
+ return `until “${targetLabel}” appears`;
+ case 'element-vanishes':
+ return `until “${targetLabel}” disappears`;
+ case 'text-matches':
+ return `until the page ${targetLabel ? `(in “${targetLabel}”) ` : ''}matches /${until.pattern}/`;
+ case 'progress-reaches':
+ return `until “${targetLabel}” reaches ${until.threshold}%`;
+ case 'title-matches':
+ return `until the tab title matches /${until.pattern}/`;
+ }
+}
+
+export function estimate(
+ samples: readonly MonitorSample[],
+ threshold: number,
+): { percent?: number; etaMs?: number } {
+ const dated = samples.filter((sample) => typeof sample.percent === 'number');
+ const latest = dated.at(-1);
+ if (!latest) return {};
+ const percent = latest.percent!;
+ const oldest = dated[0];
+ const spanMs = latest.t - oldest.t;
+ const gained = percent - oldest.percent!;
+ if (dated.length < 2 || spanMs < 10_000 || gained <= 0) return { percent };
+ const etaMs = ((threshold - percent) / gained) * spanMs;
+ return { percent, etaMs: Math.max(0, Math.round(etaMs / 10_000) * 10_000) };
+}
+
+export function formatEta(etaMs: number): string {
+ const minutes = Math.round(etaMs / 60_000);
+ if (minutes < 1) return 'under a minute';
+ return `~${minutes} min`;
+}
diff --git a/lib/monitor/watch.ts b/lib/monitor/watch.ts
new file mode 100644
index 0000000..bf10cfc
--- /dev/null
+++ b/lib/monitor/watch.ts
@@ -0,0 +1,174 @@
+import { browser } from 'wxt/browser';
+import { accessibleText, resolveTarget, type Target } from '@/lib/actions/page/dom';
+import { BRIDGE_CHANNEL } from '@/lib/actions/protocol';
+import {
+ BACKSTOP_INTERVAL_MS,
+ EVAL_DEBOUNCE_MS,
+ MAX_TEXT_SCAN_CHARS,
+ MONITOR_CHANNEL,
+ SAMPLE_MIN_INTERVAL_MS,
+ type MonitorSample,
+ type MonitorUntil,
+} from './events';
+
+export { MONITOR_CHANNEL };
+
+interface MonitorCommand {
+ channel: typeof MONITOR_CHANNEL;
+ op: 'watch' | 'unwatch';
+ monitorId: string;
+ until?: MonitorUntil;
+}
+
+const PERCENT = /(\d{1,3}(?:\.\d+)?)\s?%/;
+const MATCH_CLIP = 120;
+
+export function exposeMonitor(): void {
+ const watchers = new Map<string, () => void>();
+
+ browser.runtime.onMessage.addListener((message: unknown) => {
+ if (!isMonitorCommand(message)) return;
+ if (message.op === 'unwatch') {
+ watchers.get(message.monitorId)?.();
+ watchers.delete(message.monitorId);
+ return;
+ }
+ if (!message.until || watchers.has(message.monitorId)) return;
+ watchers.set(message.monitorId, startWatcher(message.monitorId, message.until));
+ });
+
+ void armed().then((monitors) => {
+ for (const { monitorId, until } of monitors) {
+ if (!watchers.has(monitorId)) watchers.set(monitorId, startWatcher(monitorId, until));
+ }
+ });
+}
+
+function startWatcher(monitorId: string, until: MonitorUntil): () => void {
+ const regex = until.pattern ? compile(until.pattern) : null;
+ let lastSentAt = 0;
+ let lastPercent: number | undefined;
+ let lastMatched: boolean | undefined;
+ let lastText: string | undefined;
+ let debounce: ReturnType<typeof setTimeout> | undefined;
+
+ const evaluate = (): MonitorSample => {
+ const t = Date.now();
+ switch (until.kind) {
+ case 'element-appears':
+ return { t, matched: !!find(until.target) };
+ case 'element-vanishes':
+ return { t, matched: !find(until.target) };
+ case 'progress-reaches': {
+ const el = find(until.target);
+ const percent = el ? readPercent(el) : undefined;
+ return { t, percent, matched: percent != null && percent >= until.threshold };
+ }
+ case 'text-matches': {
+ const el = until.target?.selector || until.target?.text ? find(until.target) : null;
+ const scope = (el ? innerTextOf(el) : document.body?.innerText ?? '').slice(0, MAX_TEXT_SCAN_CHARS);
+ const hit = regex?.exec(scope);
+ return { t, matched: !!hit, text: hit?.[0]?.slice(0, MATCH_CLIP) };
+ }
+ case 'title-matches':
+ return { t, matched: !!regex?.test(document.title), text: document.title.slice(0, MATCH_CLIP) };
+ }
+ };
+
+ const check = () => {
+ const sample = evaluate();
+ const flipped = sample.matched !== lastMatched;
+ const moved = sample.percent != null && (lastPercent == null || Math.abs(sample.percent - lastPercent) >= 1);
+ const reworded = sample.text !== undefined && sample.text !== lastText;
+ if (!flipped && !moved && !reworded) return;
+ if (!sample.matched && sample.t - lastSentAt < SAMPLE_MIN_INTERVAL_MS) return;
+ lastSentAt = sample.t;
+ lastPercent = sample.percent ?? lastPercent;
+ lastMatched = sample.matched;
+ lastText = sample.text ?? lastText;
+ void browser.runtime
+ .sendMessage({ channel: BRIDGE_CHANNEL, op: 'monitorSample', monitorId, sample })
+ .catch(() => undefined);
+ };
+
+ const schedule = () => {
+ clearTimeout(debounce);
+ debounce = setTimeout(check, EVAL_DEBOUNCE_MS);
+ };
+
+ const observer = new MutationObserver(schedule);
+ observer.observe(document.documentElement, {
+ subtree: true,
+ childList: true,
+ attributes: true,
+ characterData: true,
+ });
+ const interval = setInterval(check, BACKSTOP_INTERVAL_MS);
+ check();
+
+ return () => {
+ observer.disconnect();
+ clearInterval(interval);
+ clearTimeout(debounce);
+ };
+}
+
+function find(target: Target | undefined): HTMLElement | null {
+ if (!target) return null;
+ try {
+ return resolveTarget(target, { includeHidden: false });
+ } catch {
+ return null;
+ }
+}
+
+function readPercent(el: HTMLElement): number | undefined {
+ if (el instanceof HTMLProgressElement || el instanceof HTMLMeterElement) {
+ return el.max > 0 ? clamp((el.value / el.max) * 100) : undefined;
+ }
+ const now = parseFloat(el.getAttribute('aria-valuenow') ?? '');
+ if (Number.isFinite(now)) {
+ const min = parseFloat(el.getAttribute('aria-valuemin') ?? '0') || 0;
+ const max = parseFloat(el.getAttribute('aria-valuemax') ?? '100') || 100;
+ return max > min ? clamp(((now - min) / (max - min)) * 100) : undefined;
+ }
+ const spoken = PERCENT.exec(el.getAttribute('aria-valuetext') ?? '') ?? PERCENT.exec(accessibleText(el));
+ if (spoken) return clamp(parseFloat(spoken[1]));
+ const width = PERCENT.exec(el.style.width) ?? PERCENT.exec((el.firstElementChild as HTMLElement | null)?.style.width ?? '');
+ return width ? clamp(parseFloat(width[1])) : undefined;
+}
+
+function innerTextOf(el: HTMLElement): string {
+ return el.innerText ?? el.textContent ?? '';
+}
+
+function clamp(percent: number): number {
+ return Math.min(100, Math.max(0, percent));
+}
+
+function compile(pattern: string): RegExp | null {
+ try {
+ return new RegExp(pattern, 'i');
+ } catch {
+ return null;
+ }
+}
+
+async function armed(): Promise<{ monitorId: string; until: MonitorUntil }[]> {
+ try {
+ const state = await browser.runtime.sendMessage({ channel: BRIDGE_CHANNEL, op: 'monitorState' });
+ const data = (state as { ok?: boolean; data?: { monitors?: { monitorId: string; until: MonitorUntil }[] } })?.data;
+ return Array.isArray(data?.monitors) ? data.monitors : [];
+ } catch {
+ return [];
+ }
+}
+
+function isMonitorCommand(message: unknown): message is MonitorCommand {
+ return (
+ typeof message === 'object' &&
+ message !== null &&
+ (message as MonitorCommand).channel === MONITOR_CHANNEL &&
+ typeof (message as MonitorCommand).monitorId === 'string'
+ );
+}