@vdoninja/mcp 0.4.1 → 0.4.2

package/scripts/lib/ssapp-worker.js

@@ -0,0 +1,198 @@
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const http = require('node:http');
+const crypto = require('node:crypto');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { McpStdioParser } = require('./mcp-stdio-parser');
+
+const RPC_OPTIONS = { magic: 'ninja_ssapp_v1', maxResult: 10 * 1024 * 1024, parallel: true, backpressure: true, errorCodes: true,
+  timeoutMessage: 'Inspect ninja_ssapp_result and the current app before repeating an action.' };
+const error = (code, message) => Object.assign(new Error(message || code), { code });
+
+function controlOrigin(value = 'http://127.0.0.1:17777') {
+  const url = new URL(value);
+  if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw error('invalid_control_url', 'SSApp must use an http://127.0.0.1:PORT origin');
+  return url.origin;
+}
+
+function appInstance(origin) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(`${origin}/api/v1/instance`, { timeout: 2000 }, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (part) => { data += part; if (data.length > 16000) res.destroy(error('invalid_instance')); });
+      res.on('error', reject);
+      res.on('end', () => {
+        try {
+          const value = JSON.parse(data);
+          if (res.statusCode !== 200 || !/^[a-f0-9-]{36}$/i.test(value.instanceId)) throw error('instance_binding_required', 'Start SSApp with API 1.4.1 or newer and enable Local AI / Automation');
+          resolve(value);
+        } catch (failure) { reject(failure); }
+      });
+    });
+    req.on('timeout', () => req.destroy(error('SSAPP_UNREACHABLE')));
+    req.on('error', reject);
+  });
+}
+
+function validateCommand(settings) {
+  if (!settings || !path.isAbsolute(settings.command || '') || !Array.isArray(settings.args) || settings.args.some((arg) => typeof arg !== 'string')) throw error('invalid_mcp_command', 'Set an absolute host MCP executable and its argument array');
+}
+
+class LocalMcp {
+  constructor(settings, instanceId) {
+    validateCommand(settings);
+    this.pending = new Map(); this.nextId = 0; this.failed = false;
+    this.child = spawn(settings.command, settings.args, { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'], cwd: settings.cwd,
+      env: { ...process.env, ...(settings.env || {}), UV_THREADPOOL_SIZE: '2', SSAPP_CONTROL_URL: controlOrigin(settings.controlUrl),
+        SSAPP_EXPECTED_INSTANCE_ID: instanceId || 'offline', SSAPP_MCP_REQUEST_TIMEOUT_MS: '35000' } });
+    this.child.stderr.on('data', () => {});
+    const parser = new McpStdioParser({ maxMessageBytes: RPC_OPTIONS.maxResult });
+    parser.on('message', ({ message }) => {
+      if (message.method && message.id === undefined) { if (this.onNotification) this.onNotification(message); return; }
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      clearTimeout(pending.timer); this.pending.delete(message.id);
+      if (message.error) pending.reject(error('local_mcp_error', message.error.message));
+      else pending.resolve(message.result);
+    });
+    parser.on('error', () => this.fail(error('invalid_mcp_response')));
+    this.child.stdout.on('data', (chunk) => { parser.push(chunk); if (parser.buffer.length > RPC_OPTIONS.maxResult) this.fail(error('mcp_response_too_large')); });
+    this.child.on('error', (failure) => this.fail(failure));
+    this.child.on('exit', () => this.fail(error('local_mcp_closed')));
+    this.child.stdin.on('error', (failure) => this.fail(failure));
+  }
+  fail(failure) {
+    this.failed = true;
+    for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(failure); }
+    this.pending.clear();
+  }
+  request(method, params = {}) {
+    if (this.failed) return Promise.reject(error('local_mcp_closed'));
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.fail(error('local_mcp_timeout', 'Local MCP outcome unknown. Inspect SSApp before resuming control.')); this.child.kill(); }, 38000);
+      this.pending.set(id, { resolve, reject, timer });
+      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+    });
+  }
+  async start() {
+    this.info = await this.request('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'ninja-ssapp-host', version: '0.4.2' } });
+    if (this.info.serverInfo?.name !== 'social-stream-ninja') throw error('wrong_mcp_backend', 'Configure SSApp\'s own MCP connector');
+    const version = String(this.info.serverInfo.version).split('.').map(Number);
+    if (!(version[0] > 1 || version[0] === 1 && (version[1] > 3 || version[1] === 3 && version[2] >= 1))) throw error('instance_binding_required', 'Use SSApp MCP adapter 1.3.1 or newer for remote access');
+    this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    this.catalog = await this.request('tools/list');
+    if (!Array.isArray(this.catalog.tools) || this.catalog.tools.some((tool) => !tool.name.startsWith('ssapp_'))) throw error('invalid_ssapp_catalog');
+  }
+  async close() {
+    this.fail(error('local_mcp_closed'));
+    if (!this.child.stdin.destroyed) this.child.stdin.end();
+    if (this.child.exitCode !== null) return;
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => { this.child.kill(); resolve(); }, 1500);
+      this.child.once('exit', () => { clearTimeout(timer); resolve(); });
+    });
+  }
+}
+
+class SsappController {
+  constructor(config) {
+    this.config = config;
+    this.origin = controlOrigin(config.ssapp.controlUrl);
+    this.instance = null; this.lastInstanceId = null; this.local = null; this.checking = null; this.lease = null;
+    this.generation = 0; this.mutations = Promise.resolve(); this.queued = 0; this.closed = false; this.uncertain = false;
+    this.discovered = new Map();
+  }
+  revoke() { this.lease = null; this.generation++; }
+  async ensure() {
+    if (this.checking) return this.checking;
+    this.checking = (async () => {
+      let instance = null;
+      try { instance = await appInstance(this.origin); } catch (_) { /* Offline discovery still exposes the local tool catalog. */ }
+      if (this.closed) throw error('worker_closed');
+      if (this.instance?.instanceId !== instance?.instanceId) { this.revoke(); this.discovered.clear(); }
+      // A temporary API outage does not resolve a previously dispatched action.
+      if (instance && instance.instanceId !== this.lastInstanceId) { this.uncertain = false; this.lastInstanceId = instance.instanceId; }
+      if (!this.local || this.local.failed || this.instance?.instanceId !== instance?.instanceId) {
+        if (this.local) await this.local.close();
+        this.instance = instance;
+        this.local = new LocalMcp(this.config.ssapp, instance?.instanceId);
+        try { await this.local.start(); } catch (failure) { await this.local.close(); throw failure; }
+      }
+      this.instance = instance;
+      return instance;
+    })().finally(() => { this.checking = null; });
+    return this.checking;
+  }
+  allowed(client, tool) {
+    const identity = this.config.clients[client];
+    return (!identity.tools || identity.tools.includes(tool.name)) && (identity.role === 'controller' || tool.annotations?.readOnlyHint === true);
+  }
+  async discovery(client) {
+    await this.ensure();
+    if (this.instance) this.discovered.set(client, this.instance.instanceId);
+    const identity = this.config.clients[client];
+    return { backend: 'ssapp', contract: 1, instance: this.instance, serverInfo: this.local.info.serverInfo,
+      instructions: this.local.info.instructions, role: identity.role, allowHostFiles: identity.allowHostFiles === true,
+      catalog: { ...this.local.catalog, tools: this.local.catalog.tools.filter((tool) => this.allowed(client, tool)) },
+      lease: this.lease && this.lease.expires > Date.now() ? { owner: this.lease.owner, expires: this.lease.expires } : null,
+      uncertain: this.uncertain, limits: { result_bytes: RPC_OPTIONS.maxResult, request_envelope_bytes: 65000, timeout_ms: 60000 }, live_frames: false };
+  }
+  checkLease(client, args) {
+    if (!this.lease || this.lease.owner !== client || this.lease.token !== args.lease || this.lease.expires <= Date.now()) throw error('valid_app_lease_required');
+  }
+  async execute(client, role, op, args, request) {
+    if (op === 'discover') return this.discovery(client);
+    if (op === 'release') { this.checkLease(client, args); this.revoke(); return { released: true }; }
+    await this.ensure();
+    if (this.closed || Date.now() >= request.deadline) throw error('request_expired');
+    if (this.instance && (args.instance !== this.instance.instanceId || this.discovered.get(client) !== this.instance.instanceId)) throw error('fresh_app_discovery_required', 'Call ninja_ssapp_status, discover targets, and claim control again');
+    if (op === 'claim') {
+      if (!this.instance) throw error('SSAPP_UNREACHABLE', 'Start SSApp with API 1.4.1 or newer and enable Local AI / Automation');
+      if (role !== 'controller') throw error('observer_cannot_control');
+      const ttl = args.ttl_ms === undefined ? 60000 : args.ttl_ms;
+      if (!Number.isInteger(ttl) || ttl < 1000 || ttl > 120000) throw error('invalid_lease_duration');
+      if (this.uncertain && args.reconciled !== true) throw error('execution_uncertain', 'Inspect the app and operation result, then claim with reconciled: true to resume');
+      if (this.lease && this.lease.expires > Date.now() && (this.lease.owner !== client || this.lease.token !== args.lease)) throw error('app_already_claimed');
+      this.uncertain = false;
+      this.lease = { owner: client, token: this.lease?.expires > Date.now() ? this.lease.token : crypto.randomUUID(), expires: Date.now() + ttl };
+      return { lease: this.lease.token, expires: this.lease.expires, instance: this.instance.instanceId };
+    }
+    if (op !== 'call') throw error('unknown_ssapp_operation');
+    const tool = this.local.catalog.tools.find((item) => item.name === args.name);
+    if (!tool || !this.allowed(client, tool)) throw error('tool_not_permitted');
+    const mutation = tool.annotations?.readOnlyHint !== true;
+    if (mutation) { if (!this.instance) throw error('SSAPP_UNREACHABLE'); this.checkLease(client, args); }
+    if (args.name === 'ssapp_browser_frame_stream') throw error('remote_frames_unavailable', 'Use ssapp_browser_screenshot; local stream URLs cannot be used remotely');
+    if ((args.name === 'ssapp_browser_choose_files' || args.name === 'ssapp_respond_to_app_dialog' && args.arguments?.paths?.length) && this.config.clients[client].allowHostFiles !== true) throw error('host_file_access_disabled');
+    const generation = this.generation;
+    const dispatch = async () => {
+      if (this.closed || generation !== this.generation || Date.now() >= request.deadline) throw error('request_revoked_or_expired');
+      if (mutation) this.checkLease(client, args);
+      // The local adapter sends the app-instance condition with every HTTP request,
+      // including capability checks. A restart between checks cannot admit input.
+      let result;
+      try { result = await this.local.request('tools/call', { name: args.name, arguments: args.arguments || {} }); }
+      catch (failure) { if (mutation) { this.uncertain = true; this.revoke(); } throw failure; }
+      const code = result.structuredContent?.error?.code;
+      if (mutation && ['SSAPP_UNREACHABLE', 'SSAPP_TIMEOUT'].includes(code)) { this.uncertain = true; this.revoke(); }
+      if (code === 'SSAPP_INSTANCE_CHANGED') { this.revoke(); this.discovered.clear(); }
+      return { result };
+    };
+    // Observations and prompt recovery must remain usable during long waits or a
+    // blocked renderer. Ordinary mutations retain one queue and one controller.
+    if (!mutation || args.name === 'ssapp_respond_to_app_dialog') return dispatch();
+    if (this.queued >= 8) throw error('mutation_queue_full');
+    this.queued++;
+    const pending = this.mutations.then(dispatch, dispatch);
+    this.mutations = pending.catch(() => {});
+    try { return await pending; } finally { this.queued--; }
+  }
+  async close() { this.closed = true; this.revoke(); if (this.checking) await this.checking.catch(() => {}); if (this.local) await this.local.close(); }
+}
+
+module.exports = { RPC_OPTIONS, LocalMcp, SsappController, controlOrigin, appInstance, validateCommand };

