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(actions): find, start, await, and stop background monitors

Shahriarcf9a5ad26e4a
diff --git a/lib/actions/page/await-monitor.ts b/lib/actions/page/await-monitor.ts
new file mode 100644
index 0000000..a8c32ad
--- /dev/null
+++ b/lib/actions/page/await-monitor.ts
@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { AWAIT_DEFAULT_TIMEOUT_MS, AWAIT_MAX_TIMEOUT_MS } from '@/lib/monitor/events';
+import { ActionError, defineAction } from '../core';
+
+export const awaitMonitor = defineAction({
+ name: 'page.awaitMonitor',
+ description:
+ 'Block until a background monitor completes, then return its final state with the full log. ' +
+ 'A reply with settled: false means the timeout passed while the watch continues — call again to keep waiting; that is normal, not an error. ' +
+ 'If the call fails with EXTENSION_OFFLINE the monitor is still running in the browser — reconnect and call again.',
+ input: z.object({
+ monitorId: z.string().describe('The monitor to wait on, from page.startMonitor'),
+ timeoutMs: z
+ .number()
+ .int()
+ .positive()
+ .max(AWAIT_MAX_TIMEOUT_MS)
+ .default(AWAIT_DEFAULT_TIMEOUT_MS)
+ .describe('Return after this long even if unfinished — the reply then has settled: false and the current state, so call again to keep waiting'),
+ }),
+ execute() {
+ throw new ActionError('page.awaitMonitor is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/page/find-progress.ts b/lib/actions/page/find-progress.ts
new file mode 100644
index 0000000..601d1ad
--- /dev/null
+++ b/lib/actions/page/find-progress.ts
@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { defineAction } from '../core';
+import { accessibleText, cssPath, documentBounds, isVisible } from './dom';
+
+const PERCENT = /(\d{1,3}(?:\.\d+)?)\s?%/;
+const SPINNER_CLASS = /spinner|loading|progress/i;
+const TEXT_CLIP = 80;
+
+interface Candidate {
+ kind: 'progressbar' | 'progress-element' | 'percent-text' | 'spinner' | 'busy-region';
+ selector: string;
+ text?: string;
+ value?: number;
+ max?: number;
+ percent?: number;
+ bounds: { x: number; y: number; width: number; height: number };
+}
+
+export const findProgress = defineAction({
+ name: 'page.findProgress',
+ description:
+ 'Scan the page for progress signals worth monitoring: progress bars, percent readouts, spinners and busy regions, each with a selector for page.startMonitor. ' +
+ 'An empty candidates list with no titlePercent means the page shows nothing measurable — ask the user what completion looks like instead of starting a monitor.',
+ input: z.object({
+ maxCandidates: z
+ .number()
+ .int()
+ .positive()
+ .max(30)
+ .default(10)
+ .describe('Cap on candidates returned, strongest signals first'),
+ }),
+ execute({ maxCandidates }) {
+ const candidates: Candidate[] = [
+ ...progressbars(),
+ ...progressElements(),
+ ...percentTexts(),
+ ...spinners(),
+ ...busyRegions(),
+ ];
+ const seen = new Set<string>();
+ const unique = candidates.filter((candidate) => {
+ if (seen.has(candidate.selector)) return false;
+ seen.add(candidate.selector);
+ return true;
+ });
+ const titleMatch = PERCENT.exec(document.title);
+ return {
+ candidates: unique.slice(0, maxCandidates),
+ ...(titleMatch ? { titlePercent: clamp(parseFloat(titleMatch[1])) } : {}),
+ url: location.href,
+ };
+ },
+});
+
+function progressbars(): Candidate[] {
+ return visible('[role="progressbar"]').map((el) => {
+ const now = parseFloat(el.getAttribute('aria-valuenow') ?? '');
+ const min = parseFloat(el.getAttribute('aria-valuemin') ?? '0') || 0;
+ const max = parseFloat(el.getAttribute('aria-valuemax') ?? '100') || 100;
+ const percent = Number.isFinite(now) && max > min ? clamp(((now - min) / (max - min)) * 100) : undefined;
+ return describe(el, 'progressbar', { value: Number.isFinite(now) ? now : undefined, max, percent });
+ });
+}
+
+function progressElements(): Candidate[] {
+ return visible('progress, meter').map((el) => {
+ const bar = el as HTMLProgressElement | HTMLMeterElement;
+ const percent = bar.max > 0 ? clamp((bar.value / bar.max) * 100) : undefined;
+ return describe(el, 'progress-element', { value: bar.value, max: bar.max, percent });
+ });
+}
+
+function percentTexts(): Candidate[] {
+ const walker = document.createTreeWalker(document.body ?? document.documentElement, NodeFilter.SHOW_TEXT);
+ const blocks = new Set<HTMLElement>();
+ for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+ if (!PERCENT.test(node.textContent ?? '')) continue;
+ const block = blockAncestor(node.parentElement);
+ if (block && isVisible(block)) blocks.add(block);
+ }
+ return [...blocks].map((el) => {
+ const text = collapse(el.innerText ?? '');
+ const percent = PERCENT.exec(text);
+ return describe(el, 'percent-text', {
+ text: text.slice(0, TEXT_CLIP),
+ percent: percent ? clamp(parseFloat(percent[1])) : undefined,
+ });
+ });
+}
+
+function spinners(): Candidate[] {
+ return visible('[class]')
+ .filter((el) => SPINNER_CLASS.test(el.getAttribute('class') ?? '') && getComputedStyle(el).animationName !== 'none')
+ .map((el) => describe(el, 'spinner', {}));
+}
+
+function busyRegions(): Candidate[] {
+ return visible('[aria-busy="true"]').map((el) => describe(el, 'busy-region', {}));
+}
+
+function describe(el: HTMLElement, kind: Candidate['kind'], extra: Partial<Candidate>): Candidate {
+ const text = extra.text ?? accessibleText(el).slice(0, TEXT_CLIP);
+ return {
+ kind,
+ selector: cssPath(el),
+ ...(text ? { text } : {}),
+ ...(extra.value != null ? { value: extra.value } : {}),
+ ...(extra.max != null ? { max: extra.max } : {}),
+ ...(extra.percent != null ? { percent: extra.percent } : {}),
+ bounds: documentBounds(el),
+ };
+}
+
+function visible(selector: string): HTMLElement[] {
+ return [...document.querySelectorAll<HTMLElement>(selector)].filter(isVisible);
+}
+
+function blockAncestor(el: HTMLElement | null): HTMLElement | null {
+ for (let node = el; node; node = node.parentElement) {
+ if (getComputedStyle(node).display !== 'inline') return node;
+ }
+ return el;
+}
+
+function collapse(text: string): string {
+ return text.replace(/\s+/g, ' ').trim();
+}
+
+function clamp(percent: number): number {
+ return Math.min(100, Math.max(0, percent));
+}
diff --git a/lib/actions/page/monitor-status.ts b/lib/actions/page/monitor-status.ts
new file mode 100644
index 0000000..c521d70
--- /dev/null
+++ b/lib/actions/page/monitor-status.ts
@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ActionError, defineAction } from '../core';
+
+export const monitorStatus = defineAction({
+ name: 'page.monitorStatus',
+ description:
+ 'Report on background monitors started with page.startMonitor: phase, percent, ETA, how long since anything changed, and the latest log lines.',
+ input: z.object({
+ monitorId: z
+ .string()
+ .optional()
+ .describe('One monitor to report. Omit to list every active and recently finished monitor.'),
+ }),
+ execute() {
+ throw new ActionError('page.monitorStatus is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/page/start-monitor.ts b/lib/actions/page/start-monitor.ts
new file mode 100644
index 0000000..f99374f
--- /dev/null
+++ b/lib/actions/page/start-monitor.ts
@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { DEFAULT_MONITOR_TIMEOUT_MS, MAX_MONITOR_TIMEOUT_MS } from '@/lib/monitor/events';
+import { ActionError, defineAction } from '../core';
+import { targetSchema } from './dom';
+
+export const startMonitor = defineAction({
+ name: 'page.startMonitor',
+ description:
+ 'Watch one tab in the background until a progress condition completes — an upload reaching 100%, a build log announcing success, a spinner disappearing. ' +
+ 'Returns a monitorId immediately; the extension pins the tab, keeps watching with no further tool calls even while the user works elsewhere, and notifies them on completion. ' +
+ 'Call page.findProgress first to pick a real signal. Check on it with page.monitorStatus, block for it with page.awaitMonitor, end it with page.stopMonitor.',
+ input: z.object({
+ until: z
+ .object({
+ kind: z
+ .enum(['element-appears', 'element-vanishes', 'text-matches', 'progress-reaches', 'title-matches'])
+ .describe('What ends the watch'),
+ target: targetSchema
+ .optional()
+ .describe(
+ 'Element to watch — required for element-appears, element-vanishes and progress-reaches; optional scope for text-matches',
+ ),
+ pattern: z
+ .string()
+ .max(200)
+ .optional()
+ .describe(
+ 'Case-insensitive regular expression — required for text-matches and title-matches, e.g. "upload complete|processing finished"',
+ ),
+ threshold: z
+ .number()
+ .min(1)
+ .max(100)
+ .default(100)
+ .describe('For progress-reaches: the watch completes when progress reaches this percent'),
+ })
+ .describe('The condition that completes the watch'),
+ label: z
+ .string()
+ .max(80)
+ .optional()
+ .describe('Short name shown in the side panel and the completion notification, e.g. "YouTube upload"'),
+ tabId: z
+ .number()
+ .int()
+ .optional()
+ .describe('Tab to watch, from page.openTab or page.switchTab. Defaults to the active tab.'),
+ timeoutMs: z
+ .number()
+ .int()
+ .positive()
+ .max(MAX_MONITOR_TIMEOUT_MS)
+ .default(DEFAULT_MONITOR_TIMEOUT_MS)
+ .describe('Give up and report a timeout after this long'),
+ }),
+ execute() {
+ throw new ActionError('page.startMonitor is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/page/stop-monitor.ts b/lib/actions/page/stop-monitor.ts
new file mode 100644
index 0000000..dcd4674
--- /dev/null
+++ b/lib/actions/page/stop-monitor.ts
@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ActionError, defineAction } from '../core';
+
+export const stopMonitor = defineAction({
+ name: 'page.stopMonitor',
+ description:
+ 'Stop a background monitor before it completes. The tab is unpinned again if the monitor pinned it. No notification is shown — the stop was asked for.',
+ input: z.object({
+ monitorId: z
+ .string()
+ .optional()
+ .describe('Omit when only one monitor is running; with several running an omitted id stops nothing and the candidates are listed.'),
+ }),
+ execute() {
+ throw new ActionError('page.stopMonitor is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/registry.ts b/lib/actions/registry.ts
index 01dcdbe..96ad9e7 100644
--- a/lib/actions/registry.ts
+++ b/lib/actions/registry.ts
@@ -2,16 +2,19 @@ import { z } from 'zod';
import type { AnyAction } from './core';
import type { ToolDescriptor } from './manifest';
import { attachFile } from './page/attach-file';
+import { awaitMonitor } from './page/await-monitor';
import { clickElement } from './page/click-element';
import { closeTab } from './page/close-tab';
import { extractText } from './page/extract-text';
import { fillInput } from './page/fill-input';
+import { findProgress } from './page/find-progress';
import { focusInput } from './page/focus-input';
import { getPageInfo } from './page/get-page-info';
import { highlightElement } from './page/highlight-element';
import { hoverElement } from './page/hover-element';
import { listFiles } from './page/list-files';
import { listRecordings } from './page/list-recordings';
+import { monitorStatus } from './page/monitor-status';
import { navigate } from './page/navigate';
import { openTab } from './page/open-tab';
import { pressKey } from './page/press-key';
@@ -20,6 +23,8 @@ import { screenshot } from './page/screenshot';
import { scrollTo } from './page/scroll-to';
import { selectOption } from './page/select-option';
import { selectText } from './page/select-text';
+import { startMonitor } from './page/start-monitor';
+import { stopMonitor } from './page/stop-monitor';
import { submitForm } from './page/submit-form';
import { switchTab } from './page/switch-tab';
import { typeText } from './page/type-text';
@@ -41,6 +46,11 @@ export const actions: ReadonlyMap<string, AnyAction> = new Map(
pressKey,
submitForm,
waitForElement,
+ findProgress,
+ startMonitor,
+ monitorStatus,
+ awaitMonitor,
+ stopMonitor,
highlightElement,
navigate,
openTab,
diff --git a/lib/bridge/invoke.ts b/lib/bridge/invoke.ts
index 7110e88..0918756 100644
--- a/lib/bridge/invoke.ts
+++ b/lib/bridge/invoke.ts
@@ -3,16 +3,21 @@ import { z } from 'zod';
import { invokeInTab } from '@/lib/actions/client';
import { ActionError } from '@/lib/actions/core';
import { attachFile } from '@/lib/actions/page/attach-file';
+import { awaitMonitor } from '@/lib/actions/page/await-monitor';
import { closeTab } from '@/lib/actions/page/close-tab';
import { listFiles } from '@/lib/actions/page/list-files';
import { listRecordings } from '@/lib/actions/page/list-recordings';
+import { monitorStatus } from '@/lib/actions/page/monitor-status';
import { navigate, resolveNavigation, type NavigateInput } from '@/lib/actions/page/navigate';
import { openTab } from '@/lib/actions/page/open-tab';
import { readRecording } from '@/lib/actions/page/read-recording';
import { screenshot } from '@/lib/actions/page/screenshot';
+import { startMonitor } from '@/lib/actions/page/start-monitor';
+import { stopMonitor } from '@/lib/actions/page/stop-monitor';
import { switchTab } from '@/lib/actions/page/switch-tab';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import { listMeta, readBytes } from '@/lib/bridge/file-store';
+import { awaitMonitorDone, monitorStatusFor, startTabMonitor, stopTabMonitor } from '@/lib/bridge/monitor';
import { listRecordings as listStoredMeta, readRecordingBody } from '@/lib/bridge/recording-store';
import { screenshotTab } from '@/lib/bridge/screenshot';
import { closeOpenTab, openNewTab, switchToTab, watchForLoad } from '@/lib/bridge/tabs';
@@ -22,6 +27,10 @@ export async function invokeForHarness(action: string, input?: unknown, tabId?:
if (action === listRecordings.name) return listStoredRecordings(input);
if (action === readRecording.name) return readStoredRecording(input);
if (action === openTab.name) return openNewTab(input);
+ if (action === startMonitor.name) return beginMonitor(input, tabId);
+ if (action === monitorStatus.name) return statusOfMonitors(input);
+ if (action === stopMonitor.name) return stopRequestedMonitor(input);
+ if (action === awaitMonitor.name) return awaitRequestedMonitor(input);
const tab = tabId == null ? (await browser.tabs.query({ active: true, currentWindow: true }))[0] : await pinnedTab(tabId);
if (tab?.id == null) {
@@ -45,6 +54,30 @@ async function pinnedTab(tabId: number) {
}
}
+async function beginMonitor(input: unknown, tabId?: number): Promise<ActionResult> {
+ const parsed = startMonitor.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return startTabMonitor(parsed.data, tabId);
+}
+
+async function statusOfMonitors(input: unknown): Promise<ActionResult> {
+ const parsed = monitorStatus.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return monitorStatusFor(parsed.data.monitorId);
+}
+
+async function stopRequestedMonitor(input: unknown): Promise<ActionResult> {
+ const parsed = stopMonitor.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return stopTabMonitor(parsed.data.monitorId);
+}
+
+async function awaitRequestedMonitor(input: unknown): Promise<ActionResult> {
+ const parsed = awaitMonitor.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return awaitMonitorDone(parsed.data.monitorId, parsed.data.timeoutMs);
+}
+
async function listStoredFiles(input: unknown): Promise<ActionResult> {
const filter = (input as { nameContains?: unknown } | undefined)?.nameContains;
const needle = typeof filter === 'string' ? filter.toLowerCase() : null;