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(timers): schedule a job the browser wakes you for

Shahriar650dcaabce7d
diff --git a/README.md b/README.md
index b99be5b..5fdf913 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Hand your real, logged-in browser to the AI agent you already run. Browsentic is
- **Your Real Browser, Not a Headless One**: Drives the tab in front of you, in your own profile, with your own logins and sessions
- **Bring Your Own Agent**: Runs on the agent CLI you already pay for and are already signed in to — switch between Claude Code, Codex and Antigravity with one click
-- **38 Page Capabilities**: Reading, clicking, typing, dragging, on-site search, form submission, navigation, screenshots, captchas, theming and accessibility, background progress monitoring, and pointing at an element
+- **41 Page Capabilities**: Reading, clicking, typing, dragging, on-site search, form submission, navigation, screenshots, captchas, theming and accessibility, background progress monitoring, scheduled and repeating jobs, and pointing at an element
- **Voice, Text, or Demonstration**: Dictate in the side panel, type anywhere, or record yourself doing a job once and later say "do it like last time"
- **Point at What You Mean (A-Eye)**: Press the lens, hover the page, click the thing — the element and its content ride along with your next message, and the agent can hand the lens back when *it* needs you to pick
- **Teach It a Site Once**: Point it at a site and it explores and writes reusable notes, so every later session already knows its way around
@@ -63,7 +63,7 @@ The extension dials out to the daemon, because a Manifest V3 service worker cann
- 📚 [Documentation](docs/)
- 🚀 [Install and Pair](docs/guide/install.md)
- ✨ [Features](docs/guide/features/)
-- 🧰 [All 38 Page Tools](docs/reference/tools.md)
+- 🧰 [All 41 Page Tools](docs/reference/tools.md)
- 🔌 [Use It From Claude Code, Cursor or Zed](docs/guide/mcp-clients.md)
- 🛡️ [Approvals and Guardrails](docs/guide/approvals.md)
- 🏗️ [Architecture](docs/internals/)
diff --git a/docs/README.md b/docs/README.md
index 1a6cde2..a89cf39 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -50,7 +50,7 @@ How the pieces actually work, for contributors and for anyone integrating.
| | |
| --- | --- |
-| [Tools](reference/tools.md) | All 38 MCP tools with their parameters, plus the resources |
+| [Tools](reference/tools.md) | All 41 MCP tools with their parameters, plus the resources |
| [CLI](reference/cli.md) | Every `browsentic-mcp` command |
| [Errors](reference/errors.md) | Every error code, what caused it, what to do |
diff --git a/docs/guide/features/README.md b/docs/guide/features/README.md
index 7f0290b..3e674c7 100644
--- a/docs/guide/features/README.md
+++ b/docs/guide/features/README.md
@@ -18,7 +18,7 @@ first.
| | |
| --- | --- |
-| [Page actions](page-actions.md) | The 38 things it can do to a page, grouped by what you would want |
+| [Page actions](page-actions.md) | The 41 things it can do to a page, grouped by what you would want |
| [Screenshots](screenshots.md) | Viewport, full page, or one element — and when a capture touches disk |
| [Theming](theming.md) | Dark mode on a site that has none, and a real WCAG contrast audit |
| [Captchas](captcha.md) | What it will and will not do at a "verify you are human" block |
@@ -29,6 +29,7 @@ first.
| | |
| --- | --- |
| [Monitoring](monitoring.md) | Watching an upload, a build or a deploy in the background |
+| [Scheduling](scheduling.md) | Doing something in ten minutes, or every two, without an agent sitting there |
| [Site maps](site-maps.md) | Teaching it a site once, so later sessions already know their way around |
| [Recordings](recordings.md) | Doing a repetitive job once yourself, then "do it like last time" |
diff --git a/docs/guide/features/monitoring.md b/docs/guide/features/monitoring.md
index 50842f2..5f21d36 100644
--- a/docs/guide/features/monitoring.md
+++ b/docs/guide/features/monitoring.md
@@ -75,5 +75,6 @@ again.
## See also
- [reference/tools.md § Monitoring](../../reference/tools.md#monitoring) — every parameter
+- [Scheduling](scheduling.md) — when the page shows nothing to watch and the job must be re-done
- [Skills](skills.md) — the `monitor-progress` skill routes these requests
- [internals/subsystems.md](../../internals/subsystems.md) — how sampling actually works
diff --git a/docs/guide/features/page-actions.md b/docs/guide/features/page-actions.md
index ffc366f..bd76d31 100644
--- a/docs/guide/features/page-actions.md
+++ b/docs/guide/features/page-actions.md
@@ -1,6 +1,6 @@
# Page actions
-The 38 things Browsentic can do to a page. You never have to name these — you say what you want and
+The 41 things Browsentic can do to a page. You never have to name these — you say what you want and
the agent picks — but knowing what exists tells you what is worth asking for.
Exact parameters for every one: [reference/tools.md](../../reference/tools.md).
@@ -68,6 +68,7 @@ pinned tab, a browser page, and a tab being [recorded](recordings.md).
| Theming and accessibility | `page_readTheme`, `page_auditContrast`, `page_applyTheme` | [Theming](theming.md) |
| Captchas | `page_findCaptcha`, `page_solveCaptcha` | [Captchas](captcha.md) |
| Background watching | `page_startMonitor`, `page_monitorStatus`, `page_awaitMonitor`, `page_stopMonitor` | [Monitoring](monitoring.md) |
+| Scheduled jobs | `page_startTimer`, `page_timerStatus`, `page_stopTimer` | [Scheduling](scheduling.md) |
| Files | `page_listFiles`, `page_attachFile` | [Files](files.md) |
| Recordings | `page_listRecordings`, `page_readRecording` | [Recordings](recordings.md) |
diff --git a/docs/guide/features/scheduling.md b/docs/guide/features/scheduling.md
new file mode 100644
index 0000000..684500d
--- /dev/null
+++ b/docs/guide/features/scheduling.md
@@ -0,0 +1,103 @@
+# Scheduled jobs
+
+Some work is not waiting for a signal — it is waiting for a clock. A queue that only changes when
+you reload it. A deploy board with no progress bar. A reminder.
+
+```
+check the deploy queue every five minutes and tell me when something lands
+```
+
+```
+in ten minutes, reload this and tell me whether the build passed
+```
+
+---
+
+## What happens
+
+Browsentic schedules the job in the extension and the agent's turn ends. Nothing runs in between —
+no polling, no open connection, no tokens.
+
+When the timer is due, the extension **starts a fresh turn in the conversation that set it**,
+carrying the words the agent wrote for itself. The agent picks up with everything it already knew,
+does the work, and stops again until the next fire.
+
+The schedule lives in the extension, so it survives the agent finishing, the MCP client
+disconnecting, and the service worker being shut down between fires.
+
+---
+
+## Timer or monitor?
+
+They look similar and solve different problems.
+
+| | [Monitoring](monitoring.md) | Scheduling |
+| --- | --- | --- |
+| Fires on | a condition the page shows — a bar reaching 100%, a phrase appearing | a clock |
+| Best for | uploads, builds, deploys with visible progress | queues, dashboards, inboxes, reminders |
+| Between fires | watches the page continuously | nothing runs |
+| Wakes the agent | once, at the end | every time it fires |
+
+If the page can tell you when it is done, a monitor is exact and cheaper. A timer is for work that
+has to be **re-done** to find out.
+
+---
+
+## Once, or over and over
+
+| You say | What is set |
+| --- | --- |
+| "in ten minutes" | one fire, ten minutes out |
+| "every two minutes" | a repeating fire, two minutes apart |
+
+Thirty seconds is the shortest interval a browser can keep, and a day is the longest. Every
+repeating timer carries a `maxRuns` cap — twelve by default — so a forgotten one cannot run all
+night. Five timers at most, across everything.
+
+A repeating job usually cancels itself: the agent writes "if the build has finished, tell me and
+stop the timer" into its own prompt, and the fired turn calls `page_stopTimer` once there is an
+answer.
+
+---
+
+## Reminders that need no agent
+
+If you only want to be told something at a time, there is nothing for an agent to do:
+
+```
+remind me to check the oven in twenty minutes
+```
+
+That schedules a browser notification carrying the text, and wakes no agent at all. It works with
+the side panel closed.
+
+---
+
+## When a fire lands on a busy conversation
+
+A timer that comes due while its conversation is still working on the previous turn **skips that
+beat** rather than queueing behind it. A five-minute job on a two-minute timer simply runs less
+often than asked, instead of piling up a backlog.
+
+Skips do not count against `maxRuns`, and they are reported by `page_timerStatus` alongside the
+fires that did happen. After twenty skipped fires the timer gives up and says why — at that point
+the interval was simply wrong for the job.
+
+Timers belong to the conversation that set them. Ending it, or closing its tab, cancels them —
+they never outlive it, and one conversation's timers never reach another's.
+
+---
+
+## From an MCP client
+
+`page_startTimer` needs a side-panel conversation to wake, and an outside MCP client is not one: a
+timer there fails with `NO_CONVERSATION`. Use `deliver: "notify"` for a reminder, or your client's
+own scheduler for work — Claude Code, for instance, has `/loop` and scheduled agents.
+
+---
+
+## See also
+
+- [reference/tools.md § Scheduling](../../reference/tools.md#scheduling) — every parameter
+- [Monitoring](monitoring.md) — the condition-driven half of the same problem
+- [Skills](skills.md) — the `scheduled-jobs` skill routes these requests
diff --git a/docs/guide/mcp-clients.md b/docs/guide/mcp-clients.md
index 11d9900..efe08aa 100644
--- a/docs/guide/mcp-clients.md
+++ b/docs/guide/mcp-clients.md
@@ -44,7 +44,7 @@ Tools missing from a session you registered mid-flight is the single most common
## What the client gets
-- **38 page tools** — every one listed with its parameters in [reference/tools.md](../reference/tools.md)
+- **41 page tools** — every one listed with its parameters in [reference/tools.md](../reference/tools.md)
- **`browsentic_status`** — whether the extension is connected, its version, the active tab, any
running monitors, and a `hint` naming the fix when something is wrong. Call it first when a page
tool fails.
diff --git a/docs/internals/registry.md b/docs/internals/registry.md
index 17253bd..373b620 100644
--- a/docs/internals/registry.md
+++ b/docs/internals/registry.md
@@ -8,7 +8,7 @@ One definition, compiled into two bundles.
## One array, two consumers
-There are **38 page capabilities**. They are defined once, in
+There are **41 page capabilities**. They are defined once, in
[`lib/actions/registry.ts`](../../lib/actions/registry.ts), and that array is compiled into **both**
the extension and the daemon.
diff --git a/docs/reference/README.md b/docs/reference/README.md
index 6e91a01..9372ca5 100644
--- a/docs/reference/README.md
+++ b/docs/reference/README.md
@@ -5,7 +5,7 @@ Lookup tables. Nothing here explains a workflow — see the [user guide](../guid
| | |
| --- | --- |
-| [Tools](tools.md) | All 38 MCP tools with their parameters, the three read-only resources, and the reserved actions that never become tools |
+| [Tools](tools.md) | All 41 MCP tools with their parameters, the three read-only resources, and the reserved actions that never become tools |
| [CLI](cli.md) | Every `browsentic-mcp` command |
| [Errors](errors.md) | Every error code, where it comes from, and what to do about it |
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
index 3a75ffe..a8bf206 100644
--- a/docs/reference/tools.md
+++ b/docs/reference/tools.md
@@ -26,6 +26,7 @@ The surface, at a glance:
| [Moving](#moving) | `page_searchSite`, `page_navigate`, `page_scrollTo`, `page_openTab`, `page_switchTab`, `page_closeTab` |
| [Theming](#theming) | `page_readTheme`, `page_auditContrast`, `page_applyTheme` |
| [Monitoring](#monitoring) | `page_startMonitor`, `page_monitorStatus`, `page_awaitMonitor`, `page_stopMonitor` |
+| [Scheduling](#scheduling) | `page_startTimer`, `page_timerStatus`, `page_stopTimer` |
| [Files](#files) | `page_listFiles`, `page_attachFile` |
| [Recordings](#recordings) | `page_listRecordings`, `page_readRecording` |
| [Mapping runs only](#mapping-runs-only) | `browsentic_saveSiteMap` |
@@ -657,6 +658,51 @@ No notification is shown — the stop was asked for.
---
+## Scheduling
+
+Work on a clock rather than on a condition: `page_startTimer` schedules it, `page_timerStatus`
+reports on it, `page_stopTimer` cancels it. The schedule is kept by the extension, so it needs no
+further tool calls — when a timer fires it starts a fresh turn in the conversation that set it,
+carrying the `prompt` as the instruction. Use a [monitor](#monitoring) instead whenever the page
+itself can signal completion; a timer is for work that has to be re-done, such as reloading a queue.
+
+### page_startTimer
+
+Schedule work for later — "in ten minutes check whether the build finished", "every two minutes
+refresh the queue". Returns a `timerId` immediately.
+
+| Parameter | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `prompt` | string | required | What to do when the timer fires, written as an instruction to the agent starting a fresh turn. With `deliver: "notify"` it is the notification text instead |
+| `afterMs` | integer | required | How long to wait before firing, and for a repeating timer the gap between fires. Floor 30000, ceiling 86400000 |
+| `repeat` | boolean | `false` | Keep firing every `afterMs` instead of once |
+| `maxRuns` | integer | `12` | Stop a repeating timer after this many fires. Ignored when `repeat` is false |
+| `label` | string | — | Short name shown in the side panel and in notifications, e.g. `"deploy check"` |
+| `deliver` | `"agent"` \| `"notify"` | `"agent"` | `agent` wakes the conversation with the prompt; `notify` only shows the user a browser notification and never wakes the agent |
+
+Five timers at most, across everything. `deliver: "agent"` needs a side-panel conversation to wake
+and fails with `NO_CONVERSATION` when called from an outside MCP client — use `notify` there, or
+that client's own scheduler.
+
+### page_timerStatus
+
+Report on scheduled jobs: fires so far, fires skipped because the conversation was still busy, when
+the next one is due, and the latest log lines.
+
+| Parameter | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `timerId` | string | — | One timer to report. Omit to list every scheduled and recently finished timer |
+
+### page_stopTimer
+
+Cancel a scheduled job before it has run out. Nothing further fires and no notification is shown.
+
+| Parameter | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `timerId` | string | — | Omit when only one timer is scheduled; with several, an omitted id cancels nothing and the candidates are listed |
+
+---
+
## Files
### page_listFiles
diff --git a/entrypoints/background.ts b/entrypoints/background.ts
index 492b48d..0f12d06 100644
--- a/entrypoints/background.ts
+++ b/entrypoints/background.ts
@@ -11,6 +11,7 @@ import { ingestSample, monitorsForTab, serveMonitor } from '@/lib/bridge/monitor
import { appendEvents, recordingStateFor, serveRecorder } from '@/lib/bridge/recorder';
import { serveRunPorts, serveTabSessions } from '@/lib/bridge/run-port';
import { serveRail, setPanelCollapsed, syncRail } from '@/lib/bridge/rail';
+import { serveTimers } from '@/lib/bridge/timer';
import { openSidePanel } from '@/lib/bridge/side-panel';
import { isAgentKind } from '@/lib/agents/catalog';
import {
@@ -176,6 +177,7 @@ export default defineBackground(() => {
serveRecorder();
serveMonitor();
+ serveTimers();
serveRunPorts();
serveTabSessions();
serveRail();
diff --git a/lib/actions/page/start-timer.ts b/lib/actions/page/start-timer.ts
new file mode 100644
index 0000000..1666fdb
--- /dev/null
+++ b/lib/actions/page/start-timer.ts
@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import {
+ DEFAULT_MAX_RUNS,
+ MAX_PROMPT_CHARS,
+ MAX_TIMER_MS,
+ MAX_TIMER_RUNS,
+ MIN_TIMER_MS,
+} from '@/lib/timers/events';
+import { ActionError, defineAction } from '../core';
+
+export const startTimer = defineAction({
+ name: 'page.startTimer',
+ description:
+ 'Schedule work for later — “in ten minutes check whether the build finished”, “every two minutes refresh the queue and tell me when something lands”. ' +
+ 'Returns a timerId immediately; the extension keeps the schedule with no further tool calls and wakes this conversation with your prompt each time it fires, so set it and end your turn. ' +
+ 'Reach for page.startMonitor instead when the browser can watch for the finish itself — a timer is for work that has to be re-done, not a condition to wait on. ' +
+ 'Check on it with page.timerStatus, end it with page.stopTimer.',
+ input: z.object({
+ prompt: z
+ .string()
+ .min(1)
+ .max(MAX_PROMPT_CHARS)
+ .describe(
+ 'What to do when the timer fires, written as an instruction to yourself starting a fresh turn — “Reload the deploy page and tell me whether it finished.” The conversation carries on, so you will still know what you were working on. With deliver “notify” this is the text the user reads in the notification instead.',
+ ),
+ afterMs: z
+ .number()
+ .int()
+ .min(MIN_TIMER_MS)
+ .max(MAX_TIMER_MS)
+ .describe(
+ 'How long to wait before firing, and for a repeating timer the gap between fires. 30 seconds is the shortest interval the browser can keep.',
+ ),
+ repeat: z
+ .boolean()
+ .default(false)
+ .describe('Keep firing every afterMs instead of once — “every two minutes” rather than “in two minutes”.'),
+ maxRuns: z
+ .number()
+ .int()
+ .min(1)
+ .max(MAX_TIMER_RUNS)
+ .default(DEFAULT_MAX_RUNS)
+ .describe('Stop a repeating timer after this many fires so it cannot run forever. Ignored when repeat is false.'),
+ label: z
+ .string()
+ .max(80)
+ .optional()
+ .describe('Short name shown in the side panel and in notifications, e.g. “deploy check”.'),
+ deliver: z
+ .enum(['agent', 'notify'])
+ .default('agent')
+ .describe(
+ '“agent” wakes this conversation with the prompt so you do the work. “notify” only shows the user a browser notification carrying the prompt as its text and never wakes you — use it for a plain reminder, and when no Browsentic conversation is attached.',
+ ),
+ }),
+ execute() {
+ throw new ActionError('page.startTimer is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/page/stop-timer.ts b/lib/actions/page/stop-timer.ts
new file mode 100644
index 0000000..b33bc0a
--- /dev/null
+++ b/lib/actions/page/stop-timer.ts
@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ActionError, defineAction } from '../core';
+
+export const stopTimer = defineAction({
+ name: 'page.stopTimer',
+ description:
+ 'Cancel a scheduled job before it has run out. Nothing further fires and no notification is shown — the stop was asked for.',
+ input: z.object({
+ timerId: z
+ .string()
+ .optional()
+ .describe('Omit when only one timer is scheduled; with several an omitted id stops nothing and the candidates are listed.'),
+ }),
+ execute() {
+ throw new ActionError('page.stopTimer is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/page/timer-status.ts b/lib/actions/page/timer-status.ts
new file mode 100644
index 0000000..0686243
--- /dev/null
+++ b/lib/actions/page/timer-status.ts
@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ActionError, defineAction } from '../core';
+
+export const timerStatus = defineAction({
+ name: 'page.timerStatus',
+ description:
+ 'Report on scheduled jobs started with page.startTimer: how many times each has fired, how many fires were skipped because the conversation was still busy, when the next one is due, and the latest log lines.',
+ input: z.object({
+ timerId: z
+ .string()
+ .optional()
+ .describe('One timer to report. Omit to list every scheduled and recently finished timer.'),
+ }),
+ execute() {
+ throw new ActionError('page.timerStatus is resolved by the Browsentic extension, not in the page', 'UNSUPPORTED');
+ },
+});
diff --git a/lib/actions/registry.ts b/lib/actions/registry.ts
index c80eb1d..2dd93a0 100644
--- a/lib/actions/registry.ts
+++ b/lib/actions/registry.ts
@@ -33,9 +33,12 @@ import { selectOption } from './page/select-option';
import { selectText } from './page/select-text';
import { solveCaptcha } from './page/solve-captcha';
import { startMonitor } from './page/start-monitor';
+import { startTimer } from './page/start-timer';
import { stopMonitor } from './page/stop-monitor';
+import { stopTimer } from './page/stop-timer';
import { submitForm } from './page/submit-form';
import { switchTab } from './page/switch-tab';
+import { timerStatus } from './page/timer-status';
import { trustedClick } from './page/trusted-click';
import { typeText } from './page/type-text';
import { waitForElement } from './page/wait-for-element';
@@ -70,6 +73,9 @@ export const actions: ReadonlyMap<string, AnyAction> = new Map(
monitorStatus,
awaitMonitor,
stopMonitor,
+ startTimer,
+ timerStatus,
+ stopTimer,
highlightElement,
searchSite,
navigate,
diff --git a/lib/bridge/invoke.ts b/lib/bridge/invoke.ts
index 5139f0d..8765d1e 100644
--- a/lib/bridge/invoke.ts
+++ b/lib/bridge/invoke.ts
@@ -17,8 +17,11 @@ import { screenshot } from '@/lib/actions/page/screenshot';
import { searchSite } from '@/lib/actions/page/search-site';
import { solveCaptcha } from '@/lib/actions/page/solve-captcha';
import { startMonitor } from '@/lib/actions/page/start-monitor';
+import { startTimer } from '@/lib/actions/page/start-timer';
import { stopMonitor } from '@/lib/actions/page/stop-monitor';
+import { stopTimer } from '@/lib/actions/page/stop-timer';
import { switchTab } from '@/lib/actions/page/switch-tab';
+import { timerStatus } from '@/lib/actions/page/timer-status';
import { trustedClick } from '@/lib/actions/page/trusted-click';
import { failure, success, type ActionResult } from '@/lib/actions/protocol';
import { EXPIRED_MESSAGE, REFUSED_MESSAGE } from '@/lib/secrets';
@@ -26,6 +29,7 @@ import { releaseForAction, sealForPage } from '@/lib/bridge/secret-vault';
import { findCaptchaInTab, solveCaptchaInTab } from '@/lib/bridge/captcha';
import { listMeta, readBytes } from '@/lib/bridge/file-store';
import { awaitMonitorDone, monitorStatusFor, startTabMonitor, stopTabMonitor } from '@/lib/bridge/monitor';
+import { startJobTimer, stopJobTimer, timerStatusFor } from '@/lib/bridge/timer';
import { listRecordings as listStoredMeta, readRecordingBody } from '@/lib/bridge/recording-store';
import { screenshotTab } from '@/lib/bridge/screenshot';
import { dragInTab, trustedClickInTab } from '@/lib/bridge/trusted-input';
@@ -85,6 +89,9 @@ async function dispatch(
if (action === monitorStatus.name) return statusOfMonitors(input);
if (action === stopMonitor.name) return stopRequestedMonitor(input);
if (action === awaitMonitor.name) return awaitRequestedMonitor(input);
+ if (action === startTimer.name) return beginTimer(input, owner?.sessionId);
+ if (action === timerStatus.name) return statusOfTimers(input);
+ if (action === stopTimer.name) return stopRequestedTimer(input);
const tab = await resolveTab(tabId, owner);
if (tab?.id == null) {
@@ -186,6 +193,24 @@ async function awaitRequestedMonitor(input: unknown): Promise<ActionResult> {
return awaitMonitorDone(parsed.data.monitorId, parsed.data.timeoutMs);
}
+async function beginTimer(input: unknown, sessionId?: string): Promise<ActionResult> {
+ const parsed = startTimer.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return startJobTimer(parsed.data, sessionId);
+}
+
+async function statusOfTimers(input: unknown): Promise<ActionResult> {
+ const parsed = timerStatus.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return timerStatusFor(parsed.data.timerId);
+}
+
+async function stopRequestedTimer(input: unknown): Promise<ActionResult> {
+ const parsed = stopTimer.input.safeParse(input ?? {});
+ if (!parsed.success) return failure('INVALID_INPUT', z.prettifyError(parsed.error));
+ return stopJobTimer(parsed.data.timerId);
+}
+
async function listStoredFiles(input: unknown): Promise<ActionResult> {
const filter = (input as { nameContains?: unknown } | undefined)?.nameContains;
const needle = typeof filter === 'string' ? filter.toLowerCase() : null;
diff --git a/lib/bridge/run-port.ts b/lib/bridge/run-port.ts
index 760c105..0b74c87 100644
--- a/lib/bridge/run-port.ts
+++ b/lib/bridge/run-port.ts
@@ -34,6 +34,7 @@ import {
type StoredSessionMeta,
} from './session-store';
import { recordGeneratedSkill } from './skill-store';
+import { dropTimersForSession, onTimerFire, type TimerHandoff } from './timer';
import {
activateSiteMap,
cancelRun,
@@ -135,6 +136,17 @@ export function serveRunPorts(): void {
}
});
+ onTimerFire((sessionId, prompt, label) =>
+ serialized<TimerHandoff>(async () => {
+ const session = (await readTabSessions())[sessionId];
+ if (!session) return 'gone';
+ if (session.runId || busy.has(sessionId)) return 'busy';
+ await append(sessionId, notice('info', `Timer “${label}” fired.`));
+ await startTurn(session, prompt, { fastPath: false });
+ return 'delivered';
+ }),
+ );
+
onSiteMapDraft((_runId, draft) => {
pendingDraft = draft;
broadcast({ op: 'mapDraft', draft });
@@ -307,27 +319,36 @@ async function instruct(
});
return;
}
- const session = ensured.session;
- const { sessionId } = session;
- if (session.runId || busy.has(sessionId)) {
- await append(
- sessionId,
- notice('error', 'RUN_IN_PROGRESS: This conversation is still running — stop it before sending another instruction.'),
- );
- return;
- }
+ const outcome = await startTurn(ensured.session, text, { agentSkillId, focus, fastPath: true });
+ if (outcome !== 'busy') return;
+ await append(
+ ensured.session.sessionId,
+ notice('error', 'RUN_IN_PROGRESS: This conversation is still running — stop it before sending another instruction.'),
+ );
+}
+
+type TurnOutcome = 'started' | 'local' | 'busy' | 'offline';
+
+async function startTurn(
+ session: TabSession,
+ text: string,
+ options: { agentSkillId?: string; focus?: FocusedElement; fastPath: boolean },
+): Promise<TurnOutcome> {
+ const { agentSkillId, focus, fastPath } = options;
+ const { sessionId } = session;
+ if (session.runId || busy.has(sessionId)) return 'busy';
await append(sessionId, { kind: 'user', id: crypto.randomUUID(), text, focus: focus && focusLabel(focus) });
await patchSession(sessionId, { turns: session.turns + 1 });
busy.add(sessionId);
try {
- // An attached agent skill, or an element the user pointed at, is meaningless to the fast
- // path — both only mean something to a spawned agent.
- if (!agentSkillId && !focus && (await handledLocally(text, session))) {
+ // An attached agent skill, an element the user pointed at, or a job a timer is handing
+ // back only mean something to a spawned agent, so none of them may take the fast path.
+ if (fastPath && !agentSkillId && !focus && (await handledLocally(text, session))) {
await persist(sessionId);
- return;
+ return 'local';
}
const runId = sendInstruction(text, {
@@ -350,10 +371,11 @@ async function instruct(
),
);
await persist(sessionId);
- return;
+ return 'offline';
}
await patchSession(sessionId, { runId });
await syncRunIndicator();
+ return 'started';
} finally {
busy.delete(sessionId);
}
@@ -404,6 +426,7 @@ async function endRun(sessionId: string, message: string): Promise<void> {
async function endSession(sessionId: string): Promise<void> {
const session = (await readTabSessions())[sessionId];
if (session?.runId) cancelRun(session.runId);
+ await dropTimersForSession(sessionId);
clearTimeout(cancelTimers.get(sessionId));
cancelTimers.delete(sessionId);
await persist(sessionId);
@@ -516,6 +539,7 @@ export function serveTabSessions(): void {
}
clearTimeout(cancelTimers.get(closed.sessionId));
cancelTimers.delete(closed.sessionId);
+ await dropTimersForSession(closed.sessionId);
await persist(closed.sessionId);
buffers.delete(closed.sessionId);
busy.delete(closed.sessionId);
diff --git a/lib/bridge/timer.ts b/lib/bridge/timer.ts
new file mode 100644
index 0000000..0d5a89e
--- /dev/null
+++ b/lib/bridge/timer.ts
@@ -0,0 +1,344 @@
+import { browser } from 'wxt/browser';
+import { failure, success, type ActionResult } from '@/lib/actions/protocol';
+import {
+ BUSY_RETRY_MS,
+ MAX_TIMER_LOGS,
+ MAX_TIMER_SKIPS,
+ MAX_TIMERS,
+ MAX_TIMERS_KEPT,
+ NOTIFICATION_PREFIX,
+ STATUS_LOG_TAIL,
+ TIMER_ALARM_PREFIX,
+ describeSchedule,
+ timerAlarm,
+ type TimerDelivery,
+ type TimerLogEntry,
+ type TimerPhase,
+ type TimerState,
+} from '@/lib/timers/events';
+
+const TIMERS_KEY = 'browsentic/timers';
+const DONE_KEY = 'browsentic/timersDone';
+
+interface ScheduledTimer {
+ id: string;
+ sessionId?: string;
+ label?: string;
+ prompt: string;
+ deliver: TimerDelivery;
+ afterMs: number;
+ repeat: boolean;
+ maxRuns: number;
+ runs: number;
+ skipped: number;
+ createdAt: number;
+ nextFireAt: number;
+ lastFiredAt?: number;
+ logs: TimerLogEntry[];
+}
+
+export type TimerHandoff = 'delivered' | 'busy' | 'gone';
+
+type Deliverer = (sessionId: string, prompt: string, label: string) => Promise<TimerHandoff>;
+
+let handOff: Deliverer | null = null;
+let queue: Promise<unknown> = Promise.resolve();
+
+export function onTimerFire(deliverer: Deliverer): void {
+ handOff = deliverer;
+}
+
+function locked<T>(task: () => Promise<T>): Promise<T> {
+ const run = queue.then(task, task);
+ queue = run.catch(() => undefined);
+ return run;
+}
+
+async function readTimers(): Promise<Record<string, ScheduledTimer>> {
+ const stored = await browser.storage.session.get(TIMERS_KEY);
+ return (stored[TIMERS_KEY] as Record<string, ScheduledTimer> | undefined) ?? {};
+}
+
+function writeTimers(map: Record<string, ScheduledTimer>): Promise<void> {
+ return browser.storage.session.set({ [TIMERS_KEY]: map });
+}
+
+async function readDone(): Promise<TimerState[]> {
+ const stored = await browser.storage.session.get(DONE_KEY);
+ const list = stored[DONE_KEY] as TimerState[] | undefined;
+ return Array.isArray(list) ? list : [];
+}
+
+function writeDone(list: TimerState[]): Promise<void> {
+ return browser.storage.session.set({ [DONE_KEY]: list });
+}
+
+function stateOf(timer: ScheduledTimer, phase: TimerPhase = 'scheduled', message?: string): TimerState {
+ return {
+ timerId: timer.id,
+ label: timer.label,
+ prompt: timer.prompt,
+ deliver: timer.deliver,
+ sessionId: timer.sessionId,
+ afterMs: timer.afterMs,
+ repeat: timer.repeat,
+ maxRuns: timer.maxRuns,
+ runs: timer.runs,
+ skipped: timer.skipped,
+ createdAt: timer.createdAt,
+ nextFireAt: phase === 'scheduled' ? timer.nextFireAt : undefined,
+ lastFiredAt: timer.lastFiredAt,
+ phase,
+ logs: timer.logs,
+ message,
+ };
+}
+
+function trimLogs(state: TimerState): TimerState {
+ return { ...state, logs: state.logs.slice(-STATUS_LOG_TAIL) };
+}
+
+function appendLog(timer: ScheduledTimer, text: string): void {
+ timer.logs.push({ t: Date.now(), text });
+ if (timer.logs.length > MAX_TIMER_LOGS) timer.logs.splice(0, timer.logs.length - MAX_TIMER_LOGS);
+}
+
+const nameOf = (timer: ScheduledTimer): string => timer.label ?? 'timer';
+
+export async function startJobTimer(
+ input: {
+ prompt: string;
+ afterMs: number;
+ repeat: boolean;
+ maxRuns: number;
+ label?: string;
+ deliver: TimerDelivery;
+ },
+ sessionId?: string,
+): Promise<ActionResult> {
+ if (input.deliver === 'agent' && !sessionId) {
+ return failure(
+ 'NO_CONVERSATION',
+ 'Nothing here can be woken with a prompt — a timer only hands work back inside a Browsentic side-panel conversation. Pass deliver: "notify" to remind the user at that time instead, or schedule the job with your own client’s scheduler.',
+ );
+ }
+
+ const outcome = await locked(async () => {
+ const map = await readTimers();
+ if (Object.keys(map).length >= MAX_TIMERS) {
+ return failure(
+ 'TIMER_LIMIT',
+ `${MAX_TIMERS} timers are already scheduled — cancel one with page.stopTimer first. page.timerStatus lists them.`,
+ );
+ }
+ const now = Date.now();
+ const timer: ScheduledTimer = {
+ id: crypto.randomUUID(),
+ sessionId,
+ label: input.label,
+ prompt: input.prompt,
+ deliver: input.deliver,
+ afterMs: input.afterMs,
+ repeat: input.repeat,
+ maxRuns: input.repeat ? input.maxRuns : 1,
+ runs: 0,
+ skipped: 0,
+ createdAt: now,
+ nextFireAt: now + input.afterMs,
+ logs: [],
+ };
+ appendLog(timer, `Scheduled to fire ${describeSchedule(timer)}.`);
+ map[timer.id] = timer;
+ await writeTimers(map);
+ return success(timer);
+ });
+ if (!outcome.ok) return outcome;
+
+ const timer = outcome.data as ScheduledTimer;
+ await arm(timer);
+ return success(trimLogs(stateOf(timer)));
+}
+
+function arm(timer: ScheduledTimer): Promise<void> {
+ return browser.alarms.create(timerAlarm(timer.id), {
+ when: timer.nextFireAt,
+ ...(timer.repeat ? { periodInMinutes: timer.afterMs / 60_000 } : {}),
+ });
+}
+
+async function fireTimer(timerId: string): Promise<void> {
+ const due = (await readTimers())[timerId];
+ if (!due) {
+ await browser.alarms.clear(timerAlarm(timerId));
+ return;
+ }
+
+ const outcome = await deliverOnce(due);
+ if (outcome === 'gone') {
+ await finishTimer(timerId, 'orphaned', 'The conversation this timer belonged to is gone.');
+ return;
+ }
+
+ const advanced = await locked(async () => {
+ const map = await readTimers();
+ const timer = map[timerId];
+ if (!timer) return null;
+ const now = Date.now();
+ if (outcome === 'busy') {
+ timer.skipped += 1;
+ appendLog(timer, 'Skipped — the conversation was still working on the previous turn.');
+ } else {
+ timer.runs += 1;
+ timer.lastFiredAt = now;
+ appendLog(timer, `Fired — run ${timer.runs}${timer.repeat ? ` of ${timer.maxRuns}` : ''}.`);
+ }
+ timer.nextFireAt = now + (timer.repeat || outcome === 'delivered' ? timer.afterMs : BUSY_RETRY_MS);
+ await writeTimers(map);
+ return { ...timer };
+ });
+ if (!advanced) return;
+
+ if (advanced.skipped >= MAX_TIMER_SKIPS) {
+ await finishTimer(
+ timerId,
+ 'finished',
+ `Gave up after ${advanced.skipped} fires found the conversation still busy — the job takes longer than the interval it was given.`,
+ );
+ return;
+ }
+
+ if (!advanced.repeat) {
+ if (outcome === 'delivered') await finishTimer(timerId, 'finished');
+ else await arm(advanced);
+ return;
+ }
+ if (advanced.runs >= advanced.maxRuns) {
+ await finishTimer(timerId, 'finished', `Fired ${advanced.runs} times, which is the limit that was set.`);
+ }
+}
+
+async function deliverOnce(timer: ScheduledTimer): Promise<TimerHandoff> {
+ if (timer.deliver === 'notify') {
+ await notify(timer.id, timer.label ?? 'Browsentic timer', timer.prompt);
+ return 'delivered';
+ }
+ if (!timer.sessionId || !handOff) return 'gone';
+ return handOff(timer.sessionId, timer.prompt, nameOf(timer));
+}
+
+export async function finishTimer(
+ timerId: string,
+ phase: Exclude<TimerPhase, 'scheduled'>,
+ message?: string,
+): Promise<TimerState | null> {
+ const closed = await locked(async () => {
+ const map = await readTimers();
+ const timer = map[timerId];
+ if (!timer) return null;
+ delete map[timerId];
+ await writeTimers(map);
+ appendLog(timer, message ?? closingLine(phase));
+ const state = stateOf(timer, phase, message);
+ await writeDone([...(await readDone()), state].slice(-MAX_TIMERS_KEPT));
+ return state;
+ });
+ if (!closed) return null;
+
+ await browser.alarms.clear(timerAlarm(timerId));
+ if (phase === 'orphaned') {
+ await notify(
+ timerId,
+ `Timer ended: ${closed.label ?? 'scheduled job'}`,
+ 'The conversation it was set in has closed, so it was cancelled.',
+ );
+ }
+ return closed;
+}
+
+function closingLine(phase: Exclude<TimerPhase, 'scheduled'>): string {
+ const lines: Record<Exclude<TimerPhase, 'scheduled'>, string> = {
+ finished: 'The schedule ran out.',
+ stopped: 'Cancelled.',
+ orphaned: 'The conversation this timer belonged to is gone.',
+ };
+ return lines[phase];
+}
+
+export async function stopJobTimer(timerId?: string): Promise<ActionResult> {
+ const scheduled = Object.values(await readTimers());
+
+ if (timerId != null) {
+ const state = await finishTimer(timerId, 'stopped');
+ if (state) return success(trimLogs(state));
+ const done = (await readDone()).find((finished) => finished.timerId === timerId);
+ return done
+ ? failure('TIMER_NOT_FOUND', `Timer ${timerId} already ended (${done.phase}) — there is nothing to cancel.`)
+ : failure('TIMER_NOT_FOUND', `No timer with id “${timerId}”. page.timerStatus lists what is scheduled.`);
+ }
+
+ if (scheduled.length === 0) return failure('TIMER_NOT_FOUND', 'No timer is scheduled.');
+ if (scheduled.length > 1) {
+ const lines = scheduled.map((timer) => `${timer.id} · ${nameOf(timer)} (${describeSchedule(timer)})`).join('; ');
+ return failure(
+ 'INVALID_TARGET',
+ `${scheduled.length} timers are scheduled, so nothing was cancelled — cancel one by id: ${lines}`,
+ );
+ }
+ const state = await finishTimer(scheduled[0].id, 'stopped');
+ return state ? success(trimLogs(state)) : failure('TIMER_NOT_FOUND', 'That timer just ended on its own.');
+}
+
+export async function timerStatusFor(timerId?: string): Promise<ActionResult> {
+ const map = await readTimers();
+ const done = await readDone();
+
+ if (timerId != null) {
+ const scheduled = map[timerId];
+ if (scheduled) return success(trimLogs(stateOf(scheduled)));
+ const finished = done.find((state) => state.timerId === timerId);
+ return finished
+ ? success(trimLogs(finished))
+ : failure('TIMER_NOT_FOUND', `No timer with id “${timerId}” is scheduled or recently finished.`);
+ }
+
+ return success({
+ timers: [...Object.values(map).map((timer) => trimLogs(stateOf(timer))), ...done.map(trimLogs)],
+ });
+}
+
+export async function dropTimersForSession(sessionId: string): Promise<void> {
+ for (const timer of Object.values(await readTimers())) {
+ if (timer.sessionId === sessionId) await finishTimer(timer.id, 'orphaned', 'The conversation was ended.');
+ }
+}
+
+export function serveTimers(): void {
+ browser.alarms.onAlarm.addListener((alarm) => {
+ if (!alarm.name.startsWith(TIMER_ALARM_PREFIX)) return;
+ void fireTimer(alarm.name.slice(TIMER_ALARM_PREFIX.length));
+ });
+
+ browser.notifications?.onClicked.addListener((notificationId) => {
+ if (!notificationId.startsWith(NOTIFICATION_PREFIX)) return;
+ void browser.notifications.clear(notificationId).catch(() => undefined);
+ });
+}
+
+async function notify(timerId: string, title: string, message: string): Promise<void> {
+ await browser.notifications
+ ?.create(`${NOTIFICATION_PREFIX}${timerId}`, {
+ type: 'basic',
+ iconUrl: largestIcon(),
+ title,
+ message,
+ })
+ .catch(() => undefined);
+}
+
+function largestIcon(): string {
+ const icons = browser.runtime.getManifest().icons ?? {};
+ const sizes = Object.keys(icons)
+ .map(Number)
+ .sort((a, b) => b - a);
+ return icons[sizes[0]] ?? '';
+}
diff --git a/lib/timers/events.ts b/lib/timers/events.ts
new file mode 100644
index 0000000..60adff3
--- /dev/null
+++ b/lib/timers/events.ts
@@ -0,0 +1,62 @@
+export const MAX_TIMERS = 5;
+export const MIN_TIMER_MS = 30_000;
+export const MAX_TIMER_MS = 24 * 60 * 60_000;
+export const DEFAULT_MAX_RUNS = 12;
+export const MAX_TIMER_RUNS = 500;
+export const MAX_PROMPT_CHARS = 2_000;
+export const BUSY_RETRY_MS = 60_000;
+export const MAX_TIMER_SKIPS = 20;
+export const MAX_TIMER_LOGS = 20;
+export const MAX_TIMERS_KEPT = 6;
+export const STATUS_LOG_TAIL = 5;
+
+export const TIMER_ALARM_PREFIX = 'browsentic/timer:';
+
+export const timerAlarm = (timerId: string): string => `${TIMER_ALARM_PREFIX}${timerId}`;
+
+export const NOTIFICATION_PREFIX = 'browsentic-timer:';
+
+export type TimerDelivery = 'agent' | 'notify';
+
+export type TimerPhase = 'scheduled' | 'finished' | 'stopped' | 'orphaned';
+
+export interface TimerLogEntry {
+ t: number;
+ text: string;
+}
+
+export interface TimerSchedule {
+ afterMs: number;
+ repeat: boolean;
+ maxRuns: number;
+}
+
+export interface TimerState extends TimerSchedule {
+ timerId: string;
+ label?: string;
+ prompt: string;
+ deliver: TimerDelivery;
+ sessionId?: string;
+ runs: number;
+ skipped: number;
+ createdAt: number;
+ nextFireAt?: number;
+ lastFiredAt?: number;
+ phase: TimerPhase;
+ logs: TimerLogEntry[];
+ message?: string;
+}
+
+export function humanMs(ms: number): string {
+ const seconds = Math.round(ms / 1000);
+ if (seconds < 90) return `${seconds}s`;
+ const minutes = Math.round(seconds / 60);
+ if (minutes < 90) return `${minutes} min`;
+ return `${Number((ms / 3_600_000).toFixed(1))}h`;
+}
+
+export function describeSchedule(schedule: TimerSchedule): string {
+ return schedule.repeat
+ ? `every ${humanMs(schedule.afterMs)}, up to ${schedule.maxRuns} times`
+ : `once in ${humanMs(schedule.afterMs)}`;
+}
diff --git a/mcp/skills/monitor-progress.md b/mcp/skills/monitor-progress.md
index 60eb21c..49203e6 100644
--- a/mcp/skills/monitor-progress.md
+++ b/mcp/skills/monitor-progress.md
@@ -12,6 +12,8 @@ Call `page_findProgress` first, always. It returns every measurable signal on th
If `candidates` is empty and there is no `titlePercent`, **do not start a monitor**. Say what the page actually shows, and ask what completion looks like — a phrase that will appear ("Upload complete", "Build passed"), an element that will disappear, a page it will land on. A phrase makes a `text-matches` watch possible even on a page with no visible progress.
+If there is nothing to watch because the page only changes when it is reloaded — a queue, a dashboard, an inbox — a monitor is the wrong tool. Schedule the re-check with `page_startTimer` instead and read `scheduled-jobs`.
+
## 2. Pick the strongest signal
- A `progressbar` or `progress-element` candidate → `until: { kind: "progress-reaches", target: { selector: … } }`. It completes at 100% unless the user wants a different `threshold`.
diff --git a/mcp/skills/scheduled-jobs.md b/mcp/skills/scheduled-jobs.md
new file mode 100644
index 0000000..3af7dc2
--- /dev/null
+++ b/mcp/skills/scheduled-jobs.md
@@ -0,0 +1,58 @@
+---
+name: scheduled-jobs
+description: Do something on a clock — once after a delay, or over and over on an interval — by scheduling the work and letting the browser wake you when it is due.
+triggers: [remind me, reminder, schedule, minutes, hours, every minute, every hour, every few, check every, keep checking, check back, check again, poll, recurring, on a timer, set a timer, come back to, do this later, wake me]
+---
+
+The extension keeps the clock, not you. You set a timer, end your turn, and the browser starts a fresh turn with your own words in it when the time comes. Nothing is running in between — no polling, no waiting, no tokens.
+
+## 1. A timer or a monitor?
+
+They solve different problems and picking wrong wastes the user's time.
+
+- **The page will show you when it is done** — a progress bar, a completion phrase, a spinner that vanishes → `page_startMonitor`. It watches continuously and fires the moment the condition is true. Read `monitor-progress` for that.
+- **There is nothing to watch, only work to re-do** — reload and compare, re-run a search, look at a dashboard that updates on its own, remind the user → `page_startTimer`.
+
+"Tell me when this upload finishes" is a monitor. "Check the deploy queue every five minutes" is a timer. If a real signal exists, a monitor beats a timer every time: it is exact, and it does not re-do work that has not changed.
+
+## 2. Translate what they said
+
+| They said | `afterMs` | `repeat` |
+| --- | --- | --- |
+| "in ten minutes" | `600000` | `false` |
+| "every two minutes" | `120000` | `true` |
+| "every half hour until it lands" | `1800000` | `true` |
+
+Thirty seconds is the floor the browser can keep, and a day is the ceiling. A repeating timer always stops at `maxRuns` — set it to cover how long the user actually expects to wait (twelve by default), so a forgotten timer cannot run all night.
+
+## 3. Write the prompt for your future self
+
+The `prompt` is what you will be handed when it fires, as a new instruction in this same conversation. Write it as a job, with the finish line in it:
+
+> "Reload the deploy page and check whether build #4412 has finished. If it has, tell me the result and call page_stopTimer. If it hasn't, say nothing and end the turn."
+
+Two things make that work:
+
+- **Say when to stop.** A repeating timer that has done its job should cancel itself — that is the whole point of handing you `page_stopTimer` from inside the fired turn. Without it the user gets the same answer twelve times.
+- **Say when to stay quiet.** Most fires of a "watch for X" timer find nothing. Tell yourself to end the turn without a report unless something changed, or you will fill the panel with "still building".
+
+You keep the conversation, so you do not need to restate context — refer to what you already know.
+
+## 4. Set it and stop
+
+`page_startTimer` with a short `label` the user will recognise, then tell them what you scheduled and end the turn. Do not stay to see the first fire.
+
+Five timers at most, across everything.
+
+## 5. Reminders that need no agent
+
+If the user only wants to be told something at a time — "remind me to check the oven in twenty minutes" — pass `deliver: "notify"`. The `prompt` becomes the notification text, and nothing wakes you. Cheaper, and it works even if the panel is closed.
+
+`deliver: "agent"` is the default and needs a Browsentic conversation to wake. Called from an outside MCP client there is none, and it refuses with `NO_CONVERSATION` — use `notify`, or that client's own scheduler.
+
+## 6. Later asks
+
+- "Is that still running?" → `page_timerStatus`: fires so far, fires skipped, when the next one is due, recent log lines.
+- "Stop that" → `page_stopTimer`. With several scheduled, an omitted id cancels nothing and lists them — ask which, then cancel by id.
+- A timer that fires while the conversation is still working on the previous turn **skips that beat** rather than queueing behind it. Skips do not count against `maxRuns`, and `page_timerStatus` reports them. A slow job on a fast interval simply runs less often than asked — until twenty fires have been skipped, at which point the timer gives up and says so, because the interval was wrong for the job.
+- Ending the conversation cancels its timers. They do not outlive it.
diff --git a/mcp/src/agent/mapping.ts b/mcp/src/agent/mapping.ts
index ec22ce6..7f9d91c 100644
--- a/mcp/src/agent/mapping.ts
+++ b/mcp/src/agent/mapping.ts
@@ -31,6 +31,7 @@ const READ_ONLY_ACTIONS = new Set([
'page.findSearch',
'page.findCaptcha',
'page.monitorStatus',
+ 'page.timerStatus',
'page.readTheme',
'page.auditContrast',
]);