@vdoninja/mcp 0.4.0 → 0.4.2

package/scripts/lib/browser-media.js

@@ -0,0 +1,79 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const crypto = require('node:crypto');
+const http = require('node:http');
+
+// Capture only the worker's initial tab. The publisher lives in another browser
+// context and is excluded from remote tools; no desktop or microphone capture.
+async function startBrowserMedia(browser, target, title, config = {}) {
+  const token = crypto.randomBytes(24).toString('hex');
+  const server = http.createServer((req, res) => {
+    if (req.url !== `/${token}`) { res.writeHead(404); res.end(); return; }
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    res.end('<!doctype html><title>Ninja browser media publisher</title>');
+  });
+  let context, page, previousTitle;
+  const credentials = {
+    room: `media_${crypto.randomBytes(12).toString('hex')}`,
+    streamID: `chrome_${crypto.randomBytes(12).toString('hex')}`,
+    password: crypto.randomBytes(24).toString('hex')
+  };
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+    context = await browser.createBrowserContext();
+    previousTitle = await target.title();
+    await target.evaluate((value) => { document.title = value; }, title);
+    page = await context.newPage();
+    await page.goto(`http://127.0.0.1:${server.address().port}/${token}`);
+    // Close the bootstrap listener immediately. No web control endpoint remains.
+    await new Promise((resolve) => { server.close(resolve); server.closeAllConnections(); });
+    await page.addScriptTag({ path: require.resolve('@vdoninja/sdk/browser') });
+    await page.evaluate(async (settings) => {
+      const stream = await Promise.race([
+        navigator.mediaDevices.getDisplayMedia({ video: { frameRate: 15, width: { max: 1280 }, height: { max: 720 } }, audio: true, selfBrowserSurface: 'exclude' }),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Tab capture timed out')), 15000))
+      ]);
+      if (stream.getVideoTracks().some((track) => track.getSettings().displaySurface !== 'browser')) {
+        stream.getTracks().forEach((track) => track.stop());
+        throw new Error('Expected tab capture');
+      }
+      window.ninjaCapture = stream;
+      window.ninjaMedia = new VDONinjaSDK({ password: settings.password, ...(settings.host ? { host: settings.host } : {}) });
+      await Promise.race([
+        (async () => {
+          await window.ninjaMedia.connect();
+          await window.ninjaMedia.publish(stream, { room: settings.room, streamID: settings.streamID, password: settings.password, label: 'Ninja browser', media: { video: { maxBitrate: 1500000 }, audio: { maxBitrate: 64000 } } });
+        })(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Media signaling timed out')), 15000))
+      ]);
+    }, { ...credentials, host: config.host });
+    await target.evaluate((value) => { document.title = value; }, previousTitle);
+    const viewer = new URL('https://vdo.ninja/');
+    viewer.searchParams.set('view', credentials.streamID);
+    viewer.searchParams.set('room', credentials.room);
+    viewer.searchParams.set('password', credentials.password);
+    viewer.searchParams.set('cleanoutput', '');
+    return {
+      page,
+      status: async () => ({ enabled: true, transport: 'webrtc', stream_id: credentials.streamID, room: credentials.room,
+        password: credentials.password, ...(config.host ? { signaling_host: config.host } : { viewer_url: viewer.href }),
+        ...await page.evaluate(() => ({ connected: !!window.ninjaMedia.state.connected,
+          tracks: window.ninjaCapture.getTracks().map((track) => ({ kind: track.kind, state: track.readyState, muted: track.muted })) })) }),
+      close: async () => {
+        try { await page.evaluate(async () => { window.ninjaCapture.getTracks().forEach((track) => track.stop()); await window.ninjaMedia.disconnect(); }); } catch (_) { /* Browser may already be closed. */ }
+        await context.close();
+      }
+    };
+  } catch (error) {
+    server.close();
+    server.closeAllConnections();
+    if (context) await context.close();
+    throw error;
+  } finally {
+    if (previousTitle !== undefined) await target.evaluate((value) => { document.title = value; }, previousTitle).catch(() => {});
+  }
+}
+
+module.exports = { startBrowserMedia };

