Core

Check the checkbox/radio identified by ref or selector (no-op if already checked). Options: force, timeoutMs. Returns: { ok, session_id, target, checked: true }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.

Clear the value of the input/textarea identified by ref or selector (sets it to empty). Options: force, timeoutMs. Returns: { ok, session_id, target, cleared }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.

Click the element identified by ref (from a snapshot) or selector. Options: button (left|right|middle, default left), clickCount (2 = double-click), force (bypass actionability), timeoutMs. Returns: { ok, session_id, target }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (no such element — re-snapshot; not retryable, carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED (not retryable), POINTER_NOT_DELIVERED (the click landed on another element or frame; retryable), NOT_RUNNING, BAD_ARGUMENT (ref+selector both/neither).

Read the captured renderer console output for the session, newest-relevant entries last. Filters (all optional, ANDed): type (one or more of log/info/warning/error/debug/...), match (a regular expression the text must match), since (epoch ms — only entries at/after it), limit (max entries, default 200, max 1000 — the most recent are kept). Returns: { ok, session_id, entries: [{ type, text, timestamp, windowId?, location? }], count, overflowed }. overflowed is the number of older entries the buffer dropped. Errors: NOT_RUNNING, BAD_ARGUMENT (invalid regex, or multiple sessions).

Disconnect from an attached or injected app without stopping it. A launch-owned session cannot detach because its transport owns the process; this includes Playwright development launches and packaged CDP launches. Use electron_stop for that case. Returns: { ok, session_id, detached: true }. Errors: TRANSPORT_UNSUPPORTED (launch-owned session; not retryable), NOT_RUNNING (no such session), BAD_ARGUMENT (multiple sessions).

Arm the auto-responder for native JS dialogs (alert/confirm/prompt/beforeunload) and read which dialogs fired. Dialogs block the renderer, so the policy is applied automatically the instant one appears. Arming args (all optional): action (accept|dismiss — the default for every dialog), perType (per-kind overrides, e.g. {"confirm":"accept","beforeunload":"dismiss"}, falls back to action), promptText (text submitted to prompt() when it is accepted), oneShot (apply to exactly the next dialog, then revert to dismiss). With NO arming args the call is inspect-only and leaves the policy unchanged. Re…

Scan the conventional CDP debug ports (9222-9225 by default) for already-running, debuggable Electron apps on loopback only. No session required. Returns: { ok, targets, count, scanned } where each target is { targetId, port, appName, pid } and scanned reports { host, ports, elapsed_ms } so an empty result is unambiguous. Errors: BAD_ARGUMENT (non-loopback host, invalid port list, or timeout outside bounds). A failed probe is simply "no target on that port".

Run non-mutating preflight checks without starting an Electron session: Node version, Playwright, Electron, Linux display, configured app root and screenshot directory, eval policy, and project Electron runtime alignment. Returns: { ok, doctor_ok, checks, runtime }, where runtime includes server and, with --app-root, target Electron/Node/V8/ABI facts plus a bounded native-addon inventory. Inspect failed checks and warnings before electron_launch. Errors: none.

Drag the source element (ref or selector) onto the target element (targetRef or targetSelector), using the real mouse API. Options: force, timeoutMs. Returns: { ok, session_id, source, target }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), POINTER_NOT_DELIVERED (retryable), NOT_RUNNING, BAD_ARGUMENT (a side missing or both ref+selector given).

Description is built at runtime.

Description is built at runtime.

Return whether the element identified by ref or selector is present in the DOM. A no-match is a normal result (exists: false), NOT an error — so an agent can poll for appearance/disappearance. Returns: { ok, session_id, exists }. Errors: TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector or ref+selector both/neither).

Assert how many elements match, polling until the count satisfies the predicate or timeoutMs elapses. Target EITHER by selector (counts querySelectorAll; visible:true counts visible only, visible:false counts hidden only) OR by accessibility role/name filters (role, name_contains, name_exact, visible, enabled, interactive). Provide at least one of equals, min, max. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (count predicate not met within timeoutMs — details carry expected + actual; retryable), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no count predicate, …

