Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

mcp-server: bound concurrent bot-memory scopes, not lifetime runs

Barack Sokullu74aa363437fe
diff --git a/mcp-server/src/bridge.ts b/mcp-server/src/bridge.ts
index 29a442b35..c56489e3e 100644
--- a/mcp-server/src/bridge.ts
+++ b/mcp-server/src/bridge.ts
@@ -17,6 +17,7 @@
* exact field names `cloud-runs.js` reads.
*/
+import { randomUUID } from "node:crypto";
import { WebSocketServer, type WebSocket } from "ws";
import { config } from "./config.js";
import { BOT_MEMORY_CAPABILITY, validateTaskMemory, taskMemoryPrivateValues, redactTaskMemory, redactMemoryRunResponse } from "./task-memory.js";
@@ -56,6 +57,22 @@ export interface CloudSnapshot {
export const TERMINAL_STATUSES = new Set(["completed", "failed", "aborted"]);
+/**
+ * Memory-run redaction scopes held at once. One bridge can live as long as the
+ * app hosting it, so this bounds concurrent scopes, not lifetime runs: an
+ * unfinished run keeps its scope until the extension reports it terminal, and
+ * finished scopes are recycled oldest-first when room is needed.
+ */
+export const MAX_MEMORY_RUN_SCOPES = 256;
+
+interface MemoryRunState {
+ credentials: readonly string[];
+ /** The start was answered (or never sent): the run is in the extension's list or never will be. */
+ startSettled: boolean;
+ /** The extension reported a terminal status, so nothing new can reach this run. */
+ finished: boolean;
+}
+
interface Pending {
resolve: (value: unknown) => void;
reject: (reason: Error) => void;
@@ -109,7 +126,8 @@ export class WebBrainBridge {
private memoryPrivateValues = new Set<string>();
private memoryProtectedRunIds = new Set<string>();
private memoryRunValues = new Map<string, ReadonlySet<string>>();
- private protectedMemoryRequests = 0;
+ /** Lifecycle of each scope above, in eviction order (oldest finished first). */
+ private memoryRuns = new Map<string, MemoryRunState>();
async start(): Promise<void> {
if (this.wss) return;
@@ -236,6 +254,12 @@ export class WebBrainBridge {
this.pending.delete(id);
clearTimeout(entry.timer);
+ if (entry.memoryStart && entry.runId) {
+ // Answered either way, so the extension now lists this run or never will.
+ const state = this.memoryRuns.get(entry.runId);
+ if (state) state.startSettled = true;
+ }
+
if (msg.ok === false) {
const status = typeof msg.status === "number" ? msg.status : undefined;
entry.reject(new BridgeError(String(redactMemoryRunResponse(msg.error || "Unknown bridge error", this.memoryPrivateValues,
@@ -248,8 +272,13 @@ export class WebBrainBridge {
if (typeof runId === "string") {
this.memoryProtectedRunIds.add(runId);
if (entry.memoryValues) this.memoryRunValues.set(runId, new Set([...(this.memoryRunValues.get(runId) || []), ...entry.memoryValues]));
+ if (!this.memoryRuns.has(runId)) {
+ const credentials = (entry.runId && this.memoryRuns.get(entry.runId)?.credentials) || [];
+ this.memoryRuns.set(runId, { credentials, startSettled: true, finished: false });
+ }
}
}
+ this.noteMemoryRunStatuses(msg.result, entry.runId);
entry.resolve(redactMemoryRunResponse(msg.result, this.memoryPrivateValues, this.memoryProtectedRunIds,
entry.protectedRequest, { runValues: this.memoryRunValues, requestRunId: entry.runId, requestValues: entry.memoryValues }));
}
@@ -262,6 +291,64 @@ export class WebBrainBridge {
this.pending.clear();
}
+ /** Track which protected runs the extension reports as finished (or live again). */
+ private noteMemoryRunStatuses(result: unknown, requestRunId?: string): void {
+ if (!this.memoryRuns.size || !result || typeof result !== "object") return;
+ const listed = (result as { runs?: unknown }).runs;
+ for (const run of Array.isArray(listed) ? listed : [result]) {
+ if (!run || typeof run !== "object") continue;
+ const snapshot = run as Record<string, unknown>;
+ const runId = String(snapshot.runId || snapshot.run_id || (Array.isArray(listed) ? "" : requestRunId || ""));
+ const state = this.memoryRuns.get(runId);
+ if (!state || typeof snapshot.status !== "string") continue;
+ state.startSettled = true;
+ const finished = TERMINAL_STATUSES.has(snapshot.status);
+ if (finished && !state.finished) {
+ // Re-append so the most recently finished runs keep their scope longest.
+ this.memoryRuns.delete(runId);
+ this.memoryRuns.set(runId, state);
+ }
+ state.finished = finished;
+ }
+ }
+
+ /** Drop the oldest finished scopes until one more fits; false if every slot is unfinished. */
+ private evictFinishedMemoryRuns(): boolean {
+ let evicted = false;
+ for (const [runId, state] of this.memoryRuns) {
+ if (this.memoryRuns.size < MAX_MEMORY_RUN_SCOPES) break;
+ if (!state.finished) continue;
+ this.memoryRuns.delete(runId);
+ this.memoryProtectedRunIds.delete(runId);
+ this.memoryRunValues.delete(runId);
+ evicted = true;
+ }
+ if (evicted) {
+ // Runs can share a credential, so keep every one a retained run still uses.
+ this.memoryPrivateValues = new Set([...this.memoryRuns.values()].flatMap((state) => state.credentials));
+ }
+ return this.memoryRuns.size < MAX_MEMORY_RUN_SCOPES;
+ }
+
+ /**
+ * A caller that stopped polling leaves a finished run looking unfinished.
+ * The extension's run list is authoritative (it hydrates first), so re-read
+ * it: terminal runs are noted on the way in, and a settled start missing
+ * from the list can never be returned again.
+ */
+ private async refreshMemoryRunStates(timeoutMs: number): Promise<void> {
+ try {
+ const listed = await this.request<{ runs?: CloudSnapshot[] }>("cloud_status", {}, timeoutMs);
+ if (!Array.isArray(listed?.runs)) return;
+ const present = new Set(listed.runs.map((run) => String(run.runId || run.run_id || "")));
+ for (const [runId, state] of this.memoryRuns) {
+ if (state.startSettled && !present.has(runId)) state.finished = true;
+ }
+ } catch {
+ /* the caller reports capacity */
+ }
+ }
+
isConnected(): boolean {
return (
this.socket !== null &&
@@ -316,21 +403,37 @@ export class WebBrainBridge {
if (!this.capabilities().includes(BOT_MEMORY_CAPABILITY)) {
throw new BridgeError("Update the browser extension before starting a task with bot memory.", 409);
}
- // Retain privacy through failed/late runs; never evict an old scope and
- // then accidentally expose its data when status is queried again.
- if (this.protectedMemoryRequests >= 256) {
- throw new BridgeError("Private memory relay capacity reached. Restart the MCP server before starting another memory run.", 409);
- }
- this.protectedMemoryRequests += 1;
- payload = { ...payload, taskMemory: memory };
- memoryValues = taskMemoryPrivateValues(memory);
- this.memoryPrivateValues.add(memory.callbackToken);
- this.memoryPrivateValues.add(memory.callbackUrl);
- if (typeof payload.runId === "string") {
- this.memoryProtectedRunIds.add(payload.runId);
- memoryValues = new Set([...(this.memoryRunValues.get(payload.runId) || []), ...memoryValues]);
- this.memoryRunValues.set(payload.runId, memoryValues);
+ // Retain privacy through failed/late runs: a scope is never evicted
+ // before the extension reports its run finished, and only then once
+ // room is needed. A known run ID lets every start be tracked that way.
+ const runId = typeof payload.runId === "string" ? payload.runId : `mcp_${randomUUID()}`;
+ if (!this.memoryRuns.has(runId) && !this.evictFinishedMemoryRuns()) {
+ await this.refreshMemoryRunStates(timeoutMs);
+ if (this.socket !== socket || !this.isConnected()) {
+ throw new BridgeError("WebBrain extension disconnected before the memory run could start.");
+ }
+ // Re-checked with no await before the scope is added below.
+ if (!this.memoryRuns.has(runId) && !this.evictFinishedMemoryRuns()) {
+ throw new BridgeError(
+ `${MAX_MEMORY_RUN_SCOPES} bot-memory runs are still unfinished on this bridge. ` +
+ "Wait for one to finish or abort it before starting another memory run.",
+ 409,
+ );
+ }
}
+ payload = { ...payload, runId, taskMemory: memory };
+ memoryValues = new Set([...(this.memoryRunValues.get(runId) || []), ...taskMemoryPrivateValues(memory)]);
+ const credentials = [memory.callbackToken, memory.callbackUrl];
+ for (const credential of credentials) this.memoryPrivateValues.add(credential);
+ this.memoryProtectedRunIds.add(runId);
+ this.memoryRunValues.set(runId, memoryValues);
+ const previous = this.memoryRuns.get(runId);
+ this.memoryRuns.delete(runId);
+ this.memoryRuns.set(runId, {
+ credentials: [...new Set([...(previous?.credentials || []), ...credentials])],
+ startSettled: false,
+ finished: false,
+ });
}
const id = this.nextId++;
@@ -376,7 +479,7 @@ export class WebBrainBridge {
this.memoryPrivateValues.clear();
this.memoryProtectedRunIds.clear();
this.memoryRunValues.clear();
- this.protectedMemoryRequests = 0;
+ this.memoryRuns.clear();
if (this.socket) {
try {
this.socket.close(1001, "Server shutting down");
diff --git a/mcp-server/test/task-memory.test.mjs b/mcp-server/test/task-memory.test.mjs
index 2e7ffd176..4c9eeae02 100644
--- a/mcp-server/test/task-memory.test.mjs
+++ b/mcp-server/test/task-memory.test.mjs
@@ -13,7 +13,7 @@ await once(allocator, 'listening');
process.env.WEBBRAIN_BRIDGE_PORT = String(allocator.address().port);
allocator.close();
await once(allocator, 'close');
-const { WebBrainBridge } = await import('../dist/bridge.js');
+const { WebBrainBridge, MAX_MEMORY_RUN_SCOPES } = await import('../dist/bridge.js');
const { startRun, getStatus, describeSnapshot } = await import('../dist/runs.js');
const { bridgeUrl } = await import('../dist/config.js');
const { validateTaskMemory, redactTaskMemory, redactMemoryRunResponse, taskMemoryPrivateValues } = await import('../dist/task-memory.js');
@@ -135,6 +135,94 @@ test('memory values survive failure and reconnect, with capability downgrade sti
} finally { first.close(); second?.close(); await bridge.stop(); }
});
+const memoryFor = runId => ({ ...memory, runId, callbackUrl: `http://127.0.0.1:4174/api/internal/bot-memory/${runId}`,
+ callbackToken: `private-scoped-callback-token-${runId}`, context: { notes: `private-note-${runId}` } });
+const memoryExtension = reply => {
+ const socket = new WebSocket(bridgeUrl());
+ socket.on('open', () => socket.send(JSON.stringify({ type: 'hello', client: 'webbrain-extension', protocolVersion: 2, capabilities: ['bot_memory_v1'] })));
+ socket.on('message', raw => { const msg = JSON.parse(raw.toString()); socket.send(JSON.stringify({ id: msg.id, ...reply(msg) })); });
+ return socket;
+};
+const assertBoundedScopes = bridge => {
+ assert.ok(bridge.memoryRuns.size <= MAX_MEMORY_RUN_SCOPES);
+ assert.ok(bridge.memoryRunValues.size <= MAX_MEMORY_RUN_SCOPES);
+ assert.ok(bridge.memoryProtectedRunIds.size <= MAX_MEMORY_RUN_SCOPES);
+ assert.ok(bridge.memoryPrivateValues.size <= 2 * MAX_MEMORY_RUN_SCOPES);
+};
+
+test('one long-lived bridge keeps accepting sequential memory runs while retained memory stays bounded', async () => {
+ const bridge = new WebBrainBridge();
+ await bridge.start();
+ const extension = memoryExtension(msg => ({ ok: true, result: msg.action === 'cloud_run'
+ ? { runId: msg.payload.runId, status: 'running' }
+ : { runId: msg.payload.runId, status: 'completed', content: `Finished private-note-${msg.payload.runId}` } }));
+ const total = 2 * MAX_MEMORY_RUN_SCOPES + 10;
+ try {
+ assert.equal(await bridge.waitForExtension(3000), true);
+ for (let i = 0; i < total; i++) {
+ const runId = `sequential-${i}`;
+ const privateMemory = memoryFor(runId);
+ await startRun(bridge, { runId, task: 'Check the page', mode: 'act', taskMemory: privateMemory });
+ const settled = await getStatus(bridge, runId);
+ assert.equal(settled.status, 'completed');
+ for (const secret of [privateMemory.callbackToken, privateMemory.context.notes]) assert.equal(JSON.stringify(settled).includes(secret), false);
+ }
+ assertBoundedScopes(bridge);
+ const latest = `sequential-${total - 1}`;
+ assert.equal(JSON.stringify(await getStatus(bridge, latest)).includes(`private-note-${latest}`), false);
+ } finally { extension.close(); await bridge.stop(); }
+});
+
+test('unfinished memory runs keep their scopes; a full bridge rereads the run list before refusing', async () => {
+ const bridge = new WebBrainBridge();
+ await bridge.start();
+ const states = new Map();
+ const sent = [];
+ const extension = memoryExtension(msg => {
+ sent.push(msg);
+ const { runId } = msg.payload;
+ if (msg.action === 'cloud_run') { states.set(runId, 'running'); return { ok: true, result: { runId, status: 'running' } }; }
+ if (!runId) return { ok: true, result: { runs: [...states].map(([id, status]) => ({ runId: id, status })) } };
+ return { ok: true, result: { runId, status: states.get(runId), content: `Working on private-note-${runId}` } };
+ });
+ const starts = () => sent.filter(msg => msg.action === 'cloud_run').length;
+ const start = runId => startRun(bridge, { runId, task: 'Check the page', mode: 'act', taskMemory: memoryFor(runId) });
+ try {
+ assert.equal(await bridge.waitForExtension(3000), true);
+ for (let i = 0; i < MAX_MEMORY_RUN_SCOPES; i++) await start(`live-${i}`);
+ await assert.rejects(start('overflow'), error => error.status === 409 && /unfinished/.test(error.message));
+ assert.equal(starts(), MAX_MEMORY_RUN_SCOPES);
+ assert.deepEqual(sent.at(-1), { id: sent.at(-1).id, action: 'cloud_status', payload: {} });
+ assert.equal(JSON.stringify(await getStatus(bridge, 'live-0')).includes('private-note-live-0'), false);
+ // Finished without anyone polling it; only the run list reveals that.
+ states.set('live-7', 'completed');
+ await start('after-finish');
+ assert.equal(starts(), MAX_MEMORY_RUN_SCOPES + 1);
+ assert.equal(bridge.memoryRuns.has('live-7'), false);
+ assertBoundedScopes(bridge);
+ for (const runId of ['live-0', 'live-8', 'after-finish']) {
+ assert.equal(JSON.stringify(await getStatus(bridge, runId)).includes(`private-note-${runId}`), false);
+ }
+ } finally { extension.close(); await bridge.stop(); }
+});
+
+test('memory starts the extension refuses never exhaust bridge capacity', async () => {
+ const bridge = new WebBrainBridge();
+ await bridge.start();
+ const extension = memoryExtension(msg => msg.action === 'cloud_run'
+ ? { ok: false, status: 409, error: `Tab is busy for private-note-${msg.payload.runId}` }
+ : { ok: true, result: { runs: [] } });
+ try {
+ assert.equal(await bridge.waitForExtension(3000), true);
+ for (let i = 0; i < MAX_MEMORY_RUN_SCOPES + 10; i++) {
+ const runId = `refused-${i}`;
+ await assert.rejects(startRun(bridge, { runId, task: 'Check the page', mode: 'act', taskMemory: memoryFor(runId) }),
+ error => error.status === 409 && /Tab is busy/.test(error.message) && !error.message.includes(`private-note-${runId}`));
+ }
+ assertBoundedScopes(bridge);
+ } finally { extension.close(); await bridge.stop(); }
+});
+
test('MCP rejects protected runs on old bridges before dispatch; ordinary calls are unchanged', async () => {
const calls = [];
const bridge = { capabilities: () => [], async request(action, payload) { calls.push({ action, payload }); return { runId: 'ordinary', status: 'running' }; } };