@browserbridge/bbx 1.12.5 → 1.14.1

package/packages/mcp-server/src/handlers-utils.js

@@ -58,6 +58,73 @@ const MCP_AGENT_SESSION = process.env.BBX_SESSION?.trim() || MCP_CLIENT_ID;
 const MCP_REQUEST_ERA = new AsyncLocalStorage();
 /** @type {AsyncLocalStorage<import('../../protocol/src/types.js').BrowserTarget>} */
 const MCP_REQUEST_TARGET = new AsyncLocalStorage();
+/** @typedef {import('../../agent-client/src/client.js').BridgeClient} McpBridgeClient */
+/** @typedef {{ clients: Map<string, Promise<McpBridgeClient>>, clientId: string, agentSession: string, closed: boolean }} McpClientSession */
+/** @type {AsyncLocalStorage<McpClientSession>} */
+const MCP_CLIENT_SESSION = new AsyncLocalStorage();
+/** @type {WeakSet<McpBridgeClient>} */
+const PERSISTENT_CLIENTS = new WeakSet();
+/** @type {WeakMap<McpBridgeClient, Promise<void>>} */
+const CONNECTING_CLIENTS = new WeakMap();
+
+/** @returns {McpClientSession} */
+export function createMcpClientSession() {
+  const clientId = `mcp_${randomUUID()}`;
+  return {
+    clients: new Map(),
+    clientId,
+    agentSession: process.env.BBX_SESSION?.trim() || clientId,
+    closed: false,
+  };
+}
+
+/**
+ * @template T
+ * @param {McpClientSession} session
+ * @param {() => T} callback
+ * @returns {T}
+ */
+export function runWithMcpClientSession(session, callback) {
+  return MCP_CLIENT_SESSION.run(session, callback);
+}
+
+/** @param {McpClientSession} session @returns {Promise<void>} */
+export async function closeMcpClientSession(session) {
+  session.closed = true;
+  const clients = [...session.clients.values()];
+  session.clients.clear();
+  await Promise.allSettled(clients.map(async (pending) => (await pending).close()));
+}
+
+/**
+ * @param {McpClientSession} session
+ * @param {string | null | undefined} destinationId
+ * @returns {Promise<McpBridgeClient>}
+ */
+async function getSessionClient(session, destinationId) {
+  if (session.closed) throw new Error('MCP connection is closed.');
+  const key = destinationId || 'local';
+  let pending = session.clients.get(key);
+  if (!pending) {
+    pending = createBridgeClientForDestination(destinationId, {
+      checkProtocolOnConnect: false,
+      clientId: session.clientId,
+      agentSession: session.agentSession,
+    }).then(async (client) => {
+      if (session.closed) {
+        await client.close();
+        throw new Error('MCP connection is closed.');
+      }
+      PERSISTENT_CLIENTS.add(client);
+      return client;
+    });
+    session.clients.set(key, pending);
+    void pending.catch(() => {
+      if (session.clients.get(key) === pending) session.clients.delete(key);
+    });
+  }
+  return pending;
+}
 
 /**
  * Scope routing to one tool invocation, including selector resolution and retries.
@@ -188,6 +255,23 @@ function waitForMcpRequest(delayMs) {
  * @returns {Promise<void>}
  */
 function connectMcpClient(client, timeoutMs) {
+  if (PERSISTENT_CLIENTS.has(client)) {
+    if (client.connected) return Promise.resolve();
+    let connecting = CONNECTING_CLIENTS.get(client);
+    if (!connecting) {
+      // A cancelled call must not close a connection shared by other calls.
+      connecting = MCP_REQUEST_ERA.exit(() =>
+        awaitMcpOperation(() => client.connect(), {
+          timeoutMs,
+          onCancel: () => {
+            void client.close().catch(() => {});
+          },
+        })
+      ).finally(() => CONNECTING_CLIENTS.delete(client));
+      CONNECTING_CLIENTS.set(client, connecting);
+    }
+    return awaitMcpOperation(() => connecting);
+  }
   return awaitMcpOperation(() => client.connect(), {
     timeoutMs,
     onCancel: () => {
@@ -412,6 +496,18 @@ export async function withToolClient(callback, options = {}) {
  */
 export async function withMcpRequestClient(callback, options = {}) {
   throwIfMcpRequestCancelled();
+  const session = MCP_CLIENT_SESSION.getStore();
+  if (session) {
+    return awaitMcpOperation(async () => {
+      const client = await getSessionClient(session, options.destinationId);
+      throwIfMcpRequestCancelled();
+      if (session.closed) throw new Error('MCP connection is closed.');
+      await connectMcpClient(client, client.defaultTimeoutMs);
+      throwIfMcpRequestCancelled();
+      if (session.closed) throw new Error('MCP connection is closed.');
+      return callback(client);
+    });
+  }
   const client = await createBridgeClientForDestination(options.destinationId, {
     checkProtocolOnConnect: false,
     clientId: MCP_CLIENT_ID,

package/packages/mcp-server/src/server.js

@@ -54,7 +54,12 @@ import {
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { getMcpServerInstructions } from './guidance.js';
 import { isToolEnabledForEra, LOADABLE_TOOLSET_TOOLS } from './toolset.js';
-import { runWithMcpRequestTarget } from './handlers-utils.js';
+import {
+  runWithMcpRequestTarget,
+  createMcpClientSession,
+  runWithMcpClientSession,
+  closeMcpClientSession,
+} from './handlers-utils.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -181,6 +186,18 @@ export function createBridgeMcpServer(options = {}) {
 
   /** @type {Map<string, ReturnType<typeof server.registerTool>>} */
   const registrations = new Map();
+  const clientSession = createMcpClientSession();
+  server.server.onclose = () => {
+    void closeMcpClientSession(clientSession);
+  };
+  const closeServer = server.close.bind(server);
+  server.close = async () => {
+    try {
+      await closeServer();
+    } finally {
+      await closeMcpClientSession(clientSession);
+    }
+  };
 
   /**
    * Register a tool, then hide it when it is not part of the era's compact surface.
@@ -206,7 +223,10 @@ export function createBridgeMcpServer(options = {}) {
       (args, context) =>
         runWithMcpRequestEra(
           era,
-          () => runWithMcpRequestTarget(args, () => handler(args, context)),
+          () =>
+            runWithMcpClientSession(clientSession, () =>
+              runWithMcpRequestTarget(args, () => handler(args, context))
+            ),
           context.mcpReq.signal
         )
     );

package/packages/native-host/src/artifact-store.js

@@ -58,7 +58,7 @@ export class ArtifactStore {
     }
     if (
       !Number.isInteger(input.totalBytes) ||
-      input.totalBytes < 1 ||
+      input.totalBytes < (input.kind === 'resource' ? 0 : 1) ||
       input.totalBytes > MAX_ARTIFACT_BYTES ||
       input.chunkCount !== Math.ceil(input.totalBytes / ARTIFACT_CHUNK_BYTES)
     ) {
@@ -128,6 +128,12 @@ export class ArtifactStore {
         'Artifact chunk order is invalid.'
       );
     }
+    if (data.length > Math.ceil(ARTIFACT_CHUNK_BYTES / 3) * 4) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact chunk size is invalid.'
+      );
+    }
     const bytes = decodeBase64(data);
     if (bytes.length < 1 || bytes.length > ARTIFACT_CHUNK_BYTES) {
       throw new BridgeError(
@@ -141,7 +147,17 @@ export class ArtifactStore {
         'Artifact exceeds declared size.'
       );
     }
-    fs.writeSync(transfer.fd, bytes);
+    try {
+      let offset = 0;
+      while (offset < bytes.length) {
+        const written = fs.writeSync(transfer.fd, bytes, offset, bytes.length - offset);
+        if (written <= 0) throw new Error('Artifact write made no progress.');
+        offset += written;
+      }
+    } catch (error) {
+      this.abort(artifactId);
+      throw error;
+    }
     transfer.hash.update(bytes);
     transfer.written += bytes.length;
     transfer.nextChunk += 1;
@@ -198,7 +214,16 @@ export class ArtifactStore {
     const bytes = Buffer.alloc(byteLength);
     const fd = fs.openSync(record.filePath, 'r');
     try {
-      fs.readSync(fd, bytes, 0, byteLength, start);
+      let offset = 0;
+      while (offset < byteLength) {
+        const read = fs.readSync(fd, bytes, offset, byteLength - offset, start + offset);
+        if (read <= 0)
+          throw new BridgeError(
+            ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+            'Artifact was truncated on disk.'
+          );
+        offset += read;
+      }
     } finally {
       fs.closeSync(fd);
     }
@@ -286,6 +311,16 @@ export class ArtifactStore {
     }
   }
 
+  /** @param {string} ownerId */
+  deleteByOwner(ownerId) {
+    for (const transfer of this.transfers.values()) {
+      if (transfer.ownerId === ownerId) this.abort(transfer.artifactId);
+    }
+    for (const record of this.artifacts.values()) {
+      if (record.ownerId === ownerId) this.removeCommitted(record.artifactId);
+    }
+  }
+
   pruneExpired() {
     const now = this.now();
     for (const transfer of [...this.transfers.values()]) {
@@ -333,7 +368,10 @@ export class ArtifactStore {
 function isValidKindAndMimeType(kind, mimeType) {
   return (
     (kind === 'screenshot' && mimeType.startsWith('image/')) ||
-    (kind === 'har' && mimeType === 'application/json')
+    (kind === 'har' && mimeType === 'application/json') ||
+    (kind === 'resource' &&
+      /^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/u.test(mimeType) &&
+      mimeType.length <= 120)
   );
 }
 

package/packages/native-host/src/auth-token.js

@@ -235,6 +235,18 @@ async function ensureStoredBridgeAuthToken(tokenPath, options) {
         owner = await readFile(lockPath, 'utf8');
       } catch (error) {
         if (isMissingFileError(error)) continue;
+        // Windows can report EPERM while a competing owner deletes the lock.
+        // Retry within the same bounded acquisition loop, then recheck the winner.
+        if (
+          process.platform === 'win32' &&
+          error &&
+          typeof error === 'object' &&
+          'code' in error &&
+          error.code === 'EPERM'
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 10));
+          continue;
+        }
         throw error;
       }
       const match = /^(\d+):([0-9a-f-]{36})\n$/u.exec(owner);

package/packages/native-host/src/daemon.js

@@ -46,6 +46,8 @@ import {
   getSocketPath,
 } from './config.js';
 import { ArtifactStore } from './artifact-store.js';
+import { RecordingStore } from './recording-store.js';
+import { BridgeError } from '../../protocol/src/errors.js';
 import {
   bridgeAuthTokensEqual,
   ensureBridgeAuthToken,
@@ -211,6 +213,23 @@ function normalizeExtensionHealthResult(value) {
   /** @type {Record<string, unknown>} */
   const normalized = {};
   if (result.extension === 'ok') normalized.extension = 'ok';
+  const build = asHealthRecord(result.loadedBuild);
+  if (
+    build &&
+    typeof build.workerId === 'string' &&
+    /^[a-f0-9-]{36}$/u.test(build.workerId) &&
+    typeof build.startedAt === 'string' &&
+    build.startedAt.length <= 32 &&
+    Number.isFinite(Date.parse(build.startedAt)) &&
+    (build.sourceDigest === null ||
+      (typeof build.sourceDigest === 'string' && /^[a-f0-9]{64}$/u.test(build.sourceDigest)))
+  ) {
+    normalized.loadedBuild = {
+      workerId: build.workerId,
+      startedAt: build.startedAt,
+      sourceDigest: build.sourceDigest,
+    };
+  }
   if (
     typeof result.extensionVersion === 'string' &&
     /^\d+\.\d+\.\d+$/u.test(result.extensionVersion)
@@ -432,12 +451,30 @@ export function isWindowsNamedPipePath(socketPath) {
  *   artifact?: Record<string, unknown>,
  *   chunkIndex?: number,
  *   data?: string
+ *   journalId?: string,
+ *   offset?: number,
+ *   messageId?: string,
  * }} DaemonMessage
  */
 
 /** @typedef {import('../../protocol/src/types.js').ArtifactKind} ArtifactKind */
 
 export class BridgeDaemon {
+  /** File data belongs to a transport connection, never a caller-selected label.
+   * @type {WeakMap<ClientSocket, string>} */
+  dataOwners = new WeakMap();
+  /** @type {WeakMap<ClientSocket, Set<ClientSocket>>} */
+  dataOwnerTargets = new WeakMap();
+
+  /** @param {ClientSocket} socket */
+  getDataOwner(socket) {
+    let owner = this.dataOwners.get(socket);
+    if (!owner) {
+      owner = randomUUID();
+      this.dataOwners.set(socket, owner);
+    }
+    return owner;
+  }
   /**
    * @param {{
    *   transport?: BridgeTransport,
@@ -448,7 +485,8 @@ export class BridgeDaemon {
    *   logger?: DaemonLoggerLike | Pick<Console, 'log' | 'error'>,
    *   authToken?: string | null,
    *   extensionAuthToken?: string | null,
-   *   artifactStore?: ArtifactStore
+   *   artifactStore?: ArtifactStore,
+   *   recordingStore?: RecordingStore,
    * }} [options={}]
    */
   constructor({
@@ -461,6 +499,9 @@ export class BridgeDaemon {
     authToken = undefined,
     extensionAuthToken = undefined,
     artifactStore = new ArtifactStore(getArtifactStorePath()),
+    recordingStore = new RecordingStore(
+      path.join(path.dirname(getArtifactStorePath()), 'recordings')
+    ),
   } = {}) {
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
     this.socketPath =
@@ -512,6 +553,7 @@ export class BridgeDaemon {
     /** @type {string | null | undefined} */
     this.extensionAuthToken = extensionAuthToken;
     this.artifactStore = artifactStore;
+    this.recordingStore = recordingStore;
     this.artifactStoreInitialized = false;
     this.domBaselines = new DomBaselineOwnerRegistry({
       isCurrentExtensionSocket: (socket) =>
@@ -1016,6 +1058,40 @@ export class BridgeDaemon {
       }
       return this.handleExtensionArtifact(socket, message);
     }
+    if (
+      message?.type === 'extension.journal.begin' ||
+      message?.type === 'extension.journal.append'
+    ) {
+      if (socket.__role !== 'extension' || !socket.__extensionId)
+        return this.rejectMessageForRole(socket, message);
+      try {
+        let result;
+        if (message.type === 'extension.journal.begin') {
+          const pending = this.pendingRequests.get(String(message.requestId));
+          if (!pending || pending.method !== 'session.start' || !pending.targets.has(socket))
+            throw new Error('Journal must be created by a pending session.start request.');
+          result = this.recordingStore.begin(socket.__extensionId);
+        } else
+          result = this.recordingStore.append(
+            String(message.journalId),
+            socket.__extensionId,
+            Number(message.offset),
+            String(message.data)
+          );
+        await writeJsonLine(socket, {
+          type: 'extension.journal.ack',
+          messageId: message.messageId,
+          result,
+        });
+      } catch (error) {
+        await writeJsonLine(socket, {
+          type: 'extension.journal.ack',
+          messageId: message.messageId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      return;
+    }
 
     if (message?.type === 'extension.setup_status.request') {
       if (socket.__role !== 'extension') {
@@ -1187,8 +1263,36 @@ export class BridgeDaemon {
       return;
     }
 
+    if (request.method === 'session.journal_read' || request.method === 'session.journal_delete') {
+      try {
+        const result =
+          request.method === 'session.journal_read'
+            ? this.recordingStore.read(
+                String(request.params.journalId),
+                Number(request.params.offset),
+                Number(request.params.maxBytes)
+              )
+            : this.recordingStore.delete(String(request.params.journalId));
+        await writeJsonLine(socket, {
+          type: 'agent.response',
+          response: createSuccess(request.id, result, { method: request.method }),
+        });
+      } catch (error) {
+        await writeJsonLine(socket, {
+          type: 'agent.response',
+          response: createFailure(
+            request.id,
+            error instanceof BridgeError ? error.code : ERROR_CODES.ARTIFACT_NOT_FOUND,
+            error instanceof BridgeError ? error.message : 'Recording journal unavailable.',
+            null,
+            { method: request.method }
+          ),
+        });
+      }
+      return;
+    }
     if (request.method === 'artifact.read' || request.method === 'artifact.delete') {
-      const ownerId = socket.__clientId;
+      const ownerId = socket.__clientId ? this.getDataOwner(socket) : null;
       if (!ownerId) {
         const response = createFailure(
           request.id,
@@ -1424,7 +1528,20 @@ export class BridgeDaemon {
       targetCount: 1,
     });
     try {
-      await writeJsonLine(target, { type: 'extension.request', request });
+      if (
+        /^(?:files\.|session\.|download\.|input\.(?:set_files|paste_image)$)/u.test(request.method)
+      ) {
+        const targets = this.dataOwnerTargets.get(socket) ?? new Set();
+        targets.add(target);
+        this.dataOwnerTargets.set(socket, targets);
+      }
+      await writeJsonLine(target, {
+        type: 'extension.request',
+        request: {
+          ...request,
+          meta: { ...request.meta, transport_owner: this.getDataOwner(socket) },
+        },
+      });
     } catch (error) {
       this.logger.error('request route failed', {
         requestId: request.id,
@@ -1609,6 +1726,7 @@ export class BridgeDaemon {
         : null;
     if (!accessEnabled && socket.__extensionId) {
       this.artifactStore.deleteByExtension(socket.__extensionId);
+      this.recordingStore.disconnect(socket.__extensionId);
       this.domBaselines.clearForSocket(socket);
     }
     if (socket.__accessEnabled !== accessEnabled) {
@@ -1653,7 +1771,7 @@ export class BridgeDaemon {
     const requestId = typeof artifact.requestId === 'string' ? artifact.requestId : '';
     const pending = this.pendingRequests.get(requestId);
     if (!pending || !pending.targets.has(socket) || !socket.__extensionId) return;
-    const ownerId = pending.socket.__clientId;
+    const ownerId = pending.socket.__clientId ? this.getDataOwner(pending.socket) : null;
     if (!ownerId) return;
     try {
       if (
@@ -1671,6 +1789,9 @@ export class BridgeDaemon {
         }
       }
       if (message.type === 'extension.artifact.begin') {
+        if (artifact.kind !== getArtifactKindForMethod(pending.method)) {
+          throw new Error('Artifact kind does not match the routed operation.');
+        }
         this.artifactStore.begin({
           artifactId: String(artifact.artifactId ?? ''),
           requestId,
@@ -1698,7 +1819,7 @@ export class BridgeDaemon {
         error && typeof error === 'object' && 'code' in error
           ? /** @type {import('../../protocol/src/types.js').ErrorCode} */ (error.code)
           : ERROR_CODES.ARTIFACT_TRANSFER_INVALID;
-      pending.lastErrorResponse = createFailure(
+      pending.lastErrorResponse ??= createFailure(
         requestId,
         code,
         error instanceof Error ? error.message : String(error),
@@ -1784,7 +1905,7 @@ export class BridgeDaemon {
           !pending.socket.__clientId ||
           !this.artifactStore.matchesCommitted(
             String(artifact.artifactId ?? ''),
-            pending.socket.__clientId,
+            this.getDataOwner(pending.socket),
             responseMessage.id,
             artifact,
             expectedArtifactKind ?? undefined
@@ -1895,6 +2016,19 @@ export class BridgeDaemon {
    * @returns {void}
    */
   handleSocketClose(socket) {
+    const dataOwner = this.dataOwners.get(socket);
+    if (dataOwner) {
+      this.artifactStore.deleteByOwner(dataOwner);
+      for (const target of this.dataOwnerTargets.get(socket) ?? []) {
+        if (!target.destroyed)
+          void writeJsonLine(target, {
+            type: 'extension.owner_disconnected',
+            ownerId: dataOwner,
+          }).catch(() => {});
+      }
+    }
+    this.dataOwnerTargets.delete(socket);
+    this.dataOwners.delete(socket);
     this.windowActions.disconnect(socket);
     this.clientSockets.delete(socket);
     if (socket.__registrationTimeoutId) {
@@ -2068,6 +2202,8 @@ function isAutomaticMcpRetry(meta) {
 function getArtifactKindForMethod(method) {
   if (method?.startsWith('screenshot.')) return 'screenshot';
   if (method === 'network.export_har') return 'har';
+  if (method === 'download.resource') return 'resource';
+  if (method === 'session.export') return 'resource';
   return null;
 }
 

package/packages/native-host/src/native-host.js

@@ -183,6 +183,13 @@ export async function runNativeHost({
           await writeNativeMessageQueued(message.request);
           return;
         }
+        if (message.type === 'extension.owner_disconnected') {
+          await writeNativeMessageQueued({
+            type: 'host.owner_disconnected',
+            ownerId: message.ownerId,
+          });
+          return;
+        }
         if (message.type === 'agent.response') {
           await writeNativeMessageQueued({
             type: 'host.bridge_response',
@@ -199,6 +206,7 @@ export async function runNativeHost({
         }
         if (
           message.type === 'extension.window_action.command' ||
+          message.type === 'extension.journal.ack' ||
           message.type === 'extension.window_action.response'
         ) {
           await writeNativeMessageQueued({
@@ -290,6 +298,8 @@ export async function runNativeHost({
           const record = /** @type {Record<string, unknown>} */ (message);
           if (
             record.type === 'host.window_action.request' ||
+            record.type === 'host.journal.begin' ||
+            record.type === 'host.journal.append' ||
             record.type === 'host.window_action.result'
           ) {
             await writeJsonLine(socket, {