Assert the element identified by ref or selector matches the given state flags (any of visible, enabled, disabled, checked, selected, expanded, pressed, focused, readonly, required, invalid, busy), evaluated atomically and polled until they hold or timeoutMs elapses. Returns: { ok, session_id, matched, state }. Errors: EXPECTATION_FAILED (state not reached within timeoutMs — details carry expected + the last observed actual state; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, no state flags, or ref+selector both…

Assert the active window's URL (location.href) satisfies a predicate, polling until it does or timeoutMs elapses. Provide exactly one of: contains (substring) or matches (JavaScript regex). Optional flags (any of i, m, s, u) apply to matches; g and y are rejected as stateful. Returns: { ok, session_id, matched, actual }. Errors: EXPECTATION_FAILED (URL did not match within timeoutMs — details carry expected + actual; retryable), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (no/both predicates, or invalid regex or flags).

Assert the element identified by ref or selector is visible, polling until it is or timeoutMs elapses. Visible means attached, laid out, and not visibility:hidden. Returns: { ok, session_id, matched }. Errors: EXPECTATION_FAILED (not visible within timeoutMs; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, or ref+selector both/neither).

Find elements in the renderer by accessibility role + name + state — no CSS selectors. Filters: role (exact), name_contains, name_exact, visible, enabled, interactive; limit caps the matches returned (count still reports the true total). Returns: { ok, surface_id, matches: [{ ref, role, name, bbox }], count, truncated, renderer_reloaded }. A ref may be null for non-interactive landmarks. On zero matches, hints may explain why: similar_names, without_state_filters, other_roles, roles_present, text_matches (text content, not accessible name, with a selector for electron_get_text / electron_exist…

Return the element that currently has focus as { ref, role, name }, or focused: null when nothing (or only the body) is focused. Useful after a Tab press or to confirm focus moved. Returns: { ok, session_id, focused }. Errors: TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (multiple sessions).

Forcefully kill a session (SIGKILL) and release it — the escape hatch when stop hangs. Pass sessionId to target a specific session. Returns: { ok, session_id, killed: true }. Errors: NOT_RUNNING (no such session; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId).

Return the value of attribute `name` on the element identified by ref or selector (null when the attribute is absent — that is not an error). Returns: { ok, session_id, value }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.

Return the bounding box (CSS pixels) of the element identified by ref or selector. Returns: { ok, session_id, bbox: { x, y, w, h } }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.

Description is built at runtime.

Return the full state envelope of the element identified by ref or selector: { visible, enabled, disabled, checked, selected, expanded, pressed, focused, readonly, required, invalid, busy } plus its role and name. One call answers "is this clickable / checked / focused". Returns: { ok, session_id, ref, role, name, state }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector or ref+selector both/neither).

Return the text of the element identified by ref or selector: its trimmed textContent, or — when that is empty — the accessible label that electron_find matches on (aria-labelledby/aria-label, native labels, alt, title, placeholder), so a find-by-name then get_text chain works on labelled controls. Returns: { ok, session_id, text }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (no such element; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector or ref+selector both/neither).

Return the .value of the input/textarea/select identified by ref or selector (null if the element has no value). Returns: { ok, session_id, value }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.

Hover the element identified by ref or selector (e.g. to reveal a tooltip or menu). Options: force, timeoutMs. Returns: { ok, session_id, target }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), POINTER_NOT_DELIVERED (retryable), NOT_RUNNING, BAD_ARGUMENT.

Report the running Electron app environment: runtime versions (electron/node/chrome/v8), app name/version/paths, packaged flag, code-signature status (verified for packaged macOS apps; "unknown" for unpackaged/dev apps, "unsupported" off macOS), the active transport, and its capability matrix. Pass sessionId to target a specific session when several are running. Versions and app fields are null when the transport cannot evaluate in the main process (CDP sessions). Returns: { ok, session_id, transport, versions, app, signature, capabilities }. Errors: NOT_RUNNING (no session — call electron_lau…

Attach to a running Electron process that was NOT started with a debug flag, by injecting the Node inspector. Provide pid. Returns: { ok, session_id, transport, windows, capabilities }. Errors: INJECT_FAILED (handshake failed or inspector belongs to another process; retryable — try electron_attach when the app already exposes a debug endpoint), TRANSPORT_UNSUPPORTED, BAD_ARGUMENT.

Press a key or chord (e.g. 'Enter', 'Control+A', 'ArrowDown'). Focuses ref/selector first when given; otherwise presses against the active element. For editors, click the visible content area first; reserve force:true for offscreen inputs that truly accept focus. Options: force, timeoutMs, waitForFocusMs, requireEditable. Returns: { ok, session_id, key, focused }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), NO_FOCUSED_EDITABLE, NOT_RUNNING, BAD_ARGUMENT (ref+selector both).