package/scripts/lib/browser-routes.js

@@ -0,0 +1,119 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const EventEmitter = require('node:events');
+const { BridgeSession } = require('./bridge-session');
+
+// One browser RPC worker owns authentication, leases and deduplication above
+// both routes. Switching routes never creates a second execution authority.
+class BrowserRoutes extends EventEmitter {
+  constructor(config, options = {}) {
+    super();
+    this.config = config;
+    this.sessions = new Map();
+    this.requests = new Map();
+    this.lastReplyRoute = null;
+    this.preferHttpUntil = 0;
+    this.running = false;
+    this.probing = false;
+    this.createSession = options.createSession || ((value) => new BridgeSession(value));
+    for (const transport of ['webrtc', 'http']) {
+      const session = this.createSession({ ...config, transport });
+      const listener = (event) => this.emit('event', { ...event, route: transport,
+        ...(event.uuid ? { uuid: `${transport}:${event.uuid}` } : {}) });
+      session.on('event', listener);
+      this.sessions.set(transport, session);
+    }
+  }
+
+  async start() {
+    if (this.running) return;
+    this.running = true;
+    this.probeTimer = setInterval(() => this.retryView(), 5000);
+    this.probeTimer.unref();
+    for (const [route, session] of this.sessions) {
+      const pending = session.start().catch(() => {});
+      if (route === 'http') await pending;
+    }
+  }
+
+  available(route, target) {
+    return !!this.peer(route, target);
+  }
+
+  peer(route, target) {
+    const session = this.sessions.get(route);
+    return session.listSyncPeers()
+      .filter((peer) => peer.stream_id === target && session.hasOpenDataChannel(peer.uuid))
+      .sort((a, b) => String(b.last_seen_at).localeCompare(String(a.last_seen_at)))[0];
+  }
+
+  retryView() {
+    const target = this.config.targetStreamID;
+    const rtc = this.sessions.get('webrtc');
+    if (!this.running || !target || this.probing || rtc.connecting || rtc.state !== 'connected' ||
+        !rtc.sdk || this.available('webrtc', target)) return;
+    // The worker may return with a new peer UUID while signaling stays connected.
+    // Refresh only this browser client's intended view; HTTP continues meanwhile.
+    this.probing = true;
+    rtc.sdk.view(target, { audio: false, video: false }).catch(() => {}).finally(() => { this.probing = false; });
+  }
+
+  sendRequest(packet, target, { id, attempt }) {
+    if (!this.running) return false;
+    const previous = this.requests.get(id);
+    const preferred = Date.now() < this.preferHttpUntil ? 'http' : 'webrtc';
+    let choices = [preferred, preferred === 'webrtc' ? 'http' : 'webrtc'];
+    if (attempt > 0 && previous) {
+      choices = [previous === 'webrtc' ? 'http' : 'webrtc', previous];
+      if (previous === 'webrtc') this.preferHttpUntil = Date.now() + 30000;
+    }
+    for (const route of choices) {
+      const peer = this.peer(route, target);
+      if (!peer) continue;
+      if (this.sessions.get(route).send(packet, { uuid: peer.uuid })) {
+        if (this.requests.size >= 128) this.requests.delete(this.requests.keys().next().value);
+        this.requests.set(id, route);
+        this.emit('event', { type: 'browser_route_sent', route, request_id: id, stage: 'queued' });
+        return true;
+      }
+    }
+    return false;
+  }
+
+  markResponse(id, route) {
+    this.lastReplyRoute = route;
+    this.requests.delete(id);
+    if (route === 'webrtc') this.preferHttpUntil = 0;
+    this.emit('event', { type: 'browser_route_reply', route, request_id: id, stage: 'peer_response' });
+  }
+
+  finishRequest(id) { this.requests.delete(id); }
+
+  send(packet, target) {
+    if (!this.running) return false;
+    if (typeof target === 'string') {
+      const colon = target.indexOf(':');
+      const session = this.sessions.get(target.slice(0, colon));
+      if (session) return session.send(packet, { uuid: target.slice(colon + 1) });
+    }
+    return false;
+  }
+
+  getStatus() {
+    return { transport: 'auto', last_reply_route: this.lastReplyRoute,
+      routes: Array.from(this.sessions, ([transport, session]) => ({ transport,
+        state: session.state, peers: session.listSyncPeers().filter((peer) => session.hasOpenDataChannel(peer.uuid)).length,
+        error: session.lastError || null })) };
+  }
+
+  async stop() {
+    this.running = false;
+    clearInterval(this.probeTimer);
+    this.requests.clear();
+    await Promise.allSettled(Array.from(this.sessions.values(), (session) => session.stop()));
+  }
+}
+
+module.exports = { BrowserRoutes };

