@mobileaidev/ai-app-bridge 0.2.9 → 0.2.10

package/bin/mcp-server.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
-const { spawn } = require('child_process');
-const path = require('path');
-
-const packageInfo = require('../package.json');
-const bridgeDir = __dirname;
-const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
-const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
+const { spawn } = require('child_process');
+const path = require('path');
+
+const packageInfo = require('../package.json');
+const { WebBridgeProvider } = require('./web-provider');
+const bridgeDir = __dirname;
+const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
+const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
 const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
 const defaultProtocolVersion = supportedProtocolVersions[0];
 const mcpSurface = (process.env.AI_APP_BRIDGE_MCP_SURFACE || 'compact').toLowerCase();
@@ -16,6 +17,7 @@ const serverInstructions = [
   'Always pass packageName for app-specific commands, or pass an explicit port. Do not rely on a sample/default package in MCP sessions.',
   'Use freeze-app/thaw-app only as an optional stabilization control for dynamic or transient screens: thaw before reads/actions/captures, freeze after evidence capture only when it helps reasoning, and thaw before the next operation or before finishing so the app is not left frozen.',
 ].join(' ');
+const webProvider = new WebBridgeProvider();
 
 let buffer = Buffer.alloc(0);
 let responseFormat = null;
@@ -498,8 +500,23 @@ const commandDefinitions = [
   { command: 'flutter-h5-scroll', domain: 'webview', summary: 'Scroll Flutter H5 content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
   { command: 'webview-pages', domain: 'webview', summary: 'List attachable Android WebView DevTools/CDP pages.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'keepForward'] },
   { command: 'webview-network', domain: 'webview', summary: 'Capture WebView Network events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'urlFilter', 'durationMs', 'script', 'includeResponseBody', 'bodyMaxBytes', 'maxEvents'] },
-  { command: 'webview-console', domain: 'webview', summary: 'Capture WebView console/log events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'durationMs', 'script', 'maxEvents'] },
-  { command: 'forward', domain: 'advanced', summary: 'Create the ADB port forward for the bridge.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'webview-console', domain: 'webview', summary: 'Capture WebView console/log events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'durationMs', 'script', 'maxEvents'] },
+  { command: 'web-provider-status', domain: 'web', summary: 'Read desktop Web Bridge provider status.', options: [] },
+  { command: 'web-session-start', domain: 'web', summary: 'Start the desktop Web Bridge WebSocket session server.', options: ['host', 'webPort', 'path', 'token'] },
+  { command: 'web-connect-info', domain: 'web', summary: 'Read the Web Bridge endpoint and token for SDK clients.', options: [] },
+  { command: 'web-sessions', domain: 'web', summary: 'List connected Web Bridge SDK sessions.', options: [] },
+  { command: 'web-status', domain: 'web', summary: 'Read status and capture counts for a Web Bridge session.', targetKind: 'web-target', options: ['sessionId'] },
+  { command: 'web-dom', domain: 'web', summary: 'Read or refresh a Web Bridge DOM snapshot.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'refresh', 'timeoutMs'] },
+  { command: 'web-logs', domain: 'web', summary: 'Read Web Bridge log records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'web-network', domain: 'web', summary: 'Read Web Bridge network records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'web-state', domain: 'web', summary: 'Read Web Bridge state records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'web-events', domain: 'web', summary: 'Read Web Bridge event records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'web-command', domain: 'web', summary: 'Run a whitelisted command in a connected Web Bridge SDK session.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'name', 'arguments', 'timeoutMs'] },
+  { command: 'web-click', domain: 'web', summary: 'Click a DOM element through the Web Bridge SDK command path.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'targetText', 'timeoutMs'] },
+  { command: 'web-input', domain: 'web', summary: 'Set text in a DOM input through the Web Bridge SDK command path.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'value', 'timeoutMs'] },
+  { command: 'web-wait', domain: 'web', summary: 'Wait for text or selector through the Web Bridge SDK command path.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'targetText', 'timeoutMs'] },
+  { command: 'web-scroll', domain: 'web', summary: 'Scroll a Web Bridge DOM target.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'deltaX', 'deltaY', 'timeoutMs'] },
+  { command: 'forward', domain: 'advanced', summary: 'Create the ADB port forward for the bridge.', targetApp: true, options: ['serial', 'packageName', 'port'] },
   { command: 'remove-forward', domain: 'advanced', summary: 'Remove the ADB port forward for the bridge.', options: ['serial', 'port'] },
   { command: 'batch', domain: 'advanced', summary: 'Run multiple AI App Bridge commands serially in one MCP call.', options: ['defaults', 'steps', 'stopOnError', 'includeRaw', 'maxRawChars'] },
   { command: 'smoke', domain: 'diagnostics', summary: 'Run the native sample smoke test.', options: ['serial', 'packageName', 'outFile', 'artifactDir', 'skipFlutterLaunch'] },
@@ -589,14 +606,15 @@ function capabilityPayload(args = {}) {
   };
 }
 
-function shapeCommandDefinition(definition, includeOptions) {
-  return {
-    command: definition.command,
-    summary: definition.summary,
-    targetApp: Boolean(definition.targetApp),
-    ...(includeOptions ? { options: definition.options || [] } : {}),
-  };
-}
+function shapeCommandDefinition(definition, includeOptions) {
+  return {
+    command: definition.command,
+    summary: definition.summary,
+    targetApp: Boolean(definition.targetApp),
+    targetKind: definition.targetKind || (definition.targetApp ? 'android-app' : 'none'),
+    ...(includeOptions ? { options: definition.options || [] } : {}),
+  };
+}
 
 async function runGeneric(args = {}) {
   const command = normalizeCommandName(args.command);
@@ -606,10 +624,10 @@ async function runGeneric(args = {}) {
   const commandArgs = {
     ...(args.arguments && typeof args.arguments === 'object' ? args.arguments : {}),
   };
-  for (const key of ['adb', 'serial', 'port', 'packageName']) {
-    if (args[key] !== undefined && commandArgs[key] === undefined) {
-      commandArgs[key] = args[key];
-    }
+  for (const key of ['adb', 'serial', 'port', 'packageName', 'sessionId', 'targetId', 'webPort']) {
+    if (args[key] !== undefined && commandArgs[key] === undefined) {
+      commandArgs[key] = args[key];
+    }
   }
   if (command === 'batch') {
     return runBatch(commandArgs);
@@ -621,19 +639,27 @@ function normalizeCommandName(value) {
   return String(value || '').trim().replace(/_/g, '-');
 }
 
-function runBridgeChecked(command, args = {}) {
-  if (command === 'clear-app-data' && !args.packageName) {
-    return toolText('clear-app-data: packageName is required in MCP mode so the command cannot clear a default package.', true);
-  }
+function runBridgeChecked(command, args = {}) {
+  const definition = commandByName.get(command);
+  if (definition?.domain === 'web') {
+    return runWebChecked(command, args);
+  }
+  if (command === 'clear-app-data' && !args.packageName) {
+    return toolText('clear-app-data: packageName is required in MCP mode so the command cannot clear a default package.', true);
+  }
   if ((command === 'freeze-app' || command === 'thaw-app') && !args.packageName) {
     return toolText(`${command}: packageName is required in MCP mode so the command cannot signal a default package.`, true);
   }
-  const definition = commandByName.get(command);
-  if (definition?.targetApp && !args.packageName && !args.port) {
-    return toolText(`${command}: packageName or explicit port is required in MCP mode so the command cannot fall back to a default package.`, true);
-  }
-  return runBridge(command, args);
-}
+  if (definition?.targetApp && !args.packageName && !args.port) {
+    return toolText(`${command}: packageName or explicit port is required in MCP mode so the command cannot fall back to a default package.`, true);
+  }
+  return runBridge(command, args);
+}
+
+async function runWebChecked(command, args = {}) {
+  const result = await webProvider.run(command, args);
+  return toolJson(result, result?.ok === false);
+}
 
 async function runBatch(args = {}, runner = runBridgeChecked) {
   const startedAtMs = Date.now();
@@ -654,10 +680,10 @@ async function runBatch(args = {}, runner = runBridgeChecked) {
   }
 
   const defaults = args.defaults && typeof args.defaults === 'object' ? { ...args.defaults } : {};
-  for (const key of ['adb', 'serial', 'port', 'packageName', 'artifactDir']) {
-    if (args[key] !== undefined && defaults[key] === undefined) {
-      defaults[key] = args[key];
-    }
+  for (const key of ['adb', 'serial', 'port', 'packageName', 'artifactDir', 'sessionId', 'targetId', 'webPort']) {
+    if (args[key] !== undefined && defaults[key] === undefined) {
+      defaults[key] = args[key];
+    }
   }
 
   const normalizedSteps = [];
@@ -706,10 +732,10 @@ async function runBatch(args = {}, runner = runBridgeChecked) {
       ...defaults,
       ...(step.arguments && typeof step.arguments === 'object' ? step.arguments : {}),
     };
-    for (const key of ['adb', 'serial', 'port', 'packageName']) {
-      if (step[key] !== undefined) {
-        stepArgs[key] = step[key];
-      }
+    for (const key of ['adb', 'serial', 'port', 'packageName', 'sessionId', 'targetId', 'webPort']) {
+      if (step[key] !== undefined) {
+        stepArgs[key] = step[key];
+      }
     }
     try {
       const toolResult = await runner(step.command, stepArgs);
@@ -717,11 +743,13 @@ async function runBatch(args = {}, runner = runBridgeChecked) {
       const passed = !parsed.isError && parsed.payload?.ok !== false;
       const stepResult = {
         id: step.id,
-        command: step.command,
-        status: passed ? 'passed' : 'failed',
-        ok: passed,
-        packageName: stepArgs.packageName,
-        port: stepArgs.port,
+        command: step.command,
+        status: passed ? 'passed' : 'failed',
+        ok: passed,
+        packageName: stepArgs.packageName,
+        sessionId: stepArgs.sessionId,
+        targetId: stepArgs.targetId,
+        port: stepArgs.port,
         durationMs: Date.now() - stepStartedAtMs,
         summary: summarizeToolPayload(parsed),
       };
@@ -801,8 +829,11 @@ function summarizeToolPayload(parsed) {
     ok: payload.ok,
     error: payload.error || null,
   };
-  if (payload.packageName) summary.packageName = payload.packageName;
-  if (payload.app?.packageName) summary.app = payload.app.packageName;
+  if (payload.packageName) summary.packageName = payload.packageName;
+  if (payload.sessionId) summary.sessionId = payload.sessionId;
+  if (payload.targetId) summary.targetId = payload.targetId;
+  if (payload.session?.sessionId) summary.sessionId = payload.session.sessionId;
+  if (payload.app?.packageName) summary.app = payload.app.packageName;
   if (payload.activity) summary.activity = payload.activity;
   if (payload.component) summary.component = payload.component;
   if (payload.transport) summary.transport = payload.transport;
@@ -814,8 +845,9 @@ function summarizeToolPayload(parsed) {
       port: payload.debugBridge.port,
     };
   }
-  if (payload.count !== undefined) summary.count = payload.count;
-  if (payload.nodeCount !== undefined) summary.nodeCount = payload.nodeCount;
+  if (payload.count !== undefined) summary.count = payload.count;
+  if (payload.sessionCount !== undefined) summary.sessionCount = payload.sessionCount;
+  if (payload.nodeCount !== undefined) summary.nodeCount = payload.nodeCount;
   if (Array.isArray(payload.items)) summary.items = payload.items.length;
   if (payload.values && typeof payload.values === 'object') {
     summary.values = Object.keys(payload.values).length;

package/bin/web-provider.js

@@ -0,0 +1,618 @@
+const crypto = require('crypto');
+const http = require('http');
+const { URL } = require('url');
+const { WebSocketServer } = require('ws');
+
+const defaultHost = '127.0.0.1';
+const defaultPort = 18180;
+const defaultPath = '/ai-app-bridge-web';
+const maxCaptureEntries = 500;
+const defaultCommandTimeoutMs = 5000;
+
+class WebBridgeProvider {
+  constructor() {
+    this.server = null;
+    this.wss = null;
+    this.host = defaultHost;
+    this.port = defaultPort;
+    this.path = defaultPath;
+    this.token = '';
+    this.sessions = new Map();
+    this.pendingCommands = new Map();
+    this.captureSequence = 0;
+  }
+
+  async run(command, args = {}) {
+    switch (command) {
+      case 'web-provider-status':
+        return this.providerStatus();
+      case 'web-session-start':
+        return this.start(args);
+      case 'web-connect-info':
+        return this.connectInfo();
+      case 'web-sessions':
+        return this.listSessions();
+      case 'web-status':
+        return this.sessionStatus(args);
+      case 'web-dom':
+        return this.dom(args);
+      case 'web-logs':
+        return this.captureResponse(args, 'logs');
+      case 'web-network':
+        return this.captureResponse(args, 'network');
+      case 'web-state':
+        return this.stateResponse(args);
+      case 'web-events':
+        return this.captureResponse(args, 'events');
+      case 'web-command':
+        return this.command(args);
+      case 'web-click':
+        return this.command({ ...args, name: 'click' });
+      case 'web-input':
+        return this.command({ ...args, name: 'input' });
+      case 'web-wait':
+        return this.command({ ...args, name: 'waitFor' });
+      case 'web-scroll':
+        return this.command({ ...args, name: 'scroll' });
+      default:
+        return { ok: false, error: 'unknown_web_command', command };
+    }
+  }
+
+  async start(args = {}) {
+    if (this.server) {
+      return { ok: true, alreadyRunning: true, ...this.connectInfo() };
+    }
+
+    this.host = stringArg(args.host, defaultHost);
+    this.port = numberArg(args.webPort, numberArg(args.port, defaultPort));
+    this.path = stringArg(args.path, defaultPath);
+    this.token = stringArg(args.token, randomToken());
+
+    this.server = http.createServer((request, response) => this.handleHttp(request, response));
+    this.wss = new WebSocketServer({ server: this.server });
+    this.wss.on('connection', (socket, request) => this.handleConnection(socket, request));
+
+    await new Promise((resolve, reject) => {
+      const onError = (error) => {
+        this.server = null;
+        this.wss = null;
+        reject(error);
+      };
+      this.server.once('error', onError);
+      this.server.listen(this.port, this.host, () => {
+        this.server.off('error', onError);
+        const address = this.server.address();
+        this.port = typeof address === 'object' && address ? address.port : this.port;
+        resolve();
+      });
+    });
+
+    return { ok: true, started: true, ...this.connectInfo() };
+  }
+
+  providerStatus() {
+    return {
+      ok: true,
+      running: Boolean(this.server),
+      host: this.host,
+      port: this.server ? this.port : null,
+      path: this.path,
+      sessionCount: this.sessions.size,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  connectInfo() {
+    if (!this.server) {
+      return {
+        ok: false,
+        running: false,
+        error: 'web_provider_not_running',
+        suggestion: 'Run web-session-start first.',
+      };
+    }
+    const endpoint = `ws://${this.host}:${this.port}${this.path}`;
+    return {
+      ok: true,
+      running: true,
+      endpoint,
+      httpEndpoint: `http://${this.host}:${this.port}`,
+      token: this.token,
+      sessionCount: this.sessions.size,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  listSessions() {
+    return {
+      ok: true,
+      running: Boolean(this.server),
+      sessions: [...this.sessions.values()].map((session) => this.sessionSummary(session)),
+      count: this.sessions.size,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  sessionStatus(args = {}) {
+    const session = this.requireSession(args);
+    if (!session.ok) return session;
+    return {
+      ok: true,
+      session: this.sessionSummary(session.value),
+      capture: captureCounts(session.value),
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  async dom(args = {}) {
+    const sessionResult = this.requireSession(args);
+    if (!sessionResult.ok) return sessionResult;
+    const session = sessionResult.value;
+    const targetId = stringArg(args.targetId, 'main');
+    const refresh = args.refresh !== false;
+    if (refresh && session.socket?.readyState === 1) {
+      try {
+        const result = await this.sendCommand(session, {
+          name: 'domSnapshot',
+          targetId,
+          args: {
+            selector: args.selector,
+            maxControls: args.maxControls,
+          },
+        }, numberArg(args.timeoutMs, defaultCommandTimeoutMs));
+        const dom = result.dom || result.value || result;
+        if (dom && typeof dom === 'object') {
+          session.domByTarget.set(targetId, { ...dom, targetId, updatedAtMs: Date.now() });
+        }
+      } catch (error) {
+        if (!session.domByTarget.has(targetId)) {
+          return { ok: false, error: 'web_dom_unavailable', message: error.message };
+        }
+      }
+    }
+    const dom = session.domByTarget.get(targetId);
+    if (!dom) {
+      return { ok: false, error: 'web_dom_absent', sessionId: session.sessionId, targetId };
+    }
+    return {
+      ok: true,
+      sessionId: session.sessionId,
+      targetId,
+      dom,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  captureResponse(args = {}, stream) {
+    const sessionResult = this.requireSession(args);
+    if (!sessionResult.ok) return sessionResult;
+    const session = sessionResult.value;
+    const filter = captureFilter(args);
+    const source = session.captures[stream] || [];
+    const filtered = source.filter((item) => captureMatches(item, filter));
+    const items = filtered.length > filter.limit ? filtered.slice(-filter.limit) : filtered;
+    return {
+      ok: true,
+      type: stream,
+      sessionId: session.sessionId,
+      items: items.map((item) => ({ ...item })),
+      count: items.length,
+      sinceId: filter.sinceId ?? null,
+      sinceMs: filter.sinceMs ?? null,
+      limit: filter.limit,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  stateResponse(args = {}) {
+    const sessionResult = this.requireSession(args);
+    if (!sessionResult.ok) return sessionResult;
+    const session = sessionResult.value;
+    const filter = captureFilter(args);
+    const values = {};
+    const items = [];
+    for (const [key, item] of session.stateEntries.entries()) {
+      if (!captureMatches(item, filter)) continue;
+      values[key] = item.value;
+      items.push({ ...item });
+    }
+    const limited = items.length > filter.limit ? items.slice(-filter.limit) : items;
+    return {
+      ok: true,
+      type: 'state',
+      sessionId: session.sessionId,
+      values,
+      items: limited,
+      count: limited.length,
+      sinceId: filter.sinceId ?? null,
+      sinceMs: filter.sinceMs ?? null,
+      limit: filter.limit,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  async command(args = {}) {
+    const sessionResult = this.requireSession(args);
+    if (!sessionResult.ok) return sessionResult;
+    const session = sessionResult.value;
+    const name = stringArg(args.name || args.action || args.webCommand, '');
+    if (!name) {
+      return { ok: false, error: 'web_command_name_required' };
+    }
+    try {
+      const result = await this.sendCommand(session, {
+        name,
+        targetId: stringArg(args.targetId, 'main'),
+        args: args.arguments && typeof args.arguments === 'object' ? args.arguments : commandArgs(args),
+      }, numberArg(args.timeoutMs, defaultCommandTimeoutMs));
+      return {
+        ok: result.ok !== false,
+        sessionId: session.sessionId,
+        targetId: stringArg(args.targetId, 'main'),
+        command: name,
+        result,
+        updatedAtMs: Date.now(),
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: 'web_command_failed',
+        message: error.message,
+        sessionId: session.sessionId,
+        command: name,
+      };
+    }
+  }
+
+  sendCommand(session, command, timeoutMs) {
+    if (!session.socket || session.socket.readyState !== 1) {
+      return Promise.reject(new Error('web_session_not_connected'));
+    }
+    const commandId = `web-command-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const payload = {
+      type: 'command',
+      commandId,
+      command,
+      sentAtMs: Date.now(),
+    };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingCommands.delete(commandId);
+        reject(new Error('web_command_timeout'));
+      }, timeoutMs);
+      this.pendingCommands.set(commandId, {
+        sessionId: session.sessionId,
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      session.socket.send(JSON.stringify(payload), (error) => {
+        if (!error) return;
+        const pending = this.pendingCommands.get(commandId);
+        this.pendingCommands.delete(commandId);
+        if (pending) {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  handleHttp(request, response) {
+    setCors(response);
+    if (request.method === 'OPTIONS') {
+      response.writeHead(204);
+      response.end();
+      return;
+    }
+    if (request.method === 'GET' && request.url?.startsWith('/health')) {
+      writeJson(response, this.providerStatus());
+      return;
+    }
+    if (request.method === 'GET' && request.url?.startsWith('/sessions')) {
+      writeJson(response, this.listSessions());
+      return;
+    }
+    writeJson(response, { ok: false, error: 'not_found' }, 404);
+  }
+
+  handleConnection(socket, request) {
+    const parsed = new URL(request.url || '/', `http://${this.host}:${this.port}`);
+    if (parsed.pathname !== this.path) {
+      socket.close(1008, 'invalid_path');
+      return;
+    }
+    if (this.token && parsed.searchParams.get('token') !== this.token) {
+      socket.close(1008, 'invalid_token');
+      return;
+    }
+
+    socket.on('message', (raw) => this.handleSocketMessage(socket, raw));
+    socket.on('close', () => this.markSocketClosed(socket));
+    socket.on('error', () => this.markSocketClosed(socket));
+  }
+
+  handleSocketMessage(socket, raw) {
+    let message;
+    try {
+      message = JSON.parse(raw.toString());
+    } catch (_) {
+      socket.send(JSON.stringify({ type: 'error', error: 'invalid_json' }));
+      return;
+    }
+    switch (message.type) {
+      case 'hello':
+        this.registerSession(socket, message);
+        break;
+      case 'capture':
+        this.recordCapture(socket, message);
+        break;
+      case 'dom':
+        this.recordDom(socket, message);
+        break;
+      case 'commandResult':
+        this.resolveCommand(socket, message);
+        break;
+      case 'heartbeat':
+        this.touchSession(socket);
+        break;
+      default:
+        socket.send(JSON.stringify({ type: 'error', error: 'unknown_message_type', messageType: message.type || '' }));
+        break;
+    }
+  }
+
+  registerSession(socket, message) {
+    const sessionId = stringArg(message.sessionId, `web-session-${randomToken(6)}`);
+    const targetId = stringArg(message.targetId, 'main');
+    const existing = this.sessions.get(sessionId);
+    const session = existing || createSession(sessionId);
+    session.socket = socket;
+    session.connected = true;
+    session.appName = stringArg(message.appName, session.appName || '');
+    session.url = stringArg(message.url, session.url || '');
+    session.origin = stringArg(message.origin, session.origin || '');
+    session.route = stringArg(message.route, session.route || '');
+    session.capabilities = message.capabilities && typeof message.capabilities === 'object' ? message.capabilities : session.capabilities;
+    session.targets.set(targetId, {
+      targetId,
+      url: session.url,
+      origin: session.origin,
+      updatedAtMs: Date.now(),
+    });
+    session.updatedAtMs = Date.now();
+    socket.aiAppBridgeSessionId = sessionId;
+    this.sessions.set(sessionId, session);
+    socket.send(JSON.stringify({
+      type: 'helloAck',
+      ok: true,
+      sessionId,
+      targetId,
+      serverTimeMs: Date.now(),
+    }));
+  }
+
+  recordCapture(socket, message) {
+    const session = this.sessionForSocket(socket);
+    if (!session) return;
+    const stream = normalizeStream(message.stream || message.typeName);
+    if (!stream) return;
+    const rawItem = message.item || message.record || {};
+    const item = this.baseRecord(stream, session, rawItem);
+    if (stream === 'state') {
+      const namespace = stringArg(item.namespace, 'app');
+      const key = stringArg(item.key, 'value');
+      item.namespace = namespace;
+      item.key = key;
+      session.stateEntries.set(`${namespace}.${key}`, item);
+    } else {
+      boundedPush(session.captures[stream], item, maxCaptureEntries);
+    }
+    session.updatedAtMs = Date.now();
+  }
+
+  recordDom(socket, message) {
+    const session = this.sessionForSocket(socket);
+    if (!session) return;
+    const targetId = stringArg(message.targetId, 'main');
+    const dom = message.dom && typeof message.dom === 'object' ? message.dom : message;
+    session.domByTarget.set(targetId, {
+      ...dom,
+      targetId,
+      sessionId: session.sessionId,
+      updatedAtMs: Date.now(),
+    });
+    session.updatedAtMs = Date.now();
+  }
+
+  resolveCommand(socket, message) {
+    const pending = this.pendingCommands.get(message.commandId);
+    if (!pending) return;
+    const session = this.sessionForSocket(socket);
+    if (!session || session.sessionId !== pending.sessionId) {
+      pending.reject(new Error('web_command_session_mismatch'));
+      this.pendingCommands.delete(message.commandId);
+      return;
+    }
+    this.pendingCommands.delete(message.commandId);
+    if (message.ok === false) {
+      pending.resolve({
+        ok: false,
+        error: message.error || 'web_command_error',
+        value: message.value,
+      });
+      return;
+    }
+    pending.resolve(message.result !== undefined ? message.result : { ok: true, value: message.value });
+  }
+
+  baseRecord(stream, session, rawItem) {
+    const type = stream === 'logs' ? 'log' : stream === 'events' ? 'event' : stream;
+    return {
+      id: ++this.captureSequence,
+      type,
+      source: stringArg(rawItem.source, 'web-sdk'),
+      timestampMs: numberArg(rawItem.timestampMs, Date.now()),
+      sessionId: session.sessionId,
+      targetId: stringArg(rawItem.targetId, 'main'),
+      ...rawItem,
+    };
+  }
+
+  requireSession(args = {}) {
+    if (!this.server) {
+      return { ok: false, error: 'web_provider_not_running', suggestion: 'Run web-session-start first.' };
+    }
+    const sessionId = stringArg(args.sessionId, '');
+    if (sessionId) {
+      const session = this.sessions.get(sessionId);
+      if (!session) return { ok: false, error: 'web_session_not_found', sessionId };
+      return { ok: true, value: session };
+    }
+    const live = [...this.sessions.values()].filter((session) => session.connected);
+    if (live.length === 1) return { ok: true, value: live[0] };
+    return {
+      ok: false,
+      error: live.length === 0 ? 'web_session_required' : 'web_session_ambiguous',
+      sessions: live.map((session) => this.sessionSummary(session)),
+    };
+  }
+
+  sessionForSocket(socket) {
+    const sessionId = socket.aiAppBridgeSessionId;
+    return sessionId ? this.sessions.get(sessionId) : null;
+  }
+
+  touchSession(socket) {
+    const session = this.sessionForSocket(socket);
+    if (session) session.updatedAtMs = Date.now();
+  }
+
+  markSocketClosed(socket) {
+    const session = this.sessionForSocket(socket);
+    if (!session || session.socket !== socket) return;
+    session.connected = false;
+    session.socket = null;
+    session.updatedAtMs = Date.now();
+  }
+
+  sessionSummary(session) {
+    return {
+      sessionId: session.sessionId,
+      appName: session.appName,
+      connected: session.connected,
+      url: session.url,
+      origin: session.origin,
+      route: session.route,
+      capabilities: session.capabilities,
+      targets: [...session.targets.values()],
+      capture: captureCounts(session),
+      connectedAtMs: session.connectedAtMs,
+      updatedAtMs: session.updatedAtMs,
+    };
+  }
+}
+
+function createSession(sessionId) {
+  return {
+    sessionId,
+    appName: '',
+    connected: false,
+    socket: null,
+    url: '',
+    origin: '',
+    route: '',
+    capabilities: {},
+    targets: new Map(),
+    captures: {
+      logs: [],
+      network: [],
+      events: [],
+    },
+    stateEntries: new Map(),
+    domByTarget: new Map(),
+    connectedAtMs: Date.now(),
+    updatedAtMs: Date.now(),
+  };
+}
+
+function commandArgs(args) {
+  const omitted = new Set(['sessionId', 'targetId', 'name', 'action', 'webCommand', 'timeoutMs']);
+  const result = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!omitted.has(key)) result[key] = value;
+  }
+  return result;
+}
+
+function captureCounts(session) {
+  return {
+    logs: session.captures.logs.length,
+    network: session.captures.network.length,
+    state: session.stateEntries.size,
+    events: session.captures.events.length,
+    dom: session.domByTarget.size,
+  };
+}
+
+function captureFilter(args = {}) {
+  return {
+    sinceId: args.sinceId === undefined ? null : Number(args.sinceId),
+    sinceMs: args.sinceMs === undefined ? null : Number(args.sinceMs),
+    limit: Number.isInteger(Number(args.limit)) ? Math.max(1, Math.min(Number(args.limit), maxCaptureEntries)) : 200,
+  };
+}
+
+function captureMatches(item, filter) {
+  if (filter.sinceId !== null && Number(item.id) <= filter.sinceId) return false;
+  if (filter.sinceMs !== null && Number(item.timestampMs) < filter.sinceMs) return false;
+  return true;
+}
+
+function normalizeStream(value) {
+  const stream = String(value || '').trim();
+  if (stream === 'log') return 'logs';
+  if (stream === 'event') return 'events';
+  if (stream === 'logs' || stream === 'network' || stream === 'state' || stream === 'events') return stream;
+  return '';
+}
+
+function boundedPush(target, item, maxSize) {
+  while (target.length >= maxSize) target.shift();
+  target.push(item);
+}
+
+function setCors(response) {
+  response.setHeader('Access-Control-Allow-Origin', '*');
+  response.setHeader('Access-Control-Allow-Headers', 'content-type,x-ai-app-bridge-token');
+  response.setHeader('Access-Control-Allow-Methods', 'GET,POST,OPTIONS');
+}
+
+function writeJson(response, payload, statusCode = 200) {
+  response.writeHead(statusCode, { 'Content-Type': 'application/json; charset=utf-8' });
+  response.end(JSON.stringify(payload));
+}
+
+function randomToken(bytes = 18) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+function stringArg(value, fallback) {
+  const text = value === undefined || value === null ? '' : String(value);
+  return text.trim() ? text : fallback;
+}
+
+function numberArg(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+module.exports = {
+  WebBridgeProvider,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Desktop CLI and MCP server for AI App Bridge.",
   "repository": {
     "type": "git",
@@ -18,6 +18,7 @@
   "files": [
     "bin/ai-app-bridge.js",
     "bin/mcp-server.js",
+    "bin/web-provider.js",
     "skills/ai-app-bridge-use",
     "README.md"
   ],