Capture diagnostics

Evidence-gathering for debugging a flow or attaching artifacts to a bug report: screenshots, console output, native dialogs, and full session traces.

Screenshots

electron_screenshot { "dir": "/abs/artifacts/dir" }
electron_screenshot { "ref": 4, "format": "jpeg", "quality": 80 }

The image is written on the server host and the call returns its absolute path (plus bytes, width/height) — bytes are never inlined into the protocol. Aim captures three ways: the whole targeted window (default; windowId / windowTitle / windowIndex select among multiple), fullPage for the entire scrollable page, or a single element via ref / selector. For a stable artifact location, pass dir per call or start the server with --screenshot-dir <dir> — otherwise files land in the OS temp directory.

Console logs

electron_console_logs { "type": ["warning", "error"], "match": "ipc", "limit": 100 }

Renderer console output is captured continuously from session start — including windows the app opens later; each entry carries the originating window's id, so multi-window output stays attributable. Filters compose (ANDed): type (level or list of levels), match (a regex over the text), since (epoch ms), limit (most recent kept). The response's overflowed field counts entries the ring buffer dropped, so "nothing matched" and "it scrolled away" are distinguishable.

Native dialogs

Dialogs (alert / confirm / prompt / beforeunload) block the renderer, so an unhandled one freezes every later call. The default policy is therefore dismiss from session start — nothing hangs — and electron_dialog_handler both arms a different policy and reads back what fired:

electron_dialog_handler { "action": "dismiss", "perType": { "confirm": "accept" }, "oneShot": true }
electron_dialog_handler { "type": "confirm", "limit": 10 }

Arming args: action (the default for every dialog), perType overrides, promptText (submitted when an accepted prompt() fires), oneShot (apply to exactly the next dialog, then revert to dismiss — so a lingering accept can never silently confirm a destructive dialog you did not anticipate). A call with no arming args is inspect-only. Every handled dialog is recorded — type, message, the action taken, timestamps — whether or not you were watching at the time.

Session traces — the flight recorder

Load the trace plugin to record every tool call of a session into a portable artifact:

node packages/core/dist/cli.js --plugin @electron-stagewright/plugin-trace

trace_start { "dir": "/abs/traces" }
… the session you want recorded …
trace_stop {}
trace_view { "path": "/abs/traces/<artifact>.jsonl" }

• trace_start begins recording (a streaming JSONL v2 artifact: header plus one sequenced record per dispatch — arguments, result envelope, timing, token estimate; sensitive values can be redacted via plugin config). Calls land in a .partial file until a clean stop atomically publishes the final artifact; a partial is readable for crash recovery. Optional budgetTokens and enforce turn the trace into a live token budget: advisory by default, vetoing over-budget calls when enforced.
• trace_status / trace_tokens / trace_budget — is it recording, where, how many records; per-tool token totals and the largest responses; a cheap budget poll.
• trace_stop flushes, adds a completion footer, atomically publishes the artifact, and returns its path plus a token report.
• trace_view renders the artifact to a single self-contained HTML file — summary cards, a token-budget bar, per-tool tables, an expandable timeline — openable anywhere, no server.
• trace_promote creates a small reviewable replay spec from a raw trace. It keeps explicit success checkpoints, normalizes session ids, and redacts password/token/authorization/cookie fields before writing; filtered calls retain their required session creators. Add result matchers only for the values a regression must observe.
• trace_replay re-dispatches a recorded session against a fresh app instance (session ids remapped automatically) and judges each step on its stable outcome — the regression-check companion: record once, replay after the change. When the MCP host requests progress, a replay that crosses 250 ms reports loading plus per-call validation/replay phases; messages identify positions only and never expose recorded tool names or artifact paths. trace_stop similarly reports when a slow artifact flush is still active. The final envelope remains authoritative.

Run a promoted spec in CI

Install @electron-stagewright/plugin-trace with the core runtime, then invoke the package's headless runner against the reviewed JSON artifact. --json writes a single bounded report to stdout and separates meaningful outcomes: checkpoint mismatch (1), malformed spec (2), app launch failure (3), infrastructure (4), and invalid CLI usage (64).

- name: Replay Electron regression
  run: xvfb-run --auto-servernum electron-stagewright-replay tests/regressions/greeting.replay.json --json > replay-report.json

- name: Upload replay report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: replay-report
    path: replay-report.json

Add --plugin, --plugin-config, --allow-eval, or the same confinement/timeout options as the MCP server when the spec needs them. --include and --exclude narrow a run while retaining the session creator required by a selected later call.

The token accounting exists because the trace's first consumer is an agent operating under a context budget: it shows which tools cost the most before the budget bites.

The artifact, not the app

When the thing to diagnose is a packaged build rather than a running session — signing, notarization, update feed, crash machinery — run the same production engine directly in CI:

electron-stagewright production validate \
  --app /absolute/path/to/My.AppImage \
  --json > production-validation.json

Install @electron-stagewright/plugin-production beside core before using the root command, or run its equivalent electron-stagewright-production binary. JSON mode writes one versioned report and uses exit 0 for no failed checks, 1 for verified failures, and 2 for invalid usage/input. The command recognizes macOS .app, Windows .exe/.msi, and Linux .AppImage artifacts and selects relevant checks by default. The MCP delivery channel remains production_validate; see the tool reference and the plugin's README. A host that opts into MCP progress receives delayed per-check phases for a long validation run, without exposing the inspected path.

A capture can hold secrets. Screenshots, console logs, traces, and IPC payloads record whatever the app exposed. Configure redact for structured trace arguments and IPC payload fields before capturing, but do not treat it as a screenshot, console-output, or arbitrary-result scrubber; write artifacts only where you control access — see the security model.

Design background: dialog auto-response defaults and console-buffer semantics follow ADR-007; the trace artifact format, replay, and the dispatch-observer seam are ADR-009; production validation is ADR-012. The model behind sessions, eval, and plugins: Concepts.