Type text as real per-character keystrokes (fires keydown/keypress/input/keyup per char), unlike electron_type which sets the value directly. Focuses ref/selector first when given; otherwise types into the active element. For a code editor (Monaco / EditContext), the reliable path is electron_type_into_editor (it clicks the editor content area, e.g. '.monaco-editor .view-lines', then types into the focused editor) — do NOT target the hidden textarea, which modern editors ignore. force:true focuses an offscreen/aria-hidden input but a swallowed keystroke returns TYPE_NO_EFFECT. Options: force, …

Launch an Electron app and start a driving session. Provide main (absolute path to the main-process entry) or executablePath. Set runtime:"project" to resolve Electron only from the operator-configured --app-root (requires main when resolving that runtime); explicit executablePath takes precedence. Executable-only launches are treated as packaged apps and use a transport-owned, loopback CDP endpoint; main-based development launches use Playwright. A server started with --demo supplies its packaged demo entry when both are omitted. Returns: { ok, session_id, transport, windows, renderer_ready, …

List the plugins loaded into this server: each plugin's name, version, enabled state, namespaced tools and their availability, error codes, declared eval/transport gates, and explicitly safe effective config. A disabled tool is hidden by the server eval policy; its reason says which target to enable. Use this to discover plugin capabilities beyond the core tool surface. Takes no arguments and needs no running app. Returns: { ok, plugins: [{ name, version, state, tools, errorCodes, requirements?, effectiveConfig? }] }. Errors: none.

Press each key in `keys`, in order (e.g. ['Control+A', 'Delete', 'Enter']). Focuses ref/selector first when given. For editors, click the visible content area first; reserve force:true for offscreen inputs that truly accept focus. Options: force, timeoutMs, waitForFocusMs, requireEditable (checked before the first key). Returns: { ok, session_id, keys, focused }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), NO_FOCUSED_EDITABLE, NOT_RUNNING, BAD_ARGUMENT (empty keys or ref+selector both).

Reload the active window (or windowId, which also selects it) and wait, within readyTimeoutMs (default 5000), for the new page to render, like electron_launch; then optionally for waitForSelector to be visible. Use it instead of location.reload() in eval. ignoreCache does a hard reload. Refs from before the reload are gone. Returns: { ok, session_id, renderer_ready, url }. Errors: WAIT_TIMEOUT (waitForSelector not visible in time; retryable), REF_NOT_FOUND (no such window), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector).

Capture a screenshot to an image file and return its path (the image is written on the server host; the bytes are NOT returned inline). With ref/selector, captures just that element; otherwise the targeted window (windowId > windowTitle > windowIndex, default the active window) with optional fullPage or clip. Options: format (png|jpeg), quality (jpeg), path (absolute file) or dir (absolute directory, generated filename). With neither, writes to the server --screenshot-dir if configured, else the OS temp dir — pass dir or set --screenshot-dir for a stable, retrievable artifact location. Before …

Scroll: with ref/selector, centre that element into view; otherwise dispatch a wheel delta (dx/dy). Options: timeoutMs. Returns: { ok, session_id, target } (into-view) or { ok, session_id, dx, dy } (wheel). Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (no element matched the selector; carries similar_refs), NOT_RUNNING, BAD_ARGUMENT (ref+selector both).

Centre the element identified by ref or selector into the viewport. Options: timeoutMs. Returns: { ok, session_id, target }. Errors: SELECTOR_NO_MATCH / REF_NOT_FOUND (carries similar_refs), NOT_RUNNING, BAD_ARGUMENT (ref+selector both/neither).

Select option(s) by value in the <select> identified by ref or selector. Options: force, timeoutMs. Returns: { ok, session_id, target, selected } (selected = the values actually chosen). Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.

Description is built at runtime.

Resize the active window (or windowId) to width x height, of the whole window or, with area "content", of its web content, without eval. Waits for the size to settle and reports what the window really got: an app minimum/maximum size or the screen can clamp it. A maximized or fullscreen window is restored first. Returns: { ok, session_id, window_id, requested, actual, clamped, clamped_by?, window, content, min_size, max_size, restored_from?, method }; clamped_by is minimum_size, maximum_size or window_system; min_size/max_size are null when unset or unknown. CDP attach resizes from the page: i…

