recovery-probe 1.1.0-preview.2 → 1.1.0-preview.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,12 @@ All notable changes to Recovery Probe are documented here. The project follows [
4
4
 
5
5
  Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
6
6
 
7
+ ## 1.1.0-preview.3 (2026-11-13)
8
+
9
+ - `observe` checks the target window when the capture starts and says when the page is hidden or draws no frames, the usual reason a click step times out. `restoreWindow` un-minimizes the window for the capture, and `keepRendering` (IPC) keeps a minimized or covered window drawing where it is by turning off its background throttling through the development hook. Both put the window back afterwards, and the report records it under `window`. The hook gains a `setBackgroundThrottling` control. `check`, `discover`, `action` and `refresh` now also warn about a hidden page, not only one that reports itself visible but draws nothing. These window messages now go to stderr, so `--json` output on stdout stays parseable.
10
+ - Add MCP Registry ownership and launch metadata with stable-only OIDC publication.
11
+ - Add a reproducible stdio MCP retry demonstration and clarify unattended setup and dependencies.
12
+
7
13
  ## 1.1.0-preview.2 (2026-10-28)
8
14
 
9
15
  - Reject browser-origin WebSocket connections and untrusted Host headers on the Android CDP bridge before opening an upstream connection. Validate the network proxy control API's Host header to block DNS rebinding.
package/README.md CHANGED
@@ -22,6 +22,8 @@ npx playwright install chromium
22
22
  npx recovery-probe demo
23
23
  ```
24
24
 
25
+ The next preview, `1.1.0-preview.3`, adds observation controls for minimized or covered Electron windows. After publication, install it with `npm install --save-dev recovery-probe@next playwright`. Until then, use the [source installation instructions](CONTRIBUTING.md#install-an-unpublished-source-preview).
26
+
25
27
  The demo runs two versions of a small app. Both load fine. Only the fixed one survives a 503, a dropped connection and a broken JSON response.
26
28
 
27
29
  ## Check your own app
@@ -6,6 +6,7 @@ const checks_cjs_1 = require("./checks.cjs");
6
6
  const pushes_cjs_1 = require("./pushes.cjs");
7
7
  const state_cjs_1 = require("./state.cjs");
8
8
  const stats_cjs_1 = require("./stats.cjs");
9
+ const window_cjs_1 = require("./window.cjs");
9
10
  const installed = new WeakSet();
10
11
  // No Electron import: use its public registration API, supplied by the development app.
11
12
  function installIpcProbe(
@@ -30,6 +31,7 @@ class ProbeHook {
30
31
  #registered = new Set();
31
32
  #seenIds = new Set();
32
33
  #pushes;
34
+ #windows;
33
35
  #active = true;
34
36
  #state = null;
35
37
  #timer;
@@ -37,6 +39,7 @@ class ProbeHook {
37
39
  this.#ipcMain = ipcMain;
38
40
  this.#original = ipcMain.handle;
39
41
  this.#sender = settings.sender;
42
+ this.#windows = (0, window_cjs_1.windowControls)(settings.sender);
40
43
  this.#classify = settings.classify;
41
44
  this.#allowed = new Set(settings.channels);
42
45
  this.#allowedPushes = new Set(settings.pushChannels);
@@ -50,8 +53,7 @@ class ProbeHook {
50
53
  identify: ((challenge) => this.identify(challenge)),
51
54
  begin: (options) => this.begin(options),
52
55
  snapshot: () => this.snapshot(),
53
- windowState: () => this.windowState(),
54
- setWindowMinimized: (minimized) => this.setWindowMinimized(minimized),
56
+ ...this.#windows,
55
57
  reset: (id) => this.reset(id),
56
58
  dispose: () => this.dispose(),
57
59
  };
@@ -114,19 +116,6 @@ class ProbeHook {
114
116
  ? JSON.parse(JSON.stringify({ ...state, capturedAt: Date.now() }))
115
117
  : null;
116
118
  }
117
- windowState() {
118
- return { minimized: this.#window().isMinimized() };
119
- }
120
- setWindowMinimized(minimized) {
121
- if (typeof minimized !== 'boolean')
122
- throw new Error('Expected boolean window state');
123
- const window = this.#window();
124
- if (minimized)
125
- window.minimize();
126
- else
127
- window.restore();
128
- return { minimized: window.isMinimized() };
129
- }
130
119
  reset(id) {
131
120
  if (id !== undefined && this.#state && id !== this.#state.id)
132
121
  throw new Error('Stale run ID');
@@ -149,12 +138,6 @@ class ProbeHook {
149
138
  if (previous && Object.values(previous.channels).some((c) => c.pending))
150
139
  throw new Error('Previous real calls are still pending; wait before beginning another run');
151
140
  }
152
- #window() {
153
- const window = this.#sender()?.getOwnerBrowserWindow?.();
154
- if (!window || window.isDestroyed())
155
- throw new Error('Window control unavailable');
156
- return window;
157
- }
158
141
  #disarm() {
159
142
  clearTimeout(this.#timer);
160
143
  this.#pushes.unwrap();
@@ -5,6 +5,9 @@ export interface ProbeWebContents {
5
5
  getURL(): string;
6
6
  executeJavaScript(code: string): Promise<unknown>;
7
7
  send?(channel: string, ...args: unknown[]): void;
8
+ /** Used for the opt-in control that keeps a minimized or covered window drawing frames. */
9
+ setBackgroundThrottling?(allowed: boolean): void;
10
+ getBackgroundThrottling?(): boolean;
8
11
  /** Used for the opt-in window minimize/restore controls. */
9
12
  getOwnerBrowserWindow?(): {
10
13
  isDestroyed(): boolean;
@@ -109,6 +112,10 @@ export interface IpcProbe {
109
112
  setWindowMinimized(minimized: boolean): {
110
113
  minimized: boolean;
111
114
  };
115
+ setBackgroundThrottling(allowed: boolean): {
116
+ allowed: boolean;
117
+ previous: boolean;
118
+ };
112
119
  reset(id?: string): IpcSnapshot | null;
113
120
  dispose(): void;
114
121
  }
@@ -0,0 +1,39 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.windowControls = windowControls;
4
+ function windowControls(sender) {
5
+ const window = () => {
6
+ const owner = sender()?.getOwnerBrowserWindow?.();
7
+ if (!owner || owner.isDestroyed())
8
+ throw new Error('Window control unavailable');
9
+ return owner;
10
+ };
11
+ return {
12
+ windowState: () => ({ minimized: window().isMinimized() }),
13
+ setWindowMinimized(minimized) {
14
+ if (typeof minimized !== 'boolean')
15
+ throw new Error('Expected boolean window state');
16
+ const owner = window();
17
+ if (minimized)
18
+ owner.minimize();
19
+ else
20
+ owner.restore();
21
+ return { minimized: owner.isMinimized() };
22
+ },
23
+ /** Throttled, a minimized or covered window draws no frames, so clicks wait forever. */
24
+ setBackgroundThrottling(allowed) {
25
+ if (typeof allowed !== 'boolean')
26
+ throw new Error('Expected boolean background throttling');
27
+ const contents = sender();
28
+ if (!contents?.setBackgroundThrottling || contents.isDestroyed())
29
+ throw new Error('Rendering control unavailable');
30
+ // Electron throttles by default; older versions cannot report it.
31
+ const previous = contents.getBackgroundThrottling?.() ?? true;
32
+ contents.setBackgroundThrottling(allowed);
33
+ return {
34
+ allowed: contents.getBackgroundThrottling?.() ?? allowed,
35
+ previous,
36
+ };
37
+ },
38
+ };
39
+ }
@@ -0,0 +1,16 @@
1
+ import type { ProbeWebContents } from './types.cjs';
2
+ type Sender = () => ProbeWebContents | undefined | null;
3
+ export declare function windowControls(sender: Sender): {
4
+ windowState: () => {
5
+ minimized: boolean;
6
+ };
7
+ setWindowMinimized(minimized: boolean): {
8
+ minimized: boolean;
9
+ };
10
+ /** Throttled, a minimized or covered window draws no frames, so clicks wait forever. */
11
+ setBackgroundThrottling(allowed: boolean): {
12
+ allowed: boolean;
13
+ previous: boolean;
14
+ };
15
+ };
16
+ export {};
@@ -18,8 +18,10 @@ export interface WindowReport {
18
18
  initial: WindowVisibility;
19
19
  restoration?: Awaited<ReturnType<PreparedVisibility['revert']>>;
20
20
  }
21
- export declare function prepareVisibility(page: Page, { restoreWindow, control, announce, }?: {
21
+ export declare function prepareVisibility(page: Page, { restoreWindow, keepRendering, control, announce, }?: {
22
22
  restoreWindow?: boolean;
23
+ /** Keeps a minimized or covered Electron window drawing frames, through the IPC hook. */
24
+ keepRendering?: boolean;
23
25
  control?: IpcInspector;
24
26
  announce?: (message: string) => void;
25
27
  }): Promise<{
@@ -107,13 +107,43 @@ async function setWindowState(page, control, initial, state) {
107
107
  await session.detach();
108
108
  }
109
109
  }
110
- export async function prepareVisibility(page, { restoreWindow = false, control, announce = console.log, } = {}) {
110
+ /** Warns when the page is hidden or draws no frames, which stalls clicks. */
111
+ function warnUnlessDrawing(window, announce) {
112
+ const draws = window.visibility === 'visible' &&
113
+ !(window.rendering && NOT_RENDERING[window.rendering]);
114
+ if (!draws)
115
+ announce(`Recovery Probe: ${window.diagnosis}. Clicks may time out, and the run may not match what a user sees.`);
116
+ }
117
+ /** Turns off the window's background throttling through the IPC hook; returns how to turn it back. */
118
+ async function keepDrawing(control, announce) {
119
+ if (!control)
120
+ throw new Error('keepRendering needs the IPC development hook');
121
+ const { previous } = await control
122
+ .call('setBackgroundThrottling', false)
123
+ .catch((error) => {
124
+ throw new Error(`keepRendering needs this version's development hook; restart the app so it loads it (${error.message})`);
125
+ });
126
+ announce('Recovery Probe: keeping the target window drawing frames while it is minimized or covered; its background throttling is restored afterwards.');
127
+ return async () => {
128
+ const { allowed } = await control.call('setBackgroundThrottling', previous);
129
+ if (allowed !== previous)
130
+ throw new Error('Background throttling restoration unverified');
131
+ };
132
+ }
133
+ export async function prepareVisibility(page, { restoreWindow = false, keepRendering = false, control,
134
+ // stderr, so a command's JSON on stdout stays parseable.
135
+ announce = (message) => console.error(message), } = {}) {
111
136
  const initial = await windowVisibility(page, control);
112
- if (initial.rendering && NOT_RENDERING[initial.rendering])
113
- announce(`Recovery Probe: ${initial.diagnosis}. Clicks may time out, and the run may not match what a user sees.`);
137
+ const restoring = restoreWindow && initial.windowState === 'minimized';
138
+ if (!restoring && !keepRendering)
139
+ warnUnlessDrawing(initial, announce);
114
140
  const set = (state) => setWindowState(page, control, initial, state);
141
+ const restoreDrawing = keepRendering
142
+ ? await keepDrawing(control, announce)
143
+ : undefined;
115
144
  let changed = false;
116
145
  const revert = async () => {
146
+ await restoreDrawing?.();
117
147
  if (!changed)
118
148
  return { changed: false, restored: true };
119
149
  await set(initial.windowState);
@@ -122,7 +152,7 @@ export async function prepareVisibility(page, { restoreWindow = false, control,
122
152
  throw new Error('Window state restoration unverified');
123
153
  return { changed: true, restored: true, final };
124
154
  };
125
- if (restoreWindow && initial.windowState === 'minimized') {
155
+ if (restoring) {
126
156
  announce('Recovery Probe: restoring the minimized target window for this run; its original state will be restored afterwards.');
127
157
  changed = true; // An unsuccessful reply may still have executed.
128
158
  await unminimize(page, control, set, revert);
@@ -10,9 +10,14 @@ export interface IpcInspector {
10
10
  call(method: 'setWindowMinimized', minimized: boolean): Promise<{
11
11
  minimized: boolean;
12
12
  }>;
13
+ call(method: 'setBackgroundThrottling', allowed: boolean): Promise<{
14
+ allowed: boolean;
15
+ previous: boolean;
16
+ }>;
13
17
  close(): void;
14
18
  }
15
- type ProbeControl = 'identify' | 'begin' | 'snapshot' | 'reset' | 'windowState' | 'setWindowMinimized';
19
+ type ProbeControl = (typeof CONTROLS)[number];
20
+ declare const CONTROLS: readonly ["identify", "begin", "snapshot", "reset", "windowState", "setWindowMinimized", "setBackgroundThrottling"];
16
21
  export declare function connectIpcInspector(endpoint?: string): Promise<IpcInspector>;
17
22
  /** Advanced protocol transport; only the documented probe control methods are allowed. */
18
23
  export declare function callIpcInspector(send: (method: string, params: Record<string, unknown>) => Promise<unknown>, method: ProbeControl, argument?: unknown): Promise<any>;
@@ -7,6 +7,7 @@ const CONTROLS = [
7
7
  'reset',
8
8
  'windowState',
9
9
  'setWindowMinimized',
10
+ 'setBackgroundThrottling',
10
11
  ];
11
12
  export async function connectIpcInspector(endpoint = 'http://127.0.0.1:9229') {
12
13
  const socket = await InspectorSocket.open(await debuggerUrl(endpoint));
@@ -38,5 +38,9 @@ export interface ObservationConfig {
38
38
  detail: 'content' | 'region';
39
39
  observationMs: number;
40
40
  sampleMs: number;
41
+ /** Un-minimizes the target window for the capture and minimizes it again afterwards. */
42
+ restoreWindow: boolean;
43
+ /** Keeps a minimized or covered window drawing frames for the capture, through the IPC hook. */
44
+ keepRendering: boolean;
41
45
  }
42
46
  export declare function observationConfig(input: unknown): ObservationConfig;
@@ -28,6 +28,8 @@ const DEFAULTS = {
28
28
  detail: 'content',
29
29
  observationMs: 30000,
30
30
  sampleMs: 100,
31
+ restoreWindow: false,
32
+ keepRendering: false,
31
33
  };
32
34
  const RANGES = [
33
35
  ['observationMs', 500, 600000],
@@ -51,12 +53,18 @@ export function observationConfig(input) {
51
53
  c.actions = actionsConfig(c.actions);
52
54
  if (c.slowReads !== undefined)
53
55
  c.slowReads = slowReadsConfig(c.slowReads);
56
+ validateWindowOptions(c);
54
57
  if (c.transport === 'http')
55
58
  validateHttpTarget(c);
56
59
  else
57
60
  validateIpcTarget(c);
58
61
  return c;
59
62
  }
63
+ function validateWindowOptions(c) {
64
+ for (const key of ['restoreWindow', 'keepRendering'])
65
+ ensure(typeof c[key] === 'boolean', `${key} must be boolean`);
66
+ ensure(!c.keepRendering || c.transport === 'ipc', 'keepRendering needs transport ipc and the development hook');
67
+ }
60
68
  const isLoopbackDevtools = (url) => ['http:', 'ws:'].includes(url.protocol) &&
61
69
  ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
62
70
  !url.username &&
@@ -1,3 +1,4 @@
1
+ import type { WindowReport } from '../../targets/visibility.mjs';
1
2
  import type { NetworkRuleSummary } from '../../transports/net/types.mjs';
2
3
  import type { ActionEffect } from './action-effects.mjs';
3
4
  import type { ContentComparison } from './comparisons.mjs';
@@ -245,6 +246,9 @@ export interface ObservationReport {
245
246
  cleanupError?: string;
246
247
  /** Set by the CLI when closing the browser connection failed. */
247
248
  disconnectError?: string;
249
+ /** The target window's state when the capture started, and what putting it back did. */
250
+ window?: WindowReport;
251
+ windowRestoreError?: string;
248
252
  coverage?: {
249
253
  historyBeforeCapture: string;
250
254
  pendingBeforeCapture: string;
@@ -1,3 +1,6 @@
1
+ import type { Browser } from 'playwright';
2
+ import { type PreparedVisibility } from '../../targets/visibility.mjs';
3
+ import { type IpcInspector } from '../../transports/ipc/inspector.mjs';
1
4
  import { type ObservationHooks } from './capture.mjs';
2
5
  import type { ObservationConfig } from './config.mjs';
3
6
  import { type FileFaultEvidence } from './file-faults.mjs';
@@ -27,10 +30,19 @@ export interface ObserveSession {
27
30
  }
28
31
  /** Network steps over the `recovery-probe net` at `address`, which must be running. */
29
32
  export declare function connectNetworkSteps(address: string): Promise<NetworkSteps>;
33
+ /** What a session attached to, so it can be released whether or not the capture ran. */
34
+ interface Target {
35
+ browser?: Browser;
36
+ browserVersion: string | null;
37
+ control?: IpcInspector;
38
+ visibility?: PreparedVisibility;
39
+ }
30
40
  /**
31
41
  * Attaches to the configured renderer, runs the capture with any steps, then restores
32
42
  * what the steps changed and adds their evidence to the report. A capture that could
33
43
  * not start still returns an incomplete report.
34
44
  */
35
45
  export declare function observeSession(config: ObservationConfig, options: ObserveSessionOptions): Promise<ObserveSession>;
46
+ /** Reverts what preparing the window changed; a failure is a cleanup error, like a failed disconnect. */
47
+ export declare function putBackWindow(target: Pick<Target, 'visibility'>, report: ObservationReport): Promise<void>;
36
48
  export {};
@@ -1,5 +1,6 @@
1
1
  import { connectDesktop, selectDesktopPage } from '../../targets/cdp.mjs';
2
2
  import { attachIpcWindow } from '../../targets/ipc-window.mjs';
3
+ import { prepareVisibility, } from '../../targets/visibility.mjs';
3
4
  import { connectIpcInspector, } from '../../transports/ipc/inspector.mjs';
4
5
  import { connectNetworkFaults } from '../../transports/net/client.mjs';
5
6
  import { httpObservationAdapter, ipcObservationAdapter, } from './adapters.mjs';
@@ -71,7 +72,12 @@ async function capture(config, target, options, files) {
71
72
  /* Metadata may be unavailable on an attached runtime. */
72
73
  }
73
74
  const { page, adapter } = await selectTarget(config, browser, target);
74
- return runObservation(page, config, adapter, {
75
+ target.visibility = await prepareVisibility(page, {
76
+ restoreWindow: config.restoreWindow,
77
+ keepRendering: config.keepRendering,
78
+ control: target.control,
79
+ });
80
+ const report = await runObservation(page, config, adapter, {
75
81
  signal: options.signal,
76
82
  takeMarker: options.hooks.takeMarker,
77
83
  onReady() {
@@ -84,6 +90,8 @@ async function capture(config, target, options, files) {
84
90
  },
85
91
  ...operatorFor(page, options, files),
86
92
  });
93
+ report.window = { initial: target.visibility.initial };
94
+ return report;
87
95
  }
88
96
  async function selectTarget(config, browser, target) {
89
97
  if (config.transport === 'http') {
@@ -143,6 +151,7 @@ async function restore(files, network) {
143
151
  return restored;
144
152
  }
145
153
  async function release(target, report) {
154
+ await putBackWindow(target, report);
146
155
  target.control?.close();
147
156
  try {
148
157
  await target.browser?.close();
@@ -153,6 +162,19 @@ async function release(target, report) {
153
162
  report.disconnectError = error.message;
154
163
  }
155
164
  }
165
+ /** Reverts what preparing the window changed; a failure is a cleanup error, like a failed disconnect. */
166
+ export async function putBackWindow(target, report) {
167
+ try {
168
+ const restoration = await target.visibility?.revert();
169
+ if (report.window && restoration)
170
+ report.window.restoration = restoration;
171
+ }
172
+ catch (error) {
173
+ report.status = 'incomplete';
174
+ report.captureComplete = false;
175
+ report.windowRestoreError = error.message;
176
+ }
177
+ }
156
178
  /** Adds the directory's changes to the report, and returns the paths for files.json. */
157
179
  async function fileChanges(report, files, faults) {
158
180
  if (!files.snapshots.length)
package/docs/ipc.md CHANGED
@@ -58,7 +58,7 @@ Use the actual development startup command with these flags reaching **Electron*
58
58
 
59
59
  If startup already enables the Node inspector, inspect its actual port rather than adding a conflicting flag. The Node inspector controls the main-process probe; CDP observes the renderer. Both must remain loopback-only and be disabled after testing. Inspector access can execute main-process code; it is a development interface, not a production service.
60
60
 
61
- Sign in with a fixture account, open the intended route, and keep the window visible and online. With Electron's default background throttling, a minimized window hides the page and stops the check. `"restoreWindow": true` in the scenario, or `--restore-window`, un-minimizes the window for the check and minimizes it again at the end; the report records both under `window`. Preserve hash navigation; when passing a `#/route` through Git Bash tooling, check that MSYS path conversion has not rewritten it. The checker uses the actual target WebContents URL, including hash/query, and reloads the existing page without requiring a route argument.
61
+ Sign in with a fixture account, open the intended route, and keep the window visible and online. With Electron's default background throttling, a minimized window hides the page and stops the check. `"restoreWindow": true` in the scenario, or `--restore-window`, un-minimizes the window for the check and minimizes it again at the end; the report records both under `window`. An [observation](observe.md#a-minimized-or-covered-window) can instead keep a minimized or covered window drawing where it is with `"keepRendering": true`, which turns off its background throttling through the hook for the capture. Preserve hash navigation; when passing a `#/route` through Git Bash tooling, check that MSYS path conversion has not rewritten it. The checker uses the actual target WebContents URL, including hash/query, and reloads the existing page without requiring a route argument.
62
62
 
63
63
  ## 4. Generate one local scenario
64
64
 
@@ -0,0 +1,31 @@
1
+ # A retry that looks right but does nothing
2
+
3
+ A healthy screen cannot prove that Retry works. This demonstration uses a synthetic profile page whose controller leaves its `pending` flag set when a request fails. The error message and Retry button appear, but clicking Retry returns immediately. The corrected controller clears `pending` in `finally`, allowing the next read to run.
4
+
5
+ The [controller](../examples/profile-controller.mjs) and [app](../examples/demo-server.mjs) are included in the npm package. The demonstration starts the real `recovery-probe mcp` process, performs the MCP handshake and calls its tools over stdio. No AI model, API key or external app is involved.
6
+
7
+ ## Run from a clean project
8
+
9
+ Use Node.js 22 or newer, then:
10
+
11
+ ```bash
12
+ mkdir recovery-probe-example
13
+ cd recovery-probe-example
14
+ npm init -y
15
+ npm install --save-dev recovery-probe playwright
16
+ npx playwright install chromium
17
+ node node_modules/recovery-probe/examples/mcp-demo.mjs
18
+ ```
19
+
20
+ From a source checkout, use `npm ci`, `npx playwright install chromium`, then `npm run demo:mcp`.
21
+
22
+ The demonstration:
23
+
24
+ 1. Discovers the profile GET request with `find_page_reads`.
25
+ 2. Checks the broken controller with `check_read_recovery`. Each experiment first requires a healthy data marker, then injects a 503, a dropped connection or malformed JSON and clicks Retry.
26
+ 3. Repeats the same checks against the corrected controller.
27
+ 4. Calls `compare_reports` and requires `IMPROVED`, with all three failures marked `GONE`.
28
+
29
+ It exits unsuccessfully if the broken page passes, the corrected page fails, any fault is not applied, or the comparison does not match. The detailed tool results are saved in `artifacts/mcp-demo.json`; individual reports, reproduction scripts and fix briefs are under `.recovery-probe/`.
30
+
31
+ This is a controlled comparison of two supplied implementations, not an autonomous agent repairing an unknown bug. The passing result covers these reads, markers and faults only. It does not establish overall resilience or prove that fabricated data cannot satisfy a poorly chosen marker. Use checks tied to the data your users actually need.
package/docs/mcp.md CHANGED
@@ -4,12 +4,12 @@ An AI coding agent can say "this handles a failed request" without ever seeing o
4
4
 
5
5
  ## Add it to an agent
6
6
 
7
- The server runs over stdio: the agent starts `npx recovery-probe mcp` and talks to it. Add it wherever your agent keeps its MCP servers. Most agents take this JSON:
7
+ The server runs over stdio: the agent starts `npx -y recovery-probe mcp` and talks to it. Add it wherever your agent keeps its MCP servers. Most agents take this JSON:
8
8
 
9
9
  ```json
10
10
  {
11
11
  "mcpServers": {
12
- "recovery-probe": { "command": "npx", "args": ["recovery-probe", "mcp"] }
12
+ "recovery-probe": { "command": "npx", "args": ["-y", "recovery-probe", "mcp"] }
13
13
  }
14
14
  }
15
15
  ```
@@ -22,7 +22,7 @@ Some use a different shape for the same entry. VS Code's `.vscode/mcp.json` uses
22
22
  "recovery-probe": {
23
23
  "type": "stdio",
24
24
  "command": "npx",
25
- "args": ["recovery-probe", "mcp"]
25
+ "args": ["-y", "recovery-probe", "mcp"]
26
26
  }
27
27
  }
28
28
  }
@@ -33,10 +33,10 @@ Agents configured with TOML use:
33
33
  ```toml
34
34
  [mcp_servers.recovery-probe]
35
35
  command = "npx"
36
- args = ["recovery-probe", "mcp"]
36
+ args = ["-y", "recovery-probe", "mcp"]
37
37
  ```
38
38
 
39
- If your agent has an `mcp add` command, give it the name `recovery-probe` and the command `npx recovery-probe mcp`.
39
+ If your agent has an `mcp add` command, give it the name `recovery-probe` and the command `npx -y recovery-probe mcp`.
40
40
 
41
41
  Install the package in the project, as for the other commands. The browser tools also need Playwright and Chromium:
42
42
 
@@ -45,6 +45,10 @@ npm install --save-dev recovery-probe playwright
45
45
  npx playwright install chromium
46
46
  ```
47
47
 
48
+ Run the server with your project as its working directory (the MCP client’s `cwd` setting, where supported). Install the dependencies in that same project; a temporary `npx` download alone does not install the optional browser dependencies. For a fixed executable path, use `node /absolute/path/to/project/node_modules/recovery-probe/bin/recovery-probe.mjs mcp`. Node.js 22 or newer must be available to the agent.
49
+
50
+ See [the reproducible MCP demonstration](mcp-demo.md) for a clean installation and a before/after check through the real stdio server.
51
+
48
52
  ## Tools
49
53
 
50
54
  | Tool | What it does |
package/docs/observe.md CHANGED
@@ -210,6 +210,12 @@ Each step has exactly one of `mark` (start a new interval and wait for it), `nav
210
210
  { "expect": { "role": "alert" }, "name": "repair-message", "timeoutMs": 10000 }
211
211
  ```
212
212
 
213
+ ### A minimized or covered window
214
+
215
+ Clicks and waits need a page that draws frames. Electron stops drawing a window that is minimized or covered, such as behind a locked screen, and a click step then waits until it times out. Observation checks the window when it starts and says when the page is hidden or draws no frames.
216
+
217
+ `"restoreWindow": true` un-minimizes the window for the capture and minimizes it again at the end. `"keepRendering": true` (IPC transport) asks the development hook to turn off the window's background throttling for the capture, so a minimized or covered window keeps drawing where it is, and puts the previous setting back at the end. A window the app hid itself draws nothing either way. The report records the window's state at the start, and what putting it back did, under `window`. A window that could not be put back is a cleanup error, so the capture exits with 2.
218
+
213
219
  ### Network steps
214
220
 
215
221
  With `--network URL`, steps can also take hosts away from the app's own HTTPS connections through a running [`recovery-probe net`](net.md). Use them when the app's data comes through native code, such as an SDK in the main process. Start `recovery-probe net` without `--rules` first, start the app with its `HTTPS_PROXY`, then pass its URL to `--network`.
@@ -0,0 +1,117 @@
1
+ import assert from 'node:assert/strict'
2
+ import { spawn } from 'node:child_process'
3
+ import { once } from 'node:events'
4
+ import { mkdir, writeFile } from 'node:fs/promises'
5
+ import { createInterface } from 'node:readline'
6
+ import { fileURLToPath } from 'node:url'
7
+ import { startDemoServer } from './demo-server.mjs'
8
+
9
+ // Use the packaged executable, including when this example is run by a consumer.
10
+ const child = spawn(
11
+ process.execPath,
12
+ [fileURLToPath(new URL('../bin/recovery-probe.mjs', import.meta.url)), 'mcp'],
13
+ { stdio: ['pipe', 'pipe', 'inherit'] },
14
+ )
15
+ const exited = once(child, 'exit')
16
+ const lines = createInterface({ input: child.stdout })
17
+ const pending = new Map()
18
+ let nextId = 0
19
+ lines.on('line', (line) => {
20
+ const reply = JSON.parse(line)
21
+ pending.get(reply.id)?.(reply)
22
+ })
23
+ /** @returns {Promise<any>} */
24
+ async function request(method, params = {}) {
25
+ const id = ++nextId
26
+ let timer
27
+ try {
28
+ const reply = await new Promise((resolve, reject) => {
29
+ pending.set(id, resolve)
30
+ timer = setTimeout(() => reject(Error(`Timed out: ${method}`)), 90000)
31
+ child.stdin.write(
32
+ `${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`,
33
+ )
34
+ })
35
+ assert.equal(reply.error, undefined, JSON.stringify(reply.error))
36
+ return reply.result
37
+ } finally {
38
+ clearTimeout(timer)
39
+ pending.delete(id)
40
+ }
41
+ }
42
+ async function call(name, args) {
43
+ const result = await request('tools/call', { name, arguments: args })
44
+ assert.equal(result.isError, false, JSON.stringify(result.content))
45
+ return result.structuredContent
46
+ }
47
+ const app = await startDemoServer()
48
+ try {
49
+ await request('initialize', {
50
+ protocolVersion: '2025-06-18',
51
+ capabilities: {},
52
+ clientInfo: { name: 'recovery-probe-demo', version: '1' },
53
+ })
54
+ child.stdin.write(
55
+ `${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`,
56
+ )
57
+ const listed = await request('tools/list')
58
+ assert.ok(listed.tools.some(({ name }) => name === 'check_read_recovery'))
59
+ const reads = await call('find_page_reads', {
60
+ url: `${app.url}/fixed`,
61
+ durationMs: 500,
62
+ })
63
+ assert.ok(
64
+ reads.endpoints.some(
65
+ ({ endpoint }) => endpoint === `${app.url}/api/profile`,
66
+ ),
67
+ )
68
+ const check = (page) =>
69
+ call('check_read_recovery', {
70
+ url: `${app.url}/${page}`,
71
+ endpoint: `${app.url}/api/profile`,
72
+ readySelector: '#profile',
73
+ readyText: 'Synthetic Example',
74
+ recovery: 'retry',
75
+ retrySelector: '#retry',
76
+ faults: ['http-error', 'connection-failure', 'invalid-json'],
77
+ timeoutMs: 2000,
78
+ })
79
+ const broken = await check('broken')
80
+ const fixed = await check('fixed')
81
+ assert.equal(broken.ok, false)
82
+ assert.equal(fixed.ok, true)
83
+ for (const result of broken.results) {
84
+ assert.equal(result.outcome, 'fail')
85
+ assert.ok(result.applied > 0)
86
+ }
87
+ for (const result of fixed.results) {
88
+ assert.equal(result.outcome, 'pass')
89
+ assert.ok(result.applied > 0)
90
+ }
91
+ const comparison = await call('compare_reports', {
92
+ before: [broken.report],
93
+ after: [fixed.report],
94
+ })
95
+ assert.equal(comparison.verdict, 'IMPROVED')
96
+ assert.equal(comparison.changes.length, 3)
97
+ assert.ok(comparison.changes.every(({ status }) => status === 'GONE'))
98
+ const evidence = {
99
+ expectedDemonstrationVerified: true,
100
+ broken,
101
+ fixed,
102
+ comparison,
103
+ }
104
+ await mkdir('artifacts', { recursive: true })
105
+ await writeFile(
106
+ 'artifacts/mcp-demo.json',
107
+ `${JSON.stringify(evidence, null, 2)}\n`,
108
+ )
109
+ console.log(JSON.stringify(evidence, null, 2))
110
+ } finally {
111
+ child.stdin.end()
112
+ const shutdown = setTimeout(() => child.kill(), 5000)
113
+ await exited
114
+ clearTimeout(shutdown)
115
+ lines.close()
116
+ await app.close()
117
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recovery-probe",
3
- "version": "1.1.0-preview.2",
3
+ "version": "1.1.0-preview.3",
4
4
  "type": "module",
5
5
  "description": "Find recovery and UI-state bugs in web and Electron apps through fault injection and runtime evidence. Built for developers and AI coding agents.",
6
6
  "license": "MIT",
@@ -56,7 +56,8 @@
56
56
  "CONTRIBUTING.md",
57
57
  "SECURITY.md",
58
58
  "README.md",
59
- "LICENSE"
59
+ "LICENSE",
60
+ "server.json"
60
61
  ],
61
62
  "sideEffects": false,
62
63
  "engines": {
@@ -136,6 +137,8 @@
136
137
  "prepublishOnly": "npm run test:unit && npm run test:package",
137
138
  "demo": "npm run build --silent && node dist/cli/core-demo.mjs",
138
139
  "demo:browser": "npm run build --silent && node bin/recovery-probe.mjs demo",
139
- "benchmark:observe": "npm run build --silent && node scripts/benchmark-observe.mjs"
140
- }
140
+ "benchmark:observe": "npm run build --silent && node scripts/benchmark-observe.mjs",
141
+ "demo:mcp": "npm run build && node examples/mcp-demo.mjs"
142
+ },
143
+ "mcpName": "io.github.BojanKovachki/recovery-probe"
141
144
  }
package/server.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
+ "name": "io.github.BojanKovachki/recovery-probe",
4
+ "description": "Fail reads in web and Electron test apps, inspect recovery, and compare before/after evidence.",
5
+ "repository": {
6
+ "url": "https://github.com/BojanKovachki/recovery-probe",
7
+ "source": "github"
8
+ },
9
+ "version": "1.1.0-preview.3",
10
+ "packages": [
11
+ {
12
+ "registryType": "npm",
13
+ "identifier": "recovery-probe",
14
+ "version": "1.1.0-preview.3",
15
+ "runtimeHint": "npx",
16
+ "runtimeArguments": [
17
+ {
18
+ "type": "positional",
19
+ "value": "-y"
20
+ }
21
+ ],
22
+ "packageArguments": [
23
+ {
24
+ "type": "positional",
25
+ "value": "mcp"
26
+ }
27
+ ],
28
+ "transport": {
29
+ "type": "stdio"
30
+ }
31
+ }
32
+ ]
33
+ }