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(actions): find, start, await, and stop background monitors
Shahriarcf9a5ad26e4a
diff --git a/lib/actions/page/await-monitor.ts b/lib/actions/page/await-monitor.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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;