Capture the selected renderer surface accessibility tree: interactive elements (and landmarks) with role, name, state, bbox, and a stable ref. Pass since:"last" for only what changed since the previous snapshot (added/removed/changed + ref_map), interactiveOnly to drop landmarks, maxEntries to cap, root to return one subtree. format:"text" returns a compact one-line-per-entry rendering instead of JSON (5-10x fewer tokens): `[ref] role "name" value=… flags`, ~ marks recently-changed, [-] marks landmarks. Diffs default to a compact encoding (changed fields only; diffFormat:"full" restores comple…

Return compact orientation for this server: version, start time, uptime, the last stable failure not tied to a live session, active-session count, and each live session's transport, renderer readiness, selected surface, last stable error code, and non-default dialog policy. It never returns arguments, paths, window arrays, logs, stack traces, dialog entries, prompt text, or plugin payloads. Use electron_windows_list, electron_surfaces_list, or the relevant plugin tool for detailed state. Returns: { ok, server: { version, started_at, uptime_ms, last_error? }, active_sessions, sessions }. Errors…

Gracefully stop a session and release it. If the app ignores the close within timeoutMs (default 10s) the stop auto-escalates to SIGKILL, so the process is always reaped and never left orphaned; the response reports escalated: true when that happened. Pass sessionId to target a specific session. Returns: { ok, session_id, stopped: true, escalated }. Errors: NOT_RUNNING (no such session; not retryable), BAD_ARGUMENT (multiple sessions live — pass sessionId).

List the session renderer surfaces in parent-first order: BrowserWindow roots, WebContentsViews, webview guests, and iframe children. Each opaque id is stable only while its surface stays live; select it with electron_switch_surface before snapshot/find/renderer interactions. Returns: { ok, session_id, surfaces, active_surface_id, count }. Existing window tools remain compatible for window-only flows. Errors: TRANSPORT_UNSUPPORTED (surface targeting is unavailable on this transport; not retryable), NOT_RUNNING, BAD_ARGUMENT (multiple sessions).

Select a live renderer surface by the opaque id returned by electron_surfaces_list. Following snapshot, find, renderer reads/eval, waits, expectations, and interactions target that surface; a ref from a different surface is rejected rather than reused. Returns: { ok, session_id, active, active_surface_id }. Errors: SURFACE_NOT_FOUND (the id was never observed in this session), SURFACE_CLOSED (it detached or closed), SURFACE_UNSUPPORTED (the live surface cannot be driven), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT.

Select the active window by precedence targetId > windowTitle > index > default. The selection changes Stagewright's renderer target; it does not promise native OS foreground focus. Returns: { ok, session_id, active, active_window_id } on success. Errors: REF_NOT_FOUND (no window matched; not retryable), TRANSPORT_UNSUPPORTED (transport has no renderer window target; not retryable), NOT_RUNNING, BAD_ARGUMENT (multiple sessions).

Set the value of the input/textarea identified by ref or selector (fires an input event). For a code editor (Monaco / EditContext, CodeMirror) use electron_type_into_editor — setting .value on an editor host does not update its model. Options: force, timeoutMs. Returns: { ok, session_id, target }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, TYPE_NO_EFFECT (value did not change — wrong target), NOT_RUNNING, BAD_ARGUMENT.

Type into a code editor (Monaco / EditContext, CodeMirror, contenteditable) the reliable way: click the editor's content area identified by ref or selector (e.g. '.monaco-editor .view-lines'), then type the text into the now-focused editor as real keystrokes. Use this instead of typing into an editor's hidden textarea, which modern EditContext editors ignore (returns TYPE_NO_EFFECT). Pass replace:true to REPLACE the editor contents: after the focusing click it selects all (Meta/Control+A, platform-aware) and types over the selection — no second click that would collapse the selection; with emp…

Uncheck the checkbox identified by ref or selector (no-op if already unchecked). Options: force, timeoutMs. Returns: { ok, session_id, target, checked: false }. Errors: REF_NOT_FOUND / SELECTOR_NO_MATCH (carries similar_refs), ELEMENT_NOT_VISIBLE (retryable), ELEMENT_DISABLED, NOT_RUNNING, BAD_ARGUMENT.

Description is built at runtime.

Wait until a named DOM event (e.g. "transitionend", "load", a custom event) fires on the element identified by ref or selector — or on document when neither is given. Returns: { ok, session_id, fired, event }. Errors: WAIT_TIMEOUT (event did not fire within timeoutMs; retryable), SELECTOR_NO_MATCH (target element not present), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, or ref+selector both).