package/scripts/lib/tool-profiles.js

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

package/scripts/vdo-data-bridge.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+
 'use strict';
 
 const readline = require('node:readline');

package/scripts/vdo-mcp-browser-agent.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Steve Seguin
+// SPDX-License-Identifier: MIT
+'use strict';
+
+const http = require('node:http');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { WebSocketServer } = require('ws');
+const { loadConfig, makeSession } = require('./vdo-mcp-browser');
+const { BrowserRpcClient } = require('./lib/browser-rpc');
+const { BrowserVoiceAgent, MODEL } = require('./lib/browser-agent');
+
+async function startOperator(config, options = {}) {
+  if (config.clients) throw new Error('Use an individual agent JSON file, not worker.json');
+  const token = crypto.randomBytes(32).toString('hex');
+  const session = options.session || makeSession(config, false);
+  const rpc = options.rpc || new BrowserRpcClient(session, config);
+  const assets = path.join(__dirname, '..', 'assets', 'browser-agent');
+  const files = new Map([
+    ['/', [path.join(assets, 'index.html'), 'text/html; charset=utf-8']],
+    ['/client.js', [path.join(assets, 'client.js'), 'text/javascript; charset=utf-8']],
+    ['/audio-worklet.js', [path.join(assets, 'audio-worklet.js'), 'text/javascript; charset=utf-8']],
+    ['/sdk.js', [require.resolve('@vdoninja/sdk/browser'), 'text/javascript; charset=utf-8']]
+  ]);
+  let origin, client, agent, connecting, microphone = false, closed = false;
+  const send = (event) => {
+    if (!client || client.readyState !== 1) return;
+    if (client.bufferedAmount > 4 * 1024 * 1024) { client.close(1013, 'Operator connection too slow'); return; }
+    client.send(JSON.stringify(event));
+  };
+  const ensureWorker = () => {
+    if (!connecting) connecting = session.start().then(() => rpc.connect()).catch((error) => { connecting = null; throw error; });
+    return connecting;
+  };
+  const server = http.createServer((req, res) => {
+    if (req.headers.host !== new URL(origin).host || req.method !== 'GET') { res.writeHead(403); res.end(); return; }
+    const file = files.get(req.url);
+    if (!file) { res.writeHead(404); res.end(); return; }
+    res.writeHead(200, { 'content-type': file[1], 'cache-control': 'no-store', 'referrer-policy': 'no-referrer',
+      'content-security-policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' wss: https:; img-src 'self' data:; media-src 'self' blob:; object-src 'none'; frame-ancestors 'none'" });
+    fs.createReadStream(file[0]).on('error', () => res.destroy()).pipe(res);
+  });
+  const sockets = new Set();
+  server.on('connection', (socket) => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); });
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 100000, perMessageDeflate: false });
+  server.on('upgrade', (req, socket, head) => {
+    let url;
+    try { url = new URL(req.url, origin); } catch (_) { socket.destroy(); return; }
+    if (req.headers.host !== new URL(origin).host || req.headers.origin !== origin || url.pathname !== '/operator' || url.searchParams.get('token') !== token || client) { socket.destroy(); return; }
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws));
+  });
+  wss.on('connection', (ws) => {
+    client = ws;
+    const voice = new BrowserVoiceAgent(rpc, { apiKey: options.apiKey || process.env.OPENAI_API_KEY, model: options.model || process.env.VDON_BROWSER_MODEL || MODEL,
+      emit: (event) => { if (client === ws) send(event); }, connectSocket: options.connectSocket });
+    agent = voice;
+    send({ type: 'hello', worker: config.worker, provider: 'OpenAI', model: agent.model, key_available: !!agent.apiKey, transport: config.connection.transport || 'webrtc' });
+    let commands = Promise.resolve();
+    let count = 0;
+    let commandEpoch = 0;
+    ws.on('message', (raw) => {
+      let event;
+      try { event = JSON.parse(raw.toString()); } catch (_) { return; }
+      if (!event || typeof event.type !== 'string') return;
+      if (event.type === 'audio') { if (microphone) voice.audio(event.data); return; }
+      if (event.type === 'playback') { voice.truncate(event); return; }
+      // Stop and sharing controls take effect immediately, even during a tool call.
+      if (event.type === 'interrupt') { commandEpoch++; voice.interrupt(event); return; }
+      if (event.type === 'stop') { commandEpoch++; microphone = false; voice.stop(); return; }
+      if (event.type === 'permissions') {
+        microphone = !!event.microphone;
+        if (!microphone) voice.send({ type: 'input_audio_buffer.clear' });
+        voice.permissions({ share: event.share, control: event.control });
+        send({ type: 'sharing', microphone, frames: voice.share, control: voice.control, recipient: 'OpenAI' });
+        return;
+      }
+      if (count >= 8) { send({ type: 'error', message: 'Too many pending operator actions' }); return; }
+      count++;
+      const epoch = commandEpoch;
+      commands = commands.then(async () => {
+        if (client !== ws || closed || epoch !== commandEpoch) return;
+        if (event.type === 'start') { await ensureWorker(); if (client === ws && epoch === commandEpoch) await voice.start(); }
+        else if (event.type === 'text') voice.text(event.text);
+        else if (event.type === 'frame') { await ensureWorker(); if (client === ws && epoch === commandEpoch) await voice.captureFrame(); }
+        else if (event.type === 'watch') {
+          await ensureWorker();
+          if (client !== ws || epoch !== commandEpoch) return;
+          const media = await rpc.request('media');
+          if (client === ws && epoch === commandEpoch) send({ type: 'media', ...media });
+        } else if (event.type === 'check') {
+          const hello = await ensureWorker();
+          if (client === ws && epoch === commandEpoch) send({ type: 'worker', ok: true, role: hello.role, route: hello.route });
+        }
+      }).catch((error) => { if (client === ws) send({ type: 'error', message: error.message }); }).finally(() => { count--; });
+    });
+    ws.on('close', () => {
+      commandEpoch++; voice.stop(); microphone = false;
+      if (client === ws) client = null;
+    });
+    ws.on('error', () => {});
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port || 0, '127.0.0.1', resolve); });
+  origin = `http://127.0.0.1:${server.address().port}`;
+  let closePromise;
+  const close = () => {
+    if (!closePromise) closePromise = (async () => {
+      closed = true;
+      if (agent) { await agent.stop(); await agent.toolChain; }
+      if (client) client.terminate();
+      wss.close(); rpc.close();
+      await session.stop();
+      await new Promise((resolve) => { server.close(resolve); for (const socket of sockets) socket.destroy(); });
+    })();
+    return closePromise;
+  };
+  return { url: `${origin}/#${token}`, origin, close, rpc, session };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help')) { console.log('vdon-mcp-browser-agent --config <agent.json>\nOPENAI_API_KEY stays in this local process. Open the printed private loopback URL.'); return; }
+  if (args.length !== 2 || args[0] !== '--config') throw new Error('Use --config <agent.json>');
+  const service = await startOperator(loadConfig(args[1]));
+  console.log(`Open this private operator page on this computer:\n${service.url}`);
+  const shutdown = () => service.close().then(() => process.exit(0), (error) => { console.error(error.message); process.exit(1); });
+  process.once('SIGINT', shutdown); process.once('SIGTERM', shutdown);
+}
+
+if (require.main === module) main().catch((error) => { console.error(error.message); process.exitCode = 1; });
+module.exports = { startOperator };

