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(monitor): watch a page's progress signals from the content script
Shahriar4368b6f94b01
diff --git a/entrypoints/content.ts b/entrypoints/content.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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'+ );+}