Wait until the element identified by ref or selector reaches state: attached (in the DOM), visible (laid out + not visibility:hidden), hidden (absent or not visible), or detached (removed). Default state: visible. For an intentionally offscreen / aria-hidden element (e.g. a code editor's hidden textarea like Monaco), wait for state:'attached' — state:'visible' will time out because the element is never laid out. Returns: { ok, session_id, matched, state }. Errors: WAIT_TIMEOUT (condition not met within timeoutMs; retryable — for offscreen editor inputs use state:'attached'), REF_NOT_FOUND (sta…

Wait until the element identified by ref or selector matches the given state flags (any of visible, enabled, disabled, checked, selected, expanded, pressed, focused, readonly, required, invalid, busy), evaluated atomically. Returns: { ok, session_id, matched, state }. Errors: WAIT_TIMEOUT (state not reached within timeoutMs — details.last_state shows the last observed state; retryable), REF_NOT_FOUND (stale ref; carries similar_refs), TRANSPORT_UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (invalid selector, no state flags, or ref+selector both/neither).

List the app windows with their id, index, title, url, and visibility. Pass sessionId to target a specific session. Returns: { ok, session_id, windows, active_window_id, count }. Errors: NOT_RUNNING (no such session; not retryable), BAD_ARGUMENT (multiple sessions — pass sessionId).

A read errors (SELECTOR_NO_MATCH) before the element exists; expect_visible + re-read recover.

Compare a stable selected-BrowserWindow PNG against an existing configured-root baseline. A missing baseline is an error; this tool never writes or updates one. Metadata must match before comparison. A mismatch atomically writes unique actual and diff artifacts. Errors: visual.BASELINE_NOT_FOUND, visual.BASELINE_INVALID, visual.ENV_MISMATCH, visual.MISMATCH, visual.UNSUPPORTED, visual.SURFACE_UNSUPPORTED, visual.INVALID_SELECTOR, visual.UNSTABLE, visual.CAPTURE_FAILED, visual.IMAGE_TOO_LARGE, visual.PATH_INVALID, visual.WRITE_FAILED.

Queue answers for the app’s native open/save file dialogs (dialog.showOpenDialog / showSaveDialog, async or sync), first in first out: { kind: "open", paths } | { kind: "save", path } | { kind: "cancel" }, with absolute paths. Each dialog the app shows takes the next answer instead of opening an OS picker; once the queue is empty every dialog is cancelled, so nothing hangs, and a dialog of the other kind than the next answer is cancelled without using it. Replaces the queue and the recorded events unless append is true. No eval. Returns: { ok, armed, pending, hooked } (hooked is launch when el…

Let the app’s file dialogs open the real OS pickers again, drop any queued answers, and return the dialogs answered since arming. Returns: { ok, armed, pending, count, events } (pending is what was still queued). Errors: native.UNSUPPORTED, NOT_RUNNING.

Return the native file dialogs the app showed since native_file_dialog_arm, oldest first: kind (open/save), sync, the options the app passed (title, defaultPath, buttonLabel, message, filters, properties), the parent window title, the answer given, reason (queue_empty or kind_mismatch) when it was cancelled without a queued cancel, and warning multiple_paths when several paths answered a dialog without multiSelections. Returns: { ok, armed, pending, count, events }. Errors: native.UNSUPPORTED, NOT_RUNNING.

Remove every record from an object store (the store itself stays). Idempotent. Returns: { ok, origin, cleared }. Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND, storage.ACCESS_FAILED, NOT_RUNNING.

Count records in an object store (cheaper than reading them), optionally narrowed by an `index` and/or a key `range`. Returns: { ok, origin, count }. Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND, storage.ACCESS_FAILED, NOT_RUNNING.

Delete one record by primary `key` from an object store. Idempotent. Returns: { ok, origin, deleted }. Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND, storage.ACCESS_FAILED, NOT_RUNNING.

Read from an object store: one record by `key`, a `range` of records, or all records (bounded by `limit`, default 1000, with a `truncated` flag). Use `index` to read via a store index instead of the primary key. Values are returned VERBATIM (configure redactValues to mask them). Provide at most one of `key` / `range`. Returns: { ok, origin, record } or { ok, origin, records, truncated }. Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND, storage.ACCESS_FAILED, NOT_RUNNING.

List the primary keys in an object store (no values — cheap discovery), optionally narrowed by an `index` and/or a key `range`, bounded by `limit` (default 1000, with a `truncated` flag). Returns: { ok, origin, count, keys, truncated }. Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND, storage.ACCESS_FAILED, NOT_RUNNING.

Discover IndexedDB structure: with no `database`, list the app’s databases ({ name, version }); with a `database`, list its object stores ({ name, keyPath, autoIncrement, indexes }). Returns: { ok, origin, databases } or { ok, origin, database, stores }. Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND (named database absent), storage.ACCESS_FAILED, NOT_RUNNING.

Add or overwrite one record in an existing object store (seed app state). Omit `key` for a store with an in-line key path or autoIncrement; provide `key` for an out-of-line-key store. Returns: { ok, origin, key } (the effective key). Errors: storage.EVAL_REQUIRED, storage.UNSUPPORTED, storage.NOT_FOUND, storage.ACCESS_FAILED (incl. a missing required key), NOT_RUNNING.

Inspect the greeting form by reading the FULL snapshot.

Inspect the same form with a snapshot scoped to its container (root).

Install a fake clock over the renderer’s Date / setTimeout / setInterval, optionally starting at `time` (epoch ms or ISO-8601). Required before any other clock tool. Re-installing replaces the fake clock. Returns: { ok, installed, time? }. Errors: clock.UNSUPPORTED (transport cannot control the clock), NOT_RUNNING.

Call a registered ipcMain.handle channel from the main process (driving the request the renderer would normally send) and return its result. timeoutMs bounds a hung handler. If the invokeAllow plugin config is set, the channel must be in it. Returns: { ok, result }. Errors: ipc.EVAL_REQUIRED, ipc.MAIN_EVAL_UNSUPPORTED, ipc.INVOKE_FAILED (no handler / handler threw / timed out), ipc.CHANNEL_NOT_ALLOWED (channel not in invokeAllow), NOT_RUNNING, BAD_ARGUMENT.

Return the app’s application menu (the macOS menu bar / app menu) as a tree — each item’s label, role, type, accelerator, and enabled/visible/checked state, with nested submenus. The no-eval way to ASSERT native-menu state. Returns: { ok, menu } (menu is null when the app has none set). Errors: native.UNSUPPORTED (transport cannot read the native UI), NOT_RUNNING.

Trigger an application-menu item by its `path` (labels or roles from the top of the menu, e.g. ["File","Save"] or ["View","Dark Mode"]) — fires the app’s own menu handler, the deterministic way to run a menu action without simulating a keyboard accelerator. Read the item first with native_menu_item to confirm it is enabled and is not a role/submenu item. Returns: { ok, invoked, label?, role?, reason? }. On success invoked is true and the resolved label/role are echoed; otherwise invoked is false and reason is one of not_found, disabled, role (a built-in role item — press its accelerator instea…

Resolve one menu item by its `path` — an array of labels or roles from the top of the menu, e.g. ["View","Appearance","Dark Mode"] or ["Help","quit"]. The direct way to ask "is Dark Mode checked?" or "is Save enabled?" without walking the whole tree. Returns: { ok, found, item? } (found is false when the path does not resolve or the app has no menu). Errors: native.UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (empty path).

The same 30-turn flow reacting via snapshot since:last deltas.

A 30-turn act-then-observe flow reacting via FULL snapshot re-scans.

Return captured notifications, oldest first — each with title, body/subtitle/silent/urgency when set, at (epoch ms), and beforeArm:true when launch-time instrumentation caught a startup notification before the agent armed capture. The no-eval way to ASSERT the app notified the user. Returns: { ok, count, notifications }. Errors: native.NOT_CAPTURING (call native_notifications_start first), native.UNSUPPORTED, NOT_RUNNING.

Arm capture of the native notifications the app shows (new Notification(...).show()), optionally narrowed to titles containing `titleContains`. Notifications shown BEFORE arming are not captured unless the session was launched with electron_launch { instrumentNative: true }, in which case startup notifications are captured and returned with beforeArm:true. Returns: { ok, capturing }. Errors: native.UNSUPPORTED (transport cannot access the native UI), native.ALREADY_CAPTURING (call native_notifications_stop first), NOT_RUNNING, BAD_ARGUMENT (empty titleContains).

Disarm notification capture (restore the original Notification.show) and return the notifications captured during the session. Returns: { ok, count, notifications }. Errors: native.NOT_CAPTURING (nothing to stop), native.UNSUPPORTED, NOT_RUNNING.

See the same change by asking for only the delta (snapshot since:last).

See what changed after an action by re-scanning the FULL snapshot.

Fast-forward to `time` firing the timers due up to it, then HOLD there (a frozen pause at a future instant). Returns: { ok, pausedAt }. Errors: clock.NOT_INSTALLED, clock.UNSUPPORTED, NOT_RUNNING.

Convert a diagnostic JSONL trace into a compact, reviewable stagewright-replay v1 spec. The promoted spec keeps tool args plus explicit ok checkpoints, replaces recorded session ids with stable placeholders, keeps any required session creator, and applies named args.* redactions BEFORE writing. Use it as the starting point for committed regression checks; add result matchers intentionally rather than treating every raw response as a brittle oracle. parameters turns recorded values into declared parameters of a v2 spec: every argument exactly equal to a parameter value becomes { "$param": name …

Re-run the tool calls a written trace artifact recorded, in order, against the current server, and report which steps reproduce. Session ids are remapped automatically (the replayed launch creates a fresh session; later calls are rewritten to it). A call "diverged" when its ok/code differs from the recording; diverged calls carry a bounded field-level diff. Options: dryRun (re-validate against current schemas WITHOUT launching — detects a tool whose signature changed), stopOnError, include/exclude (tool-name filters), maxCalls. Note: a trace recorded with redaction cannot be faithfully replaye…

Resume the real clock (timers advance with real wall-clock time again). Returns: { ok, resumed }. Errors: clock.NOT_INSTALLED, clock.UNSUPPORTED, NOT_RUNNING.

Tick the clock forward by `ms`, firing timers at each interval as they come due and simulating the passage of time between them — unlike clock_advance, which fires the due timers and jumps straight to the destination. Use for tight timer loops that re-schedule. Returns: { ok, ranForMs }. Errors: clock.NOT_INSTALLED, clock.UNSUPPORTED, NOT_RUNNING.

Add or overwrite one cookie to seed app state (e.g. an auth token before a flow). Provide a `url` OR a `domain` (one is required). Returns: { ok, set }. Errors: storage.UNSUPPORTED, NOT_RUNNING, BAD_ARGUMENT (neither url nor domain).

Set the clock to `time` and let it keep running from there (timers fire as wall-clock time advances them), unlike the frozen clock_set_time. Returns: { ok, systemTime }. Errors: clock.NOT_INSTALLED, clock.UNSUPPORTED, NOT_RUNNING.

Pin the clock to `time` (a frozen instant): Date.now() returns it and timers do NOT auto-fire — use clock_advance to fire them. Returns: { ok, fixed }. Errors: clock.NOT_INSTALLED (call clock_install first), clock.UNSUPPORTED, NOT_RUNNING.

Return a point-in-time storage snapshot — every cookie plus each visited origin’s localStorage — the no-eval way to ASSERT persisted state. Cookie values are redacted by default; localStorage values are NOT (they are app state, not cookie secrets — treat them as sensitive if your app stores tokens there). Returns: { ok, cookies, origins }. Errors: storage.UNSUPPORTED, NOT_RUNNING.

Begin recording every subsequent tool call (input, output, timing, token estimate) to a streaming JSONL artifact until trace_stop. Calls are written to path.partial; trace_stop adds a completion footer and atomically publishes path. Optional path (exact file) or dir (generated filename); defaults to the configured dir or the OS temp dir. The trace plugin’s own tools are not recorded. Set budgetTokens to track an estimated-token budget (reported by trace_status / trace_tokens / trace_budget); set enforce:true to additionally BLOCK over-budget tool calls with trace.BUDGET_EXCEEDED. Returns: { ok…

Report whether a fake clock is installed on the session and its last applied mode/time, so an agent can branch. Returns: { ok, installed, mode?, time? }. Errors: clock.UNSUPPORTED, NOT_RUNNING.

Stop the active recording, flush its JSONL artifact, add a completion footer, atomically publish the final path, and return a summary. Includes expiring artifact metadata and an MCP resource_link when portable size limits allow. Returns: { ok, path, records, total_estimated_tokens, overflowed, budget? }. Errors: trace.NOT_RECORDING (no active trace; call trace_start first; not retryable), trace.ARTIFACT_WRITE_FAILED (artifact could not be written; fix path/permissions and retry).

Make a captured channel’s ipcMain.handle return `response` instead of running the app’s handler, for the duration of the capture. The channel MUST be in the active capture allowlist. Cleared when ipc_capture_stop restores the originals. Returns: { ok, stubbed }. Errors: ipc.NOT_CAPTURING (start a capture first), ipc.CHANNEL_NOT_ALLOWED (channel not in the allowlist), ipc.EVAL_REQUIRED, ipc.MAIN_EVAL_UNSUPPORTED, NOT_RUNNING.

Summarise estimated token usage from a trace: total, per-tool totals, and the largest individual responses. With no path it reports the live recording (if one is active); otherwise pass path to a written artifact. Returns: { ok, path, total_estimated_tokens, calls, overflowed, by_tool, largest, budget? }. Errors: trace.NOT_RECORDING (no path and no active trace), trace.ARTIFACT_NOT_FOUND (no artifact at path), trace.ARTIFACT_INVALID (bad JSONL).

Fire an interaction event on the system-tray icon with `id` (from native_trays) — runs the app’s own tray.on(event, ...) handler, the act half of the tray surface. `event` is click / right-click / double-click (cross-platform) or a mouse-* / balloon-click platform event. The session MUST have been launched with electron_launch { main, instrumentNative: true } (trays have no registry). Note: firing right-click runs the handler but does NOT auto-open the tray context menu the way a native right-click does. Returns: { ok, emitted, id?, event?, tray?, reason? }. On success emitted is true and `tra…

Return the app’s system-tray icons — each with its tooltip, title, whether it has an icon image, and its context menu (serialised like the application menu). Trays have no registry and are created at startup, so the session MUST have been launched with electron_launch { main, instrumentNative: true }. Returns: { ok, count, trays }. Errors: native.NOT_INSTRUMENTED (relaunch with main + instrumentNative), native.UNSUPPORTED (transport cannot access the native UI), NOT_RUNNING.

Remove network stubs and restore live traffic: every stub, or only those whose allowlist includes `url` (exact match) when given. Idempotent. Returns: { ok, unstubbed }. Errors: network.UNSUPPORTED, NOT_RUNNING.

Capture the selected BrowserWindow and explicitly replace its configured-root baseline only when confirm is true. This destructive operation is separate from visual_expect; CI comparisons never update baselines implicitly. Errors: visual.UNSUPPORTED, visual.SURFACE_UNSUPPORTED, visual.INVALID_SELECTOR, visual.UNSTABLE, visual.CAPTURE_FAILED, visual.IMAGE_TOO_LARGE, visual.PATH_INVALID, visual.WRITE_FAILED.

Validate a packaged Electron release artifact and return structured results. Artifact-aware defaults run the existing eight bundle/signing checks for a macOS .app, windows-authenticode for a Windows .exe/.msi, or appimage-signature for a Linux .AppImage. A checks subset may select any check explicitly. Each result is pass (verified good), fail (verified bad, with next_actions), or unknown (missing tool, key, platform, or evidence). Returns: { ok, app_path, artifact_type, passed, summary: { pass, fail, unknown }, checks }, where passed is true when no check failed (unknown checks do not fail it…

Verify the same greeting with a single expect_text call.

Verify a greeting the primitive way: get_text, wait_for_state, get_text.

Render a written trace artifact to a single self-contained HTML report (inline CSS/JS, no external assets) that opens in any browser offline. Shows a summary (calls, ok/error counts, total estimated tokens, a budget bar when the trace carries a budget), the largest-response and per-tool token tables, and an expandable timeline of every call with its args and result. With no out path the report is written next to the trace with a .html extension. Returns: { ok, path, source, calls, bytes } where path is the written HTML file. Portable results also include expiring artifact metadata and an MCP r…