package/scripts/lib/browser-rpc.js

@@ -0,0 +1,214 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const crypto = require('node:crypto');
+const MAGIC = 'ninja_browser_v1';
+const MAX_RESULT = 2 * 1024 * 1024;
+const PART_BYTES = 24000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function keyBytes(key) {
+  if (typeof key !== 'string' || !/^[a-f0-9]{64}$/i.test(key)) throw new Error('Browser keys must be 32 random bytes encoded as 64 hex characters');
+  return Buffer.from(key, 'hex');
+}
+
+// Independent, per-client encryption: another room member cannot read or forge browser operations.
+function seal(key, worker, client, direction, value, magic = MAGIC) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', keyBytes(key), iv);
+  cipher.setAAD(Buffer.from(JSON.stringify([magic, worker, client, direction])));
+  const bytes = Buffer.concat([cipher.update(JSON.stringify(value)), cipher.final()]);
+  return { browser: magic, worker, client, direction, box: Buffer.concat([iv, cipher.getAuthTag(), bytes]).toString('base64') };
+}
+
+function open(key, packet, magic = MAGIC) {
+  if (!packet || packet.browser !== magic || typeof packet.box !== 'string' || packet.box.length > 65000) throw new Error('Invalid browser packet');
+  const bytes = Buffer.from(packet.box, 'base64');
+  if (bytes.length < 29) throw new Error('Invalid browser packet');
+  const decipher = crypto.createDecipheriv('aes-256-gcm', keyBytes(key), bytes.subarray(0, 12));
+  decipher.setAAD(Buffer.from(JSON.stringify([magic, packet.worker, packet.client, packet.direction])));
+  decipher.setAuthTag(bytes.subarray(12, 28));
+  return JSON.parse(Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString('utf8'));
+}
+
+class BrowserRpcWorker {
+  constructor(session, config, execute, options = {}) {
+    this.options = options;
+    this.magic = options.magic || MAGIC;
+    this.maxResult = options.maxResult || MAX_RESULT;
+    this.session = session;
+    this.worker = config.worker;
+    this.clients = config.clients;
+    this.execute = execute;
+    this.boot = crypto.randomUUID();
+    this.records = new Map();
+    this.cacheBytes = 0;
+    this.queued = 0;
+    this.chain = Promise.resolve();
+    this.closed = false;
+    this.listener = (event) => { this.receive(event).catch(() => {}); };
+    session.on('event', this.listener);
+  }
+
+  async receive(event) {
+    const packet = event.data;
+    if (this.closed || event.type !== 'data_received' || !event.uuid || !packet || packet.browser !== this.magic || packet.worker !== this.worker || packet.direction !== 'request') return;
+    if (!Object.hasOwn(this.clients, packet.client)) return;
+    const identity = this.clients[packet.client];
+    let request;
+    try { request = open(identity.key, packet, this.magic); } catch (_) { return; }
+    const now = Date.now();
+    if (!request || typeof request.id !== 'string' || !/^[a-zA-Z0-9_-]{1,80}$/.test(request.id) || !Number.isSafeInteger(request.deadline) || request.deadline < now || request.deadline > now + 65000) return;
+    if (request.op !== 'hello' && request.boot !== this.boot) {
+      await this.reply(packet.client, event.uuid, request.id, { error: 'worker_restarted', boot: this.boot });
+      return;
+    }
+    if (this.options.onAuthenticated) this.options.onAuthenticated(packet.client, event);
+    for (const [id, record] of this.records) {
+      if (record.until < now && record.result) { this.cacheBytes -= record.bytes; this.records.delete(id); }
+    }
+    const id = `${packet.client}:${request.id}`;
+    const fingerprint = crypto.createHash('sha256').update(JSON.stringify(request)).digest('hex');
+    const previous = this.records.get(id);
+    if (previous) {
+      if (previous.fingerprint !== fingerprint) return this.reply(packet.client, event.uuid, request.id, { error: 'request_id_conflict' });
+      if (previous.result && !previous.sending) {
+        previous.sending = true;
+        try { await this.reply(packet.client, event.uuid, request.id, previous.result); } finally { previous.sending = false; }
+      }
+      return;
+    }
+    if (this.queued >= 16 || this.records.size >= 1024 || this.cacheBytes > 30 * 1024 * 1024) {
+      // Leave the request pending until capacity returns or its deadline expires.
+      // Do not report rejection while a replay could still be admitted later.
+      return;
+    }
+    const record = { fingerprint, until: request.deadline + 120000, result: null, bytes: 0, sending: false };
+    this.records.set(id, record);
+    this.queued++;
+    const run = async () => {
+      let result;
+      try {
+        if (this.closed || Date.now() > request.deadline) throw new Error('request_expired');
+        if (request.op === 'hello') result = { boot: this.boot, role: identity.role, worker: this.worker };
+        else if (request.op === 'result') {
+          const found = this.records.get(`${packet.client}:${request.args && request.args.request_id}`);
+          result = found && found.result ? { status: 'completed', result: found.result } : { status: 'unknown' };
+        } else result = await this.execute(packet.client, identity.role, request.op, request.args || {}, { ...request, peer: event.uuid });
+      } catch (error) { result = this.options.errorCodes ? { error: error.code || error.message, message: error.message } : { error: error.message }; }
+      if (Buffer.byteLength(JSON.stringify(result)) > this.maxResult) result = { error: 'result_too_large', execution: 'completed' };
+      record.result = result;
+      record.bytes = Buffer.byteLength(JSON.stringify(result));
+      this.cacheBytes += record.bytes;
+      this.queued--;
+      record.sending = true;
+      try { await this.reply(packet.client, event.uuid, request.id, result); } finally { record.sending = false; }
+    };
+    if (this.options.parallel) run().catch(() => {});
+    else this.chain = this.chain.then(run, run).catch(() => {});
+  }
+
+  async reply(client, uuid, id, result) {
+    const bytes = Buffer.from(JSON.stringify(result));
+    const count = Math.ceil(bytes.length / PART_BYTES);
+    for (let part = 0; part < count && !this.closed; part++) {
+      const packet = seal(this.clients[client].key, this.worker, client, 'response', {
+        id, boot: this.boot, part, count, data: bytes.subarray(part * PART_BYTES, (part + 1) * PART_BYTES).toString('base64')
+      }, this.magic);
+      let sent = this.session.send(packet, uuid);
+      if (!sent && this.options.backpressure) {
+        const until = Date.now() + 1000;
+        while (!sent && !this.closed && Date.now() < until) {
+          await delay(50);
+          sent = this.session.send(packet, uuid);
+        }
+      }
+      if (!sent) return;
+      // Bound queued bytes on HTTP and avoid monopolizing a data channel.
+      if (count > 1) await delay(12);
+    }
+  }
+
+  close() { this.closed = true; this.session.off('event', this.listener); }
+}
+
+class BrowserRpcClient {
+  constructor(session, config, options = {}) {
+    this.options = options;
+    this.magic = options.magic || MAGIC;
+    this.maxResult = options.maxResult || MAX_RESULT;
+    keyBytes(config.key);
+    this.session = session;
+    this.config = config;
+    this.boot = null;
+    this.pending = new Map();
+    this.listener = (event) => this.receive(event);
+    session.on('event', this.listener);
+  }
+
+  receive(event) {
+    const p = event.data;
+    if (event.type !== 'data_received' || !p || p.browser !== this.magic || p.worker !== this.config.worker || p.client !== this.config.client || p.direction !== 'response') return;
+    let value;
+    try { value = open(this.config.key, p, this.magic); } catch (_) { return; }
+    const pending = this.pending.get(value.id);
+    if (!pending || !Number.isInteger(value.count) || value.count < 1 || value.count > Math.ceil(this.maxResult / PART_BYTES) || !Number.isInteger(value.part) || value.part < 0 || value.part >= value.count || typeof value.data !== 'string' || value.data.length > 32000) return;
+    if (pending.count && (pending.count !== value.count || pending.boot !== value.boot)) return;
+    pending.count = value.count;
+    pending.boot = value.boot;
+    pending.parts.set(value.part, Buffer.from(value.data, 'base64'));
+    if (pending.parts.size === value.count) {
+      try {
+        const bytes = Buffer.concat(Array.from({ length: value.count }, (_, i) => pending.parts.get(i)));
+        if (bytes.length > this.maxResult) return;
+        const result = JSON.parse(bytes.toString('utf8'));
+        pending.route = event.route || this.session.config.transport;
+        if (this.session.markResponse) this.session.markResponse(value.id, event.route);
+        pending.resolve(result);
+      } catch (_) { /* An incomplete or invalid result is never treated as success. */ }
+    }
+  }
+
+  async request(op, args = {}, timeoutMs = 30000) {
+    if (this.pending.size >= 16) throw new Error('Too many pending browser requests');
+    if (op !== 'hello' && !this.boot) await this.connect();
+    const id = crypto.randomUUID();
+    const request = { id, boot: this.boot, deadline: Date.now() + timeoutMs, op, args };
+    const packet = seal(this.config.key, this.config.worker, this.config.client, 'request', request, this.magic);
+    if (packet.box.length > 65000) throw new Error('Browser request too large');
+    let timer, retry;
+    try {
+      const result = await new Promise((resolve) => {
+        this.pending.set(id, { resolve, parts: new Map() });
+        let attempt = 0;
+        const send = () => {
+          if (this.session.sendRequest) return this.session.sendRequest(packet, this.config.worker, { id, attempt: attempt++ });
+          return this.session.send(packet, this.config.worker);
+        };
+        send();
+        retry = setInterval(send, 2000);
+        timer = setTimeout(() => resolve({ error: 'outcome_unknown', request_id: id, message: this.options.timeoutMessage || 'Inspect browser_result and current page before repeating an action.' }), timeoutMs);
+      });
+      if (result.error === 'worker_restarted') this.boot = null;
+      return { ...result, request_id: id, route: this.pending.get(id)?.route || null };
+    } finally {
+      clearInterval(retry); clearTimeout(timer); this.pending.delete(id);
+      if (this.session.finishRequest) this.session.finishRequest(id);
+    }
+  }
+
+  async connect() {
+    const result = await this.request('hello');
+    if (result.error) throw new Error(result.error);
+    this.boot = result.boot;
+    return result;
+  }
+
+  close() {
+    this.session.off('event', this.listener);
+    for (const [id, p] of this.pending) p.resolve({ error: 'outcome_unknown', request_id: id });
+  }
+}
+
+module.exports = { BrowserRpcWorker, BrowserRpcClient, keyBytes, seal, open };

