@vdoninja/mcp 0.4.0 → 0.4.2

package/scripts/lib/browser-worker.js

@@ -0,0 +1,216 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { McpStdioParser } = require('./mcp-stdio-parser');
+
+class ChromeMcp {
+  constructor(entry, endpoint) {
+    this.pending = new Map();
+    this.nextId = 0;
+    this.failed = false;
+    this.child = spawn(process.execPath, [entry, `--ws-endpoint=${endpoint}`, '--page-id-routing=true',
+      '--javascript-evaluation=false', '--file-navigations=false', '--no-usage-statistics', '--no-performance-crux'], {
+      windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, UV_THREADPOOL_SIZE: '2', CHROME_DEVTOOLS_MCP_NO_CONFIG_DISCOVERY: '1', CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: '1' }
+    });
+    const parser = new McpStdioParser({ maxMessageBytes: 4 * 1024 * 1024 });
+    this.child.stdout.on('data', (chunk) => {
+      parser.push(chunk);
+      if (parser.buffer.length > 4 * 1024 * 1024) this.fail(new Error('Browser MCP response too large'));
+    });
+    // The child may log page details: keep stdout exclusively for the outer MCP protocol.
+    this.child.stderr.on('data', () => {});
+    parser.on('error', () => this.fail(new Error('Invalid browser MCP response')));
+    parser.on('message', ({ message }) => {
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      clearTimeout(pending.timer);
+      this.pending.delete(message.id);
+      if (message.error) pending.reject(new Error(message.error.message));
+      else pending.resolve(message.result);
+    });
+    this.child.on('error', (error) => this.fail(error));
+    this.child.on('exit', () => this.fail(new Error('Browser MCP stopped; restart the worker')));
+    this.child.stdin.on('error', (error) => this.fail(error));
+  }
+
+  fail(error) {
+    this.failed = true;
+    for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+    this.pending.clear();
+  }
+
+  request(method, params = {}) {
+    if (this.failed) return Promise.reject(new Error('Browser backend unavailable; restart the worker'));
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        // Do not start another action while a timed-out command may still be running.
+        this.fail(new Error('Browser operation outcome unknown; restart the worker'));
+        this.child.kill();
+      }, 20000);
+      this.pending.set(id, { resolve, reject, timer });
+      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+    });
+  }
+
+  async start() {
+    await this.request('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'ninja-browser-worker', version: '0.4.2' } });
+    this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    const { tools } = await this.request('tools/list');
+    for (const name of ['list_pages', 'take_snapshot', 'take_screenshot', 'navigate_page', 'click', 'fill', 'press_key']) {
+      const tool = tools.find((entry) => entry.name === name);
+      if (!tool || (name !== 'list_pages' && !tool.inputSchema.required.includes('pageId'))) throw new Error(`Incompatible Chrome MCP tool: ${name}`);
+    }
+  }
+
+  call(name, args) { return this.request('tools/call', { name, arguments: args }); }
+  close() { this.fail(new Error('Browser worker closed')); this.child.kill(); }
+}
+
+function exactKeys(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some((key) => !allowed.includes(key))) throw new Error('invalid_arguments');
+}
+
+class BrowserController {
+  constructor(backend, pages = [1]) {
+    this.backend = backend;
+    this.pages = new Set(pages);
+    this.leases = new Map();
+    this.snapshots = new Map();
+    this.generation = 0;
+  }
+
+  revoke(pageId) {
+    this.leases.delete(pageId);
+    this.invalidate(pageId);
+  }
+
+  invalidate(pageId) {
+    for (const [id, snapshot] of this.snapshots) if (snapshot.pageId === pageId) this.snapshots.delete(id);
+  }
+
+  async execute(client, role, op, args) {
+    if (op === 'tabs') {
+      exactKeys(args, []);
+      const raw = await this.backend.call('list_pages', {});
+      const result = { content: [{ type: 'text', text: (raw.content || []).filter((item) => item.type === 'text').map((item) => item.text.split('\n').filter((line) => {
+        const match = /^(\d+): /.exec(line);
+        return match && this.pages.has(Number(match[1]));
+      }).join('\n')).join('\n') }], isError: raw.isError };
+      return { result, leases: Array.from(this.leases, ([pageId, lease]) => ({ pageId, owner: lease.owner, generation: lease.generation, expires: lease.expires })).filter((lease) => lease.expires > Date.now()) };
+    }
+    if (!Number.isSafeInteger(args.pageId) || args.pageId < 0) throw new Error('pageId_required');
+    const pageId = args.pageId;
+    if (!this.pages.has(pageId)) throw new Error('page_not_shared');
+    if (op === 'observe') {
+      exactKeys(args, ['pageId', 'screenshot']);
+      if (args.screenshot !== undefined && typeof args.screenshot !== 'boolean') throw new Error('invalid_screenshot');
+      const result = await this.backend.call(args.screenshot ? 'take_screenshot' : 'take_snapshot', args.screenshot
+        ? { pageId, format: 'jpeg', quality: 55, fullPage: false }
+        : { pageId });
+      if (result.isError) return { result };
+      const snapshot = crypto.randomUUID();
+      // Chrome MCP's accessibility UIDs belong to its latest snapshot for this tab.
+      if (!args.screenshot) {
+        this.invalidate(pageId);
+        if (this.snapshots.size >= 128) this.snapshots.delete(this.snapshots.keys().next().value);
+        this.snapshots.set(snapshot, { client, pageId, expires: Date.now() + 30000 });
+      }
+      return { result, snapshot: args.screenshot ? null : snapshot, captured_at: new Date().toISOString() };
+    }
+    if (role !== 'controller') throw new Error('observer_cannot_control');
+    const lease = this.leases.get(pageId);
+    if (op === 'claim') {
+      exactKeys(args, ['pageId', 'ttl_ms', 'lease']);
+      const ttl = args.ttl_ms === undefined ? 60000 : args.ttl_ms;
+      if (!Number.isInteger(ttl) || ttl < 1000 || ttl > 120000) throw new Error('ttl_ms_must_be_1000_to_120000');
+      if (lease && lease.expires > Date.now()) {
+        if (lease.owner !== client || args.lease !== lease.token) throw new Error('tab_already_claimed');
+        lease.expires = Date.now() + ttl;
+        return { lease: lease.token, generation: lease.generation, expires: lease.expires };
+      }
+      if (this.leases.size >= 128) {
+        for (const [id, value] of this.leases) if (value.expires <= Date.now()) this.leases.delete(id);
+        if (this.leases.size >= 128) throw new Error('too_many_leases');
+      }
+      this.invalidate(pageId);
+      const next = { owner: client, token: crypto.randomUUID(), generation: ++this.generation, expires: Date.now() + ttl };
+      this.leases.set(pageId, next);
+      return { lease: next.token, generation: next.generation, expires: next.expires };
+    }
+    if (!lease || lease.owner !== client || lease.token !== args.lease || lease.expires <= Date.now()) throw new Error('valid_tab_lease_required');
+    if (op === 'release') {
+      exactKeys(args, ['pageId', 'lease']);
+      this.revoke(pageId);
+      return { released: true };
+    }
+    if (op !== 'call') throw new Error('unknown_browser_operation');
+    exactKeys(args, ['pageId', 'lease', 'snapshot', 'action', 'url', 'uid', 'value', 'key']);
+    const allowed = { navigate: ['url'], click: ['uid'], fill: ['uid', 'value'], key: ['key'] };
+    if (!Object.hasOwn(allowed, args.action)) throw new Error('action_not_allowed');
+    exactKeys(args, ['pageId', 'lease', 'snapshot', 'action', ...allowed[args.action]]);
+    for (const field of allowed[args.action]) if (typeof args[field] !== 'string' || args[field].length > 16000) throw new Error(`invalid_${field}`);
+    if (args.action !== 'navigate') {
+      const snapshot = this.snapshots.get(args.snapshot);
+      if (!snapshot || snapshot.client !== client || snapshot.pageId !== pageId || snapshot.expires < Date.now()) throw new Error('fresh_snapshot_required');
+    }
+    let tool, params = { pageId };
+    if (args.action === 'navigate') {
+      const url = new URL(args.url);
+      if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new Error('http_or_https_url_required');
+      tool = 'navigate_page'; params.url = url.href; params.timeout = 15000;
+    } else if (args.action === 'click') { tool = 'click'; params.uid = args.uid; }
+    else if (args.action === 'fill') { tool = 'fill'; params.uid = args.uid; params.value = args.value; }
+    else {
+      // Do not expose browser shortcuts (address bar, DevTools, file picker).
+      if (!['Enter', 'Tab', 'Escape', 'Backspace', 'Delete', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown'].includes(args.key)) throw new Error('key_not_allowed');
+      tool = 'press_key'; params.key = args.key;
+    }
+    this.invalidate(pageId);
+    return { result: await this.backend.call(tool, params), observed_after_action: false };
+  }
+}
+
+async function launchBrowser(config) {
+  // Optional peers keep browser dependencies out of ordinary room-only installations.
+  const roots = [config.dependencies || process.cwd(), path.join(__dirname, '..', '..')];
+  const resolve = (name) => require.resolve(name, { paths: roots });
+  const chromePackage = resolve('chrome-devtools-mcp/package.json');
+  const version = require(chromePackage).version;
+  if (version !== '1.11.0') throw new Error('Install chrome-devtools-mcp@1.11.0 for this worker');
+  const puppeteer = require(resolve('puppeteer-core'));
+  const captureTitle = `ninja_capture_${crypto.randomBytes(24).toString('hex')}`;
+  const mediaEnabled = !!(config.media && config.media.enabled === true);
+  const browser = await puppeteer.launch({
+    ...(config.executable ? { executablePath: config.executable } : { channel: 'chrome' }),
+    headless: true, defaultViewport: { width: 1280, height: 720 },
+    ...(mediaEnabled ? { ignoreDefaultArgs: ['--mute-audio'] } : {}),
+    args: ['--renderer-process-limit=2', '--num-raster-threads=2', ...(mediaEnabled ? [`--auto-select-tab-capture-source-by-title=${captureTitle}`, '--autoplay-policy=no-user-gesture-required'] : [])],
+    env: { ...process.env, UV_THREADPOOL_SIZE: '2' }
+  });
+  let backend, media;
+  try {
+    // The endpoint is loopback-only and never appears in remote results.
+    backend = new ChromeMcp(path.join(path.dirname(chromePackage), 'build/src/bin/chrome-devtools-mcp.js'), browser.wsEndpoint());
+    await backend.start();
+    const listed = await backend.call('list_pages', {});
+    const pages = (listed.content || []).filter((item) => item.type === 'text').flatMap((item) => Array.from(item.text.matchAll(/^(\d+): /gm), (match) => Number(match[1])));
+    if (pages.length !== 1) throw new Error('Expected one isolated browser tab');
+    const target = (await browser.pages())[0];
+    let mediaError;
+    if (mediaEnabled) {
+      try { media = await require('./browser-media').startBrowserMedia(browser, target, captureTitle, config.media); }
+      catch (error) { mediaError = error.message; }
+    }
+    return { browser, backend, pages, target, media,
+      mediaStatus: async () => media ? media.status() : { enabled: false, ...(mediaError ? { error: mediaError, action: 'Use browser_observe screenshots or restart the worker after restoring WebRTC media connectivity.' } : {}) },
+      close: async () => { backend.close(); try { if (media) await media.close(); } finally { await browser.close(); } } };
+  } catch (error) { if (backend) backend.close(); if (media) await media.close(); await browser.close(); throw error; }
+}
+
+module.exports = { ChromeMcp, BrowserController, launchBrowser };

package/scripts/lib/fake-network-sdk.js

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 'use strict';
 
 const { randomUUID } = require('./bridge-utils');

package/scripts/lib/http-relay-transport.js

@@ -0,0 +1,294 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
+'use strict';
+
+const crypto = require('node:crypto');
+const http = require('node:http');
+const https = require('node:https');
+const EventEmitter = require('node:events');
+
+function validateRelayConfig(config) {
+  let url;
+  try { url = new URL(config.relayUrl); } catch (_) { throw new Error('relay_url must be a valid HTTPS origin'); }
+  const loopback = ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    throw new Error('relay_url requires HTTPS except on loopback');
+  }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+    throw new Error('relay_url must be an origin without credentials, path, query, or fragment');
+  }
+  if (typeof config.relayToken !== 'string' || config.relayToken.length < 32 || /[^\x21-\x7e]/.test(config.relayToken)) {
+    throw new Error('relay_token requires at least 32 printable non-space characters');
+  }
+  if (typeof config.relayKey !== 'string' || !/^[a-fA-F0-9]{64}$/.test(config.relayKey)) {
+    throw new Error('relay_key requires 32 random bytes encoded as 64 hexadecimal characters');
+  }
+  return url;
+}
+
+// Implements the bridge's small SDK event/send interface without loading WebRTC.
+// POST acceptance is a relay receipt, not confirmation that a peer consumed data.
+class HttpRelayTransport extends EventEmitter {
+  constructor(config) {
+    super();
+    const origin = validateRelayConfig(config);
+    const secret = Buffer.from(config.relayKey, 'hex');
+    this.roomId = crypto.createHmac('sha256', secret).update(`ninjamcp-room-v1:${config.room}`).digest('hex');
+    this.key = Buffer.from(crypto.hkdfSync('sha256', secret, Buffer.from(this.roomId), Buffer.from('ninjamcp-relay-v1'), 32));
+    this.url = new URL(`/v1/rooms/${this.roomId}/events`, origin);
+    this.token = config.relayToken;
+    this.uuid = crypto.randomUUID();
+    this.streamID = null;
+    this.connected = false;
+    this.closed = false;
+    this.cursor = null;
+    this.peers = new Map();
+    this.seen = new Map();
+    this.requests = new Set();
+    this.pending = [];
+    this.pendingBytes = 0;
+    this.sending = false;
+    this.heartbeat = null;
+    this.retryTimer = null;
+    this.retryResolve = null;
+  }
+
+  addEventListener(name, handler) { this.on(name, handler); }
+  removeEventListener(name, handler) { this.off(name, handler); }
+  event(name, detail) { this.emit(name, { detail }); }
+
+  request(method, search, body) {
+    if (this.closed) return Promise.reject(new Error('relay transport stopped'));
+    const url = new URL(this.url);
+    url.search = search || '';
+    const encoded = body ? JSON.stringify(body) : null;
+    return new Promise((resolve, reject) => {
+      const headers = { authorization: `Bearer ${this.token}` };
+      if (encoded) {
+        headers['content-type'] = 'application/json';
+        headers['content-length'] = Buffer.byteLength(encoded);
+      }
+      const req = (url.protocol === 'https:' ? https : http).request(url, { method, headers }, (res) => {
+        const chunks = [];
+        let size = 0;
+        res.on('data', (chunk) => {
+          size += chunk.length;
+          if (size > 2 * 1024 * 1024) { res.destroy(new Error('relay response too large')); return; }
+          chunks.push(chunk);
+        });
+        res.on('error', reject);
+        res.on('end', () => {
+          let data;
+          try { data = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch (_) {
+            reject(new Error('invalid relay response')); return;
+          }
+          if (res.statusCode >= 200 && res.statusCode < 300) resolve(data);
+          else {
+            const error = new Error(`relay HTTP ${res.statusCode}`);
+            error.status = res.statusCode;
+            error.response = data;
+            reject(error);
+          }
+        });
+      });
+      this.requests.add(req);
+      req.once('close', () => this.requests.delete(req));
+      req.on('error', reject);
+      req.setTimeout(30000, () => req.destroy(new Error('relay request timed out')));
+      req.end(encoded);
+    });
+  }
+
+  seal(kind, data, target) {
+    const id = crypto.randomUUID();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', this.key, iv);
+    cipher.setAAD(Buffer.from(`${this.roomId}:${id}`));
+    const plaintext = JSON.stringify({ v: 1, from: this.uuid, stream: this.streamID, ts: Date.now(), kind, target: target || null, data });
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return { id, box: Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString('base64') };
+  }
+
+  open(event) {
+    if (!event || typeof event.id !== 'string' || typeof event.box !== 'string') throw new Error('invalid relay event');
+    const box = Buffer.from(event.box, 'base64');
+    if (box.length < 29 || box.length > 768 * 1024) throw new Error('invalid relay ciphertext');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', this.key, box.subarray(0, 12));
+    decipher.setAuthTag(box.subarray(12, 28));
+    decipher.setAAD(Buffer.from(`${this.roomId}:${event.id}`));
+    const data = JSON.parse(Buffer.concat([decipher.update(box.subarray(28)), decipher.final()]).toString('utf8'));
+    if (data.v !== 1 || typeof data.from !== 'string' || !/^[a-f0-9-]{36}$/.test(data.from) ||
+        typeof data.stream !== 'string' || data.stream.length > 256 || !Number.isFinite(data.ts) ||
+        data.ts < Date.now() - 300000 || data.ts > Date.now() + 60000 ||
+        !['hello', 'data', 'binary'].includes(data.kind) ||
+        (data.target !== null && typeof data.target !== 'string')) throw new Error('invalid relay message');
+    return data;
+  }
+
+  async connect() {
+    const result = await this.request('GET');
+    if (this.closed) return;
+    if (!result || typeof result.cursor !== 'string') throw new Error('invalid relay cursor');
+    this.cursor = result.cursor;
+    this.connected = true;
+    this.event('connected', { transport: 'http' });
+  }
+
+  async joinRoom() {}
+
+  async announce(options) {
+    if (typeof options.streamID !== 'string' || !options.streamID || options.streamID.length > 256) {
+      throw new Error('HTTP stream_id requires 1 to 256 characters');
+    }
+    this.streamID = options.streamID;
+    await this.request('POST', '', this.seal('hello', { request_reply: true }));
+    if (this.closed) return;
+    this.heartbeat = setInterval(() => {
+      if (this.connected) this.enqueue(this.seal('hello', null));
+      for (const [uuid, peer] of this.peers) {
+        if (Date.now() - peer.seen > 45000) {
+          this.peers.delete(uuid);
+          this.event('peerDisconnected', { uuid, streamID: peer.streamID });
+        }
+      }
+    }, 10000);
+    this.readLoop().catch(() => { if (!this.closed) this.event('error', { error: 'relay reader stopped' }); });
+  }
+
+  // Every holder of the room key participates. The existing bridge applies peer
+  // allowlists and join-token policy before delivering application messages.
+  async view() {}
+
+  hasOpenDataChannel(uuid) { return this.connected && (uuid ? this.peers.has(uuid) : this.peers.size > 0); }
+  sendPing() { return this.connected; }
+
+  sendData(data, target) {
+    const uuid = typeof target === 'string' ? target : target && target.uuid;
+    if (!this.hasOpenDataChannel(uuid)) return false;
+    if (target && typeof target === 'object' && !uuid) return false;
+    const binary = Buffer.isBuffer(data) || data instanceof ArrayBuffer;
+    const event = this.seal(binary ? 'binary' : 'data', binary ? Buffer.from(data).toString('base64') : data, uuid);
+    const ok = this.enqueue(event, !(data && data.__vdo_mcp));
+    this.lastMessageId = ok ? event.id : null;
+    return ok;
+  }
+
+  enqueue(event, receipt = false) {
+    const bytes = Buffer.byteLength(JSON.stringify(event));
+    if (this.closed || bytes > 768 * 1024 || this.pending.length >= 128 || this.pendingBytes + bytes > 8 * 1024 * 1024) return false;
+    this.pending.push({ event, bytes, receipt });
+    this.pendingBytes += bytes;
+    this.flush().catch(() => { if (!this.closed) this.event('error', { error: 'relay sender stopped' }); });
+    return true;
+  }
+
+  async flush() {
+    if (this.sending) return;
+    this.sending = true;
+    try {
+      while (!this.closed && this.pending.length) {
+        const item = this.pending[0];
+        let accepted = false;
+        for (let attempt = 0; attempt < 3 && !this.closed; attempt += 1) {
+          try {
+            const result = await this.request('POST', '', item.event);
+            if (!result || result.accepted !== true) throw new Error('invalid relay receipt');
+            accepted = true;
+            break;
+          } catch (error) {
+            if (error.status && error.status < 500) break;
+          }
+        }
+        if (this.closed) break;
+        this.pending.shift();
+        this.pendingBytes -= item.bytes;
+        if (item.receipt) this.event('relayReceipt', { message_id: item.event.id, stage: accepted ? 'relay_accepted' : 'delivery_unknown' });
+        if (!accepted) this.event('error', { error: 'relay send failed; delivery unknown', message_id: item.event.id });
+      }
+    } finally { this.sending = false; }
+  }
+
+  receive(event) {
+    if (this.seen.has(event.id)) return;
+    let message;
+    try { message = this.open(event); } catch (_) {
+      this.event('relayRejected', { reason: 'invalid_encrypted_message' });
+      return;
+    }
+    this.seen.set(event.id, Date.now());
+    while (this.seen.size > 4096) this.seen.delete(this.seen.keys().next().value);
+    if (message.from === this.uuid) return;
+    let peer = this.peers.get(message.from);
+    if (peer && peer.streamID !== message.stream) return;
+    if (!peer) {
+      if (message.kind !== 'hello' || this.peers.size >= 128) return;
+      peer = { streamID: message.stream, seen: Date.now() };
+      this.peers.set(message.from, peer);
+      // Reply once to discovery; repeated heartbeats do not create a reply loop.
+      this.enqueue(this.seal('hello', null));
+      this.event('peerConnected', { uuid: message.from, streamID: message.stream });
+      this.event('dataChannelOpen', { uuid: message.from, streamID: message.stream, transport: 'http' });
+    } else if (message.kind === 'hello' && message.data && message.data.request_reply === true) {
+      this.enqueue(this.seal('hello', null));
+    }
+    peer.seen = Date.now();
+    if (message.target && message.target !== this.uuid) return;
+    if (message.kind === 'data' || (message.kind === 'binary' && typeof message.data === 'string')) {
+      this.event('dataReceived', {
+        uuid: message.from, streamID: message.stream, fallback: true, message_id: event.id,
+        data: message.kind === 'binary' ? Buffer.from(message.data, 'base64') : message.data
+      });
+    }
+  }
+
+  async readLoop() {
+    let failures = 0;
+    while (!this.closed) {
+      try {
+        const result = await this.request('GET', `?after=${encodeURIComponent(this.cursor)}&wait_ms=25000`);
+        if (this.closed) return;
+        if (!result || typeof result.cursor !== 'string' || !Array.isArray(result.events)) throw new Error('invalid relay events');
+        if (!this.connected) this.event('relayConnection', { connected: true });
+        this.connected = true;
+        if (failures) this.enqueue(this.seal('hello', { request_reply: true }));
+        failures = 0;
+        for (const event of result.events) this.receive(event);
+        this.cursor = result.cursor;
+      } catch (error) {
+        if (this.closed) return;
+        if (this.connected) this.event('relayConnection', { connected: false });
+        this.connected = false;
+        failures += 1;
+        const response = error.response;
+        if (error.status === 409 && response && response.error === 'relay_history_lost' && typeof response.cursor === 'string') {
+          this.cursor = response.cursor;
+          for (const uuid of this.peers.keys()) this.event('peerDisconnected', { uuid });
+          this.peers.clear();
+          this.event('relayGap', { reason: 'relay_history_lost' });
+          this.enqueue(this.seal('hello', { request_reply: true }));
+        } else if (failures === 1) this.event('error', { error: error.message });
+        await new Promise((resolve) => {
+          this.retryResolve = resolve;
+          this.retryTimer = setTimeout(resolve, Math.min(1000 * failures, 10000));
+        });
+        this.retryResolve = null;
+        this.retryTimer = null;
+      }
+    }
+  }
+
+  disconnect() {
+    this.closed = true;
+    this.connected = false;
+    clearInterval(this.heartbeat);
+    clearTimeout(this.retryTimer);
+    if (this.retryResolve) this.retryResolve();
+    for (const req of this.requests) req.destroy(new Error('relay transport stopped'));
+    this.pending = [];
+    this.pendingBytes = 0;
+    this.peers.clear();
+  }
+}
+
+module.exports = { HttpRelayTransport, validateRelayConfig };

package/scripts/lib/load-vdo-sdk.js

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 'use strict';
 
 function loadVDONinjaSDK() {

package/scripts/lib/mcp-stdio-parser.js

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 'use strict';
 
 const EventEmitter = require('node:events');