package/scripts/vdo-mcp-browser.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// 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');
+const { BridgeSession } = require('./lib/bridge-session');
+const { BrowserRpcWorker, BrowserRpcClient, keyBytes } = require('./lib/browser-rpc');
+const { BrowserController, launchBrowser } = require('./lib/browser-worker');
+const { McpStdioParser, writeMcpMessage } = require('./lib/mcp-stdio-parser');
+
+const pageId = { type: 'integer', minimum: 0 };
+const lease = { type: 'string' };
+function tool(name, description, properties, required = []) {
+  return { name, description, inputSchema: { type: 'object', properties, required, additionalProperties: false } };
+}
+const TOOLS = [
+  tool('browser_tabs', 'List remote tabs and current control leases.', {}),
+  tool('browser_media', 'Get live tab audio/video status and private viewer credentials when the host enables media. Use screenshots when WebRTC media is unavailable. Protect the returned viewing link.', {}),
+  tool('browser_observe', 'Read a fresh accessibility snapshot with element UIDs, or a JPEG screenshot. Take a new snapshot after claiming control and after each action.', { pageId, screenshot: { type: 'boolean' } }, ['pageId']),
+  tool('browser_claim', 'Claim one tab for up to 120 seconds. Pass the current lease to renew it. Other agents may observe while you control.', { pageId, ttl_ms: { type: 'integer', minimum: 1000, maximum: 120000 }, lease }, ['pageId']),
+  tool('browser_release', 'Release a tab for another controller.', { pageId, lease }, ['pageId', 'lease']),
+  tool('browser_call', 'Navigate, click, fill, or press a page key. Requires a tab lease; input actions also require a fresh snapshot token. Never repeat an uncertain action before reconciling its result.', {
+    pageId, lease, snapshot: { type: 'string' }, action: { type: 'string', enum: ['navigate', 'click', 'fill', 'key'] },
+    url: { type: 'string' }, uid: { type: 'string' }, value: { type: 'string' }, key: { type: 'string' }
+  }, ['pageId', 'lease', 'action']),
+  tool('browser_result', 'Look up a recent request by its request_id. Unknown is not evidence that an action did not execute; inspect the page before deciding what to do next.', { request_id: { type: 'string' } }, ['request_id'])
+];
+
+function loadConfig(file) {
+  if (!file) throw new Error('Use --config <file>, or set VDON_BROWSER_CONFIG. Run --init <directory> to create credentials.');
+  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (!/^[a-zA-Z0-9_-]{1,80}$/.test(config.worker || '')) throw new Error('Invalid worker ID');
+  if (!config.connection || !/^[a-zA-Z0-9_-]{1,128}$/.test(config.connection.room || '')) throw new Error('A connection.room is required');
+  if (config.clients) {
+    if (!Object.keys(config.clients).length || Object.keys(config.clients).length > 32) throw new Error('Configure 1 to 32 browser clients');
+    const keys = new Set();
+    for (const [id, value] of Object.entries(config.clients)) {
+      if (!/^[a-zA-Z0-9_-]{1,80}$/.test(id) || !['controller', 'observer'].includes(value.role)) throw new Error('Invalid browser client');
+      keyBytes(value.key);
+      if (keys.has(value.key.toLowerCase())) throw new Error('Each browser client needs a unique key');
+      keys.add(value.key.toLowerCase());
+    }
+  } else {
+    if (!/^[a-zA-Z0-9_-]{1,80}$/.test(config.client || '')) throw new Error('Invalid browser client ID');
+    keyBytes(config.key);
+  }
+  return config;
+}
+
+function makeSession(config, worker) {
+  const sessionConfig = {
+    ...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,
+    streamID: worker ? config.worker : `${config.client}_${crypto.randomBytes(6).toString('hex')}`,
+    targetStreamID: worker ? null : config.worker,
+    maxQueueSize: 32
+  };
+  if (sessionConfig.transport === 'auto') {
+    const { BrowserRoutes } = require('./lib/browser-routes');
+    return new BrowserRoutes(sessionConfig);
+  }
+  return new BridgeSession(sessionConfig);
+}
+
+function initConfigs(directory) {
+  fs.mkdirSync(directory, { recursive: true });
+  const connection = { room: `browser_${crypto.randomBytes(12).toString('hex')}`, transport: 'webrtc' };
+  const worker = `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 }]);
+  }
+  files.push(['worker.json', { worker, clients, connection }]);
+  for (const [file] of files) if (fs.existsSync(path.join(directory, file))) throw new Error(`${file} already exists; choose a new directory`);
+  for (const [file, value] of files) fs.writeFileSync(path.join(directory, file), JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  process.stderr.write(`Created worker.json, agent1.json, agent2.json, and viewer.json in ${path.resolve(directory)}. Keep these credentials private.\n`);
+}
+
+async function startWorker(config) {
+  if (!config.clients) throw new Error('Worker mode requires worker.json');
+  const session = makeSession(config, true);
+  const runtime = await launchBrowser(config);
+  const controller = new BrowserController(runtime.backend, runtime.pages);
+  runtime.target.on('framenavigated', (frame) => { if (frame === runtime.target.mainFrame()) controller.invalidate(runtime.pages[0]); });
+  const rpc = new BrowserRpcWorker(session, config, (client, role, op, args) => {
+    if (op === 'media') return runtime.mediaStatus();
+    return controller.execute(client, role, op, args);
+  });
+  let closePromise;
+  const close = () => {
+    if (!closePromise) closePromise = (async () => {
+      rpc.close();
+      try { await session.stop(); } finally { await runtime.close(); }
+    })();
+    return closePromise;
+  };
+  try { await session.start(); } catch (error) { await close(); throw error; }
+  return { session, rpc, controller, runtime, close };
+}
+
+async function startClient(config, input = process.stdin, output = process.stdout) {
+  if (config.clients) throw new Error('Client mode requires an individual agent credential file');
+  const session = makeSession(config, false);
+  const rpc = new BrowserRpcClient(session, config);
+  const parser = new McpStdioParser({ maxMessageBytes: 65536 });
+  let connecting;
+  let closed = false;
+  let closePromise;
+  let inFlight = 0;
+  const close = () => {
+    if (!closePromise) {
+      closed = true;
+      rpc.close();
+      closePromise = session.stop();
+    }
+    return closePromise;
+  };
+  const dispatch = async (message, mode) => {
+    if (closed) return;
+    if (!message || message.jsonrpc !== '2.0' || typeof message.method !== 'string') return;
+    if (message.id === undefined) return;
+    const reply = (value) => writeMcpMessage(output, { jsonrpc: '2.0', id: message.id, ...value }, mode);
+    if (inFlight >= 16) return reply({ error: { code: -32000, message: 'Too many pending requests' } });
+    inFlight++;
+    try {
+      let result;
+      if (message.method === 'initialize') result = { protocolVersion: '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'ninja-browser', version: '0.4.2' } };
+      else if (message.method === 'ping') result = {};
+      else if (message.method === 'tools/list') result = { tools: TOOLS };
+      else if (message.method === 'tools/call') {
+        const { name, arguments: args = {} } = message.params || {};
+        const definition = TOOLS.find((entry) => entry.name === name);
+        if (!definition) throw new Error('Unknown browser tool');
+        if (!connecting) connecting = session.start().then(() => rpc.connect()).catch((error) => { connecting = null; throw error; });
+        await connecting;
+        const response = await rpc.request(name.slice('browser_'.length), args);
+        const { result: contentResult, ...metadata } = response;
+        const hasContent = contentResult && Array.isArray(contentResult.content);
+        result = { content: [{ type: 'text', text: JSON.stringify(hasContent ? metadata : response) }, ...(hasContent ? contentResult.content : [])],
+          isError: !!response.error || !!(contentResult && contentResult.isError) };
+      } else return reply({ error: { code: -32601, message: 'Method not found' } });
+      reply({ result });
+    } catch (error) { reply({ result: { isError: true, content: [{ type: 'text', text: error.message }] } }); }
+    finally { inFlight--; }
+  };
+  parser.on('message', ({ message, mode }) => { dispatch(message, mode).catch(() => {}); });
+  parser.on('error', () => writeMcpMessage(output, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Invalid MCP request' } }, parser.mode));
+  input.on('data', (chunk) => { parser.push(chunk); if (parser.buffer.length > 65536) { parser.buffer = Buffer.alloc(0); close().catch(() => {}); } });
+  input.on('end', () => { close().catch(() => {}); });
+  input.on('close', () => { close().catch(() => {}); });
+  return { session, rpc, close };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args[0] === '--init' && args.length === 2) return initConfigs(args[1]);
+  if (args[0] === '--setup') {
+    const directory = args[1];
+    if (!directory || directory.startsWith('--')) throw new Error('--setup requires a private directory');
+    const options = {};
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--media') options.media = true;
+      else if (args[i] === '--transport' && args[i + 1]) options.transport = args[++i];
+      else if (args[i] === '--relay-config' && args[i + 1]) options.relayConfig = args[++i];
+      else throw new Error(`Unknown setup option: ${args[i]}`);
+    }
+    return require('./lib/browser-setup').guidedSetup(directory, options);
+  }
+  const diagnostic = args[0] === '--doctor';
+  if (diagnostic) args.shift();
+  const worker = args[0] === '--worker';
+  if (worker) args.shift();
+  if (args.includes('--help')) {
+    process.stdout.write('vdon-mcp-browser --setup <private-directory> [--transport webrtc|http|auto] [--relay-config <relay.json>] [--media]\nvdon-mcp-browser --doctor --config <worker-or-agent.json>\nvdon-mcp-browser --worker --config <worker.json>\nvdon-mcp-browser --config <agent1.json>\n');
+    return;
+  }
+  if (args.length && (args.length !== 2 || args[0] !== '--config')) throw new Error('Expected --config <file>');
+  const config = loadConfig(args[1] || process.env.VDON_BROWSER_CONFIG);
+  if (diagnostic) {
+    const result = await require('./lib/browser-setup').doctor(config, makeSession);
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n', () => process.exit(result.ok ? 0 : 1));
+    return;
+  }
+  const service = worker ? await startWorker(config) : await startClient(config);
+  const shutdown = () => service.close().then(() => process.exit(0), (error) => { process.stderr.write(error.message + '\n'); process.exit(1); });
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  if (!worker) {
+    process.stdin.once('end', shutdown);
+    process.stdin.once('close', shutdown);
+  }
+  if (worker) {
+    process.stderr.write(`Browser worker ${config.worker} is running over ${config.connection.transport || 'webrtc'}. Enter "revoke <pageId>" to revoke a tab lease; "stop" or Ctrl+C stops the browser.\n`);
+    {
+      const terminal = readline.createInterface({ input: process.stdin });
+      terminal.on('line', (line) => {
+        const match = /^revoke (\d+)$/.exec(line.trim());
+        if (match) { service.controller.revoke(Number(match[1])); process.stderr.write('Lease revoked. An action already executing may finish.\n'); }
+        if (line.trim() === 'stop') { terminal.close(); shutdown(); }
+      });
+      terminal.on('SIGINT', () => { terminal.close(); shutdown(); });
+      process.once('SIGINT', () => terminal.close());
+      process.once('SIGTERM', () => terminal.close());
+    }
+  }
+}
+
+if (require.main === module) main().catch((error) => { process.stderr.write(error.message + '\n'); process.exitCode = 1; });
+module.exports = { TOOLS, loadConfig, makeSession, initConfigs, startWorker, startClient };