package/scripts/lib/browser-setup.js

@@ -0,0 +1,133 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const readline = require('node:readline/promises');
+const { validateRelayConfig, HttpRelayTransport } = require('./http-relay-transport');
+const { BrowserRpcClient } = require('./browser-rpc');
+
+function relaySettings(file) {
+  const value = file ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+  return {
+    relayUrl: process.env.VDON_MCP_RELAY_URL || value.url,
+    relayToken: process.env.VDON_MCP_RELAY_TOKEN || value.token,
+    relayKey: process.env.VDON_MCP_RELAY_KEY || value.key
+  };
+}
+
+function createSetup(directory, options = {}) {
+  const ssapp = options.backend === 'ssapp';
+  const transport = options.transport || 'webrtc';
+  if (!['webrtc', 'http', 'auto'].includes(transport)) throw new Error('Choose webrtc, http, or auto');
+  const connection = { room: `${ssapp ? 'ssapp' : 'browser'}_${crypto.randomBytes(12).toString('hex')}`, transport };
+  if (transport !== 'webrtc') {
+    const relay = relaySettings(options.relayConfig);
+    // Each new browser group gets its own room key while reusing the relay service.
+    relay.relayKey = crypto.randomBytes(32).toString('hex');
+    validateRelayConfig(relay);
+    Object.assign(connection, relay);
+  }
+  const worker = `${ssapp ? 'ssapp' : 'chrome'}_${crypto.randomBytes(6).toString('hex')}`;
+  const clients = {};
+  const files = [];
+  for (const [client, role] of [['agent1', 'controller'], ['agent2', 'controller'], ['viewer', 'observer']]) {
+    const key = crypto.randomBytes(32).toString('hex');
+    clients[client] = { role, key };
+    files.push([`${client}.json`, { worker, client, key, connection, ...(ssapp ? { backend: 'ssapp' } : {}) }]);
+  }
+  files.push(['worker.json', { worker, clients, connection, ...(ssapp ? { backend: 'ssapp', ssapp: options.ssapp } : {}), ...(options.media ? { media: { enabled: true } } : {}) }]);
+  const script = path.resolve(__dirname, '..', ssapp ? 'vdo-mcp-ssapp.js' : 'vdo-mcp-browser.js');
+  files.push(['mcp-client.json', { mcpServers: { [ssapp ? 'ninja-ssapp' : 'ninja-browser']: { command: process.execPath, args: [script, '--config', path.resolve(directory, 'agent1.json')] } } }]);
+  for (const [name] of files) if (fs.existsSync(path.join(directory, name))) throw new Error(`${name} already exists; choose a new directory`);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  for (const [name, value] of files) fs.writeFileSync(path.join(directory, name), JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return { directory: path.resolve(directory), transport, worker };
+}
+
+async function guidedSetup(directory, options = {}) {
+  if (!options.transport && process.stdin.isTTY) {
+    const terminal = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      options.transport = (await terminal.question('Connection: webrtc, http, or auto [webrtc]: ')).trim() || 'webrtc';
+      if (options.transport !== 'webrtc' && !options.relayConfig && !process.env.VDON_MCP_RELAY_URL) {
+        options.relayConfig = (await terminal.question('Private relay JSON file (url, token, key): ')).trim();
+      }
+      options.media = /^y(es)?$/i.test((await terminal.question('Enable live browser-tab audio/video? [y/N]: ')).trim());
+    } finally { terminal.close(); }
+  }
+  const result = createSetup(directory, options);
+  process.stderr.write(`Created private browser configuration in ${result.directory}. Route: ${result.transport}.\n` +
+    `Host: vdon-mcp-browser --worker --config "${path.join(result.directory, 'worker.json')}"\n` +
+    `Check: vdon-mcp-browser --doctor --config "${path.join(result.directory, 'agent1.json')}"\n` +
+    'Give each agent only its own JSON file. mcp-client.json contains the local MCP registration example.\n');
+  return result;
+}
+
+async function doctor(config, makeSession) {
+  const checks = [];
+  const transport = config.connection.transport || 'webrtc';
+  checks.push({ check: 'configuration', ok: true, worker: config.worker, role: config.clients ? 'host' : 'client', transport });
+  if (config.clients) {
+    const roots = [config.dependencies || process.cwd(), path.resolve(__dirname, '..', '..')];
+    for (const [name, version] of [['chrome-devtools-mcp', '1.11.0'], ['puppeteer-core', '24.37.5']]) {
+      try {
+        const installed = require(require.resolve(`${name}/package.json`, { paths: roots })).version;
+        checks.push({ check: name, ok: installed === version, version: installed, action: installed === version ? undefined : `Install ${name}@${version}` });
+      } catch (_) { checks.push({ check: name, ok: false, action: `Install ${name}@${version} in the Ninja MCP folder` }); }
+    }
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    const supportedNode = major >= 23 || major === 22 && minor >= 12 || major === 20 && minor >= 19;
+    checks.push({ check: 'host_node', ok: supportedNode,
+      version: process.versions.node, action: supportedNode ? undefined : 'Use Node.js 22.12 or later for the Chrome worker' });
+    try {
+      const puppeteer = require(require.resolve('puppeteer-core', { paths: roots }));
+      const executable = config.executable || puppeteer.executablePath('chrome');
+      fs.accessSync(executable, fs.constants.X_OK);
+      checks.push({ check: 'chrome_executable', ok: true });
+    } catch (_) { checks.push({ check: 'chrome_executable', ok: false, action: 'Install Chrome, or set executable to its absolute path in worker.json' }); }
+  }
+  if (transport !== 'http') {
+    try {
+      require('./load-vdo-sdk').loadVDONinjaSDK();
+      checks.push({ check: 'webrtc_runtime', ok: true });
+    } catch (_) { checks.push({ check: 'webrtc_runtime', ok: transport === 'auto', available: false,
+      action: transport === 'auto' ? 'HTTP remains available; install optional WebRTC dependencies to enable the direct route' : 'Install optional WebRTC dependencies, or configure HTTP/auto with a relay' }); }
+  }
+  if (transport !== 'webrtc') {
+    let relay;
+    try {
+      relay = new HttpRelayTransport({ ...config.connection,
+        relayUrl: process.env.VDON_MCP_RELAY_URL || config.connection.relayUrl,
+        relayToken: process.env.VDON_MCP_RELAY_TOKEN || config.connection.relayToken,
+        relayKey: process.env.VDON_MCP_RELAY_KEY || config.connection.relayKey });
+      await relay.request('GET', '');
+      checks.push({ check: 'relay_access', ok: true, origin: relay.url.origin });
+    } catch (error) {
+      checks.push({ check: 'relay_access', ok: false, action: error.status === 401 ? 'Check the relay access token' : 'Check relay configuration, HTTPS reachability and /v1/rooms/ proxy routing' });
+    } finally { if (relay) relay.disconnect(); }
+  }
+  if (!config.clients) {
+    let session, rpc;
+    try {
+      session = makeSession(config, false);
+      rpc = new BrowserRpcClient(session, config);
+      await session.start();
+      const hello = await rpc.request('hello', {}, 12000);
+      if (hello.error) throw new Error(hello.error);
+      checks.push({ check: 'authenticated_worker', ok: true, role: hello.role, route: hello.route || transport });
+      rpc.boot = hello.boot;
+      const tabs = await rpc.request('tabs', {}, 12000);
+      checks.push({ check: 'browser_tools', ok: !tabs.error && !tabs.result?.isError,
+        action: tabs.error || tabs.result?.isError ? 'Restart the browser worker and inspect its host diagnostics' : undefined });
+    } catch (_) {
+      checks.push({ check: 'authenticated_worker', ok: false,
+        action: 'Start the host with its matching worker.json. Check room, worker ID, per-agent key, and at least one shared route. Relay access alone does not prove worker access.' });
+    } finally { if (rpc) rpc.close(); if (session) await session.stop(); }
+  }
+  return { ok: checks.every((check) => check.ok), checks };
+}
+
+module.exports = { relaySettings, createSetup, guidedSetup, doctor };