Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
import fs from 'node:fs/promises';
import path from 'node:path';
import { createRequire } from 'node:module';
import { createHash } from 'node:crypto';
const require = createRequire(import.meta.url);
const terminalStatuses = new Set(['completed', 'failed', 'stopped', 'cancelled', 'clarification_required']);
const profileOwners = new Set();
const runtimeFiles = ['manifest.json', 'src/background.js', 'src/agent/agent.js', 'src/providers/manager.js'];
const capabilities = Object.freeze({ domObservation: true, activeSteering: true, checkpoints: true,
interventions: true, files: true, continuation: true });
export class LocalBackendError extends Error {
constructor(message, status = 'failed', code = 'local_backend_error') {
super(safeError(message));
this.name = 'LocalBackendError';
this.status = status;
this.code = code;
}
}
function safeError(error, limit = 2000) {
return String(error?.message || error || 'Unknown error')
.replace(/\b(Bearer\s+)[^\s"']+/gi, '$1[redacted]')
.replace(/\b(sk-[a-z0-9_-]{8,})\b/gi, '[redacted]')
.replace(/(["']?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret|authorization)["']?\s*[=:]\s*)(["']?)[^\s&,"']+\2/gi, '$1[redacted]')
.replace(/(https?:\/\/)[^/@\s]+:[^/@\s]+@/gi, '$1[redacted]@')
.slice(0, limit);
}
function safeUpdate(event) {
const source = event?.data || {};
const nested = source.result || source;
const data = {};
for (const key of ['name', 'status', 'code', 'outcome', 'attachmentDeliveryState', 'reason']) {
const value = source[key] ?? nested[key];
if (typeof value === 'string' && /^[a-z0-9_:-]{1,100}$/i.test(value)) data[key] = value;
}
for (const key of ['success', 'done', 'blockedDone', 'noDispatch', 'dispatched', 'deliveryVerified', 'runSucceeded', 'successfulDone', 'eventsMissing']) {
const value = source[key] ?? nested[key];
if (typeof value === 'boolean') data[key] = value;
}
return { seq: event.seq, type: event.type, ts: event.ts, data };
}
function assertConfiguration(role) {
if (!role.profile && !role.cdpUrl) throw new Error('Local backend requires an explicit dedicated profile or CDP URL.');
if (role.profile && role.cdpUrl) throw new Error('Choose a dedicated profile or CDP attachment, not both.');
if (role.profile) {
if (!path.isAbsolute(role.profile)) throw new Error('Dedicated profile must be an absolute path.');
if (/[\\/](?:Google[\\/]Chrome|Microsoft[\\/]Edge|Chromium)[\\/]User Data(?:[\\/]|$)/i.test(role.profile)) {
throw new Error('A normal browser user-data directory cannot be launched by this harness. Use a dedicated profile or CDP attachment.');
}
}
if (role.cdpUrl) {
let url;
try { url = new URL(role.cdpUrl); } catch { throw new Error('Invalid CDP URL.'); }
if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) throw new Error('Unsupported CDP URL protocol.');
if (url.username || url.password) throw new Error('Credentials must not be embedded in the CDP URL.');
if (!['localhost', '127.0.0.1', '[::1]'].includes(url.hostname.toLowerCase()) && role.trustRemoteCdp !== true) {
throw new Error('Non-loopback CDP attachment requires explicit trustRemoteCdp: true.');
}
}
if (role.extensionId && !/^[a-p]{32}$/.test(role.extensionId)) throw new Error('Invalid Chrome extension ID.');
}
async function discoverWebBrain(context, explicitId, timeoutMs) {
if (explicitId) return explicitId;
const find = async () => {
const matches = new Set();
const candidates = [...context.serviceWorkers(), ...context.pages()];
for (const candidate of candidates) {
if (!candidate.url().startsWith('chrome-extension://')) continue;
try {
const manifest = await candidate.evaluate(() => chrome.runtime.getManifest());
if (manifest.name === 'WebBrain' && manifest.background?.service_worker === 'src/background.js') {
matches.add(new URL(candidate.url()).hostname);
}
} catch { /* Dormant or unrelated extension pages do not identify WebBrain. */ }
}
if (matches.size > 1) throw new Error('Multiple WebBrain installations found. Set extensionId explicitly.');
return [...matches][0];
};
let id = await find();
if (!id) {
await context.waitForEvent('serviceworker', { timeout: Math.min(timeoutMs, 15000) }).catch(() => {});
id = await find();
}
if (!id) throw new Error('No installed WebBrain extension found. Set its exact extensionId or load extensionPath in a dedicated profile.');
return id;
}
async function createRuntimeTransport(context, role, timeoutMs) {
const extensionId = await discoverWebBrain(context, role.extensionId, timeoutMs);
const page = await context.newPage();
try {
// Steering intentionally requires the real chat-panel sender. This opens
// the packaged page and uses its ordinary runtime bus; no Agent is exposed.
await page.goto(`chrome-extension://${extensionId}/src/ui/sidepanel.html`, { timeout: timeoutMs });
const manifest = await page.evaluate(() => {
const value = chrome.runtime.getManifest();
return { name: value.name, version: value.version, worker: value.background?.service_worker };
});
if (manifest.name !== 'WebBrain' || manifest.worker !== 'src/background.js') {
throw new Error('Selected extension is not the WebBrain MV3 installation.');
}
await page.evaluate(() => {
// Observe the same public messages the packaged panel receives. Its
// journal acknowledgments must not erase events before a poll sees them.
window.__webbrainAuthenticatedEvents = [];
chrome.runtime.onMessage.addListener(event => {
if (event.target === 'sidepanel' && event.action === 'agent_update') {
window.__webbrainAuthenticatedEvents.push(event);
if (window.__webbrainAuthenticatedEvents.length > 2048) window.__webbrainAuthenticatedEvents.shift();
}
});
});
} catch (error) {
await page.close().catch(() => {});
throw error;
}
const send = (action, data = {}) => page.evaluate(async ({ action, data }) => {
const response = await chrome.runtime.sendMessage({ target: 'background', action, ...data });
if (action !== 'agent_run_state') return response;
if (!response) return null;
const journal = response.runUi;
// Only final content is returned for private scoring. Event logs retain
// structural evidence, never page contents, prompts, tool args or tokens.
const projectEvent = event => {
const input = event.data || {};
const result = input.result || {};
const data = {};
for (const key of ['name', 'status', 'code', 'outcome', 'attachmentDeliveryState']) {
if (typeof input[key] === 'string' && /^[a-z0-9_:-]{1,100}$/i.test(input[key])) data[key] = input[key];
}
for (const key of ['success', 'done', 'blockedDone', 'noDispatch', 'dispatched', 'deliveryVerified']) {
if (typeof result[key] === 'boolean') data[key] = result[key];
}
if (typeof result.reason === 'string' && /^[a-z0-9_:-]{1,100}$/i.test(result.reason)) data.reason = result.reason;
if (result.outcome === 'success' || result.outcome === 'failure') data.outcome = result.outcome;
for (const key of ['runSucceeded', 'successfulDone']) if (typeof input[key] === 'boolean') data[key] = input[key];
return { seq: event.seq, type: event.type, ts: event.ts, data };
};
const live = (window.__webbrainAuthenticatedEvents || []).filter(event => event.tabId === data.tabId && event.requestId === data.requestId);
const other = (window.__webbrainAuthenticatedEvents || []).filter(event => event.tabId !== data.tabId || event.requestId !== data.requestId);
window.__webbrainAuthenticatedEvents = other;
const events = new Map((journal?.events || []).map(event => [Number(event.seq), projectEvent(event)]));
for (const event of live) if (Number.isFinite(Number(event.seq))) events.set(Number(event.seq), projectEvent(event));
return { ok: response.ok, error: response.error, running: response.running, starting: response.starting,
startingRequestId: response.startingRequestId, runId: response.runId, persistenceDegraded: response.persistenceDegraded,
detachedError: response.detachedError,
runUi: journal ? { requestId: journal.requestId, runId: journal.runId, status: journal.status,
seq: journal.seq, discardedBeforeSeq: journal.discardedBeforeSeq || journal.truncatedBeforeSeq || 0,
finalContent: journal.finalContent, lastError: journal.lastError, runSucceeded: journal.runSucceeded,
attachmentDeliveryState: journal.attachmentDeliveryState, events: [...events.values()].sort((a, b) => a.seq - b.seq) } : null };
}, { action, data });
return { extensionId, page, send,
async metadata() {
// get_providers includes credentials. Project the active configuration
// inside the extension context before any value crosses into Node.
return page.evaluate(async files => {
const manifest = chrome.runtime.getManifest();
const state = await chrome.runtime.sendMessage({ target: 'background', action: 'get_providers' });
const config = state?.providers?.[state.active];
const strings = [];
for (const file of files) {
const response = await fetch(chrome.runtime.getURL(file));
if (!response.ok) throw new Error('Installed extension source is unavailable.');
strings.push(`${file}\n${await response.text()}`);
}
const bytes = new TextEncoder().encode(strings.join('\n'));
const digest = await crypto.subtle.digest('SHA-256', bytes);
const sourceHash = [...new Uint8Array(digest)].map(value => value.toString(16).padStart(2, '0')).join('');
return { extensionId: chrome.runtime.id, extensionVersion: manifest.version,
sourceHash, sourceHashFiles: files, provider: state?.active || null,
model: typeof config?.model === 'string' ? config.model : null,
providerConfigured: !!config && (config.configured === true || config.category === 'cloud' && state.active === 'webbrain_cloud'),
providerCapabilities: { vision: typeof config?.supportsVision === 'boolean' ? config.supportsVision : null,
askStreaming: typeof config?.supportsAskStreaming === 'boolean' ? config.supportsAskStreaming : null },
userAgent: navigator.userAgent };
}, runtimeFiles);
},
async tabId(pageToFind) {
// A fresh marker binds the exact Playwright-created tab even if another
// user's tab already displays the same URL. No arbitrary tab is selected.
const marker = `webbrain-harness-${crypto.randomUUID()}`;
await pageToFind.goto(`about:blank#${marker}`);
return page.evaluate(async markerUrl => {
const matches = (await chrome.tabs.query({})).filter(tab => tab.url === markerUrl);
if (matches.length !== 1) throw new Error('Could not uniquely bind the harness tab.');
return matches[0].id;
}, `about:blank#${marker}`);
},
async close() { await page.close().catch(() => {}); },
async downloads({ marker, after }) {
return page.evaluate(async ({ marker, after }) => {
const rows = await chrome.downloads.search({ query: [marker], state: 'complete', startedAfter: after });
return rows.map(row => ({ filename: row.filename, url: row.url, referrer: row.referrer,
state: row.state, exists: row.exists, startTime: row.startTime, totalBytes: row.totalBytes }));
}, { marker, after });
},
};
}
// Playwright's connectOverCDP browserProcess.close closes its WebSocket, not
// CDP Browser.close (playwright-core/server/chromium/chromium.js). Never close
// the default context of an attached browser: that belongs to the user.
async function detachAttachedBrowser(browser, detach) {
if (detach) await detach(browser);
else await browser.close();
}
function createObserverTransport() {
return { domOnly: true, extensionId: null,
async metadata() { return { extensionId: null, extensionVersion: null, sourceHash: null,
sourceHashFiles: [], provider: null, model: null, providerConfigured: false, providerCapabilities: null }; },
async tabId() { return null; },
async send() { throw new LocalBackendError('DOM-only observer cannot issue WebBrain run commands.', 'blocked', 'observer_runtime_unavailable'); },
async close() {},
};
}
export function createLocalBackend(role, options = {}) {
const config = { ...role };
const timeoutMs = options.timeoutMs || 120000;
const pollMs = options.pollMs || 300;
let context, browser, transport, metadata, profileKey;
let attached = false;
const handles = new Set();
const ownedPages = new Set();
const activeRuns = new Map();
const usedRequests = new Set();
const checkpoints = new Map();
function assertConnected() {
if (!context || !transport) throw new Error('Local backend is not connected.');
}
function ownHandle(handle) {
assertConnected();
if (!handles.has(handle) || handle.page?.isClosed?.()) throw new Error('Handle does not belong to this backend or its tab is closed.');
return handle;
}
async function stateFor(handle, requestId = '') {
const state = await transport.send('agent_run_state', { tabId: handle.tabId, requestId });
if (state?.error || state?.ok === false) throw new Error(safeError(state.error || 'Run state unavailable.'));
return state || {};
}
function matchesRun(state, entry) {
return state?.runUi?.requestId === entry.requestId || state?.startingRequestId === entry.requestId;
}
function result(entry, journal, status, error = null) {
return { status, runId: journal?.runId || entry.runId || entry.requestId,
requestId: entry.requestId, content: safeError(journal?.finalContent || '', 30000),
error: error ? safeError(error) : journal?.lastError ? safeError(journal.lastError) : null,
finalUrl: entry.handle.page.url(), delivered: journal?.runSucceeded === true,
attachmentDeliveryState: journal?.attachmentDeliveryState || '', updates: entry.updates };
}
const backend = {
capabilities: { ...capabilities, activeSteering: config.name !== 'observer', interventions: config.name !== 'observer' },
async connect({ setup = false } = {}) {
if (context) return backend;
try {
assertConfiguration(config);
const chromium = options.chromium || require('playwright').chromium;
if (config.cdpUrl) {
attached = true;
browser = await chromium.connectOverCDP(config.cdpUrl, { timeout: timeoutMs });
const contexts = browser.contexts();
if (contexts.length !== 1) throw new Error('CDP attachment requires one unambiguous browser context.');
[context] = contexts;
} else {
const proposedProfileKey = path.resolve(config.profile).toLowerCase();
if (profileOwners.has(proposedProfileKey)) throw new Error('Dedicated profile is already owned by another local backend.');
profileKey = proposedProfileKey;
profileOwners.add(profileKey);
await fs.mkdir(config.profile, { recursive: true });
const args = [];
if (config.extensionPath && (config.name !== 'observer' || config.requireExtension === true)) {
const extensionPath = path.resolve(config.extensionPath);
const manifest = JSON.parse(await fs.readFile(path.join(extensionPath, 'manifest.json'), 'utf8'));
if (manifest.name !== 'WebBrain' || manifest.background?.service_worker !== 'src/background.js') {
throw new Error('extensionPath must contain the real WebBrain MV3 extension.');
}
args.push(`--disable-extensions-except=${extensionPath}`, `--load-extension=${extensionPath}`);
}
context = await chromium.launchPersistentContext(config.profile, { headless: config.headless === true,
...(config.executablePath ? { executablePath: config.executablePath } : { channel: 'chromium' }),
viewport: { width: 1280, height: 900 }, args, timeout: timeoutMs });
browser = context.browser?.();
}
transport = options.transportFactory ? await options.transportFactory(context, config, timeoutMs)
: config.name === 'observer' && config.requireExtension !== true ? createObserverTransport()
: await createRuntimeTransport(context, config, timeoutMs);
if (transport.domOnly) Object.assign(backend.capabilities, { activeSteering: false, interventions: false, files: false, continuation: false });
metadata = await transport.metadata();
if (!transport.domOnly) {
if (config.expectedVersion && config.expectedVersion !== metadata.extensionVersion) throw new Error('Installed extension version differs from the expected version.');
if (config.expectedBuild && config.expectedBuild !== metadata.sourceHash) throw new Error('Installed extension fingerprint differs from the expected build.');
if (config.sourceHash && config.sourceHash !== metadata.sourceHash) throw new Error('Installed extension source hash differs from the expected source hash.');
}
if (setup && options.fixture?.prepare) {
await options.fixture.prepare({ context, extensionPage: transport.page, send: transport.send });
metadata = await transport.metadata();
}
if (!transport.domOnly) {
// Setup needs access to the real Settings UI before the user can
// select these values. Doctor and every run still require a match.
if (!setup && config.provider && config.provider !== metadata.provider) throw new Error('Installed active provider differs from the requested provider.');
if (!setup && config.model && config.model !== metadata.model) throw new Error('Installed active model differs from the requested model.');
if (config.sourceHash && config.sourceHash !== metadata.sourceHash) throw new Error('Installed extension source hash differs from the expected source hash.');
if (config.expectedVersion && config.expectedVersion !== metadata.extensionVersion) throw new Error('Installed extension version differs from the expected version.');
// expectedBuild identifies the exact reported installed four-file
// fingerprint, not the repository commit or a complete bundle hash.
if (config.expectedBuild && config.expectedBuild !== metadata.sourceHash) throw new Error('Installed extension fingerprint differs from the expected build.');
}
return backend;
} catch (error) {
await backend.close().catch(() => {});
throw new LocalBackendError(error, 'blocked', 'local_connection_not_ready');
}
},
async openSetup() {
assertConnected();
if (config.name !== 'actor' || transport.domOnly || !transport.extensionId) {
throw new LocalBackendError('Only an actor with the verified WebBrain extension can open setup.', 'blocked', 'local_setup_unavailable');
}
const page = await context.newPage();
ownedPages.add(page);
try {
await page.goto(`chrome-extension://${transport.extensionId}/src/ui/settings.html`, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
return { page, extensionId: transport.extensionId, url: page.url() };
} catch (error) {
await page.close().catch(() => {});
ownedPages.delete(page);
throw new LocalBackendError(error, 'blocked', 'local_setup_page_unavailable');
}
},
async doctor() {
assertConnected();
metadata = await transport.metadata();
const expectedMatches = transport.domOnly || (!config.provider || config.provider === metadata.provider)
&& (!config.model || config.model === metadata.model)
&& (!config.sourceHash || config.sourceHash === metadata.sourceHash)
&& (!config.expectedVersion || config.expectedVersion === metadata.extensionVersion)
&& (!config.expectedBuild || config.expectedBuild === metadata.sourceHash);
const ready = expectedMatches && (config.name === 'observer' || metadata.providerConfigured === true);
return { backend: 'local', browser: 'chromium', version: browser?.version?.() || metadata.userAgent,
build: metadata.extensionVersion,
extensionId: metadata.extensionId || transport.extensionId, extensionVersion: metadata.extensionVersion,
sourceHash: metadata.sourceHash, sourceHashFiles: metadata.sourceHashFiles,
sourceHashScope: transport.domOnly ? 'dom-only-observer:extension-not-inspected' : `installed-extension:${(metadata.sourceHashFiles || []).join(',')}`,
provider: metadata.provider, model: metadata.model, providerCapabilities: metadata.providerCapabilities,
capabilities: { ...backend.capabilities },
readiness: ready ? 'ready' : 'not_ready', reason: ready ? null : !expectedMatches
? 'Installed provider, model, version or source no longer matches the requested configuration.'
: 'Active provider is not configured; configure it in the dedicated browser before running.',
ownership: attached ? 'attached' : 'dedicated', inferenceChecked: false };
},
async open(url) {
assertConnected();
const parsed = new URL(url);
if (!['http:', 'https:', 'file:', 'about:'].includes(parsed.protocol)) throw new Error('Unsupported harness page URL.');
const page = await context.newPage();
ownedPages.add(page);
try {
const tabId = await transport.tabId(page);
await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
const handle = { page, tabId, url: page.url() };
handles.add(handle);
return handle;
} catch (error) { await page.close().catch(() => {}); ownedPages.delete(page); throw new Error(safeError(error)); }
},
async run({ task, mode = 'act', handle, requestId = crypto.randomUUID(), onUpdate,
timeoutMs: runTimeoutMs = timeoutMs, continueFrom, attachments } = {}) {
try {
ownHandle(handle);
if (!['ask', 'act', 'dev'].includes(mode)) throw new Error('Unsupported run mode.');
if (config.name === 'observer' && mode !== 'ask') throw new Error('Observer runs must use read-only Ask mode.');
if (transport.domOnly) throw new Error('DOM-only observer cannot issue WebBrain run commands.');
if (!continueFrom && !String(task || '').trim() && !attachments?.length) throw new Error('A run requires a task or supported attachment.');
if (activeRuns.has(handle)) throw new Error('A harness run already owns this tab.');
if (usedRequests.has(requestId)) throw new Error('Request ID has already been submitted; replay is not permitted.');
} catch (error) {
const failure = new LocalBackendError(error, 'blocked', 'local_run_not_ready');
failure.noDispatch = true;
throw failure;
}
const entry = { handle, requestId, runId: null, updates: [], lastSeq: 0 };
activeRuns.set(handle, entry);
let accepted = false;
let dispatched = false;
let rejectionProven = false;
try {
const initialState = await stateFor(handle);
if (initialState.running || initialState.starting) throw new Error('Selected tab already has an active WebBrain run.');
if (continueFrom) {
const prior = initialState.runUi;
const previousId = typeof continueFrom === 'string' ? continueFrom : continueFrom.runId || continueFrom.requestId;
if (!prior || ![prior.runId, prior.requestId].includes(previousId)) throw new Error('Continuation must identify the current run in this exact tab.');
}
const ready = await backend.doctor();
if (ready.readiness !== 'ready') throw new Error(ready.reason);
usedRequests.add(requestId);
if (options.onJournal) await options.onJournal({ type: 'attempt', requestId, tabId: handle.tabId, backend: 'local' });
dispatched = true;
const response = await transport.send(continueFrom ? 'continue_start' : 'chat_start', {
tabId: handle.tabId, requestId, mode, ...(continueFrom ? {} : { text: task, attachments }), locale: 'en' });
if (response?.error || response?.accepted !== true) {
rejectionProven = response?.accepted === false;
throw new Error(response?.error || 'WebBrain did not accept the run.');
}
accepted = true;
if (options.onJournal) await options.onJournal({ type: 'accepted', requestId, tabId: handle.tabId, backend: 'local' });
const deadline = Date.now() + runTimeoutMs;
while (Date.now() < deadline) {
const state = await stateFor(handle, requestId);
const journal = state.runUi;
if (state.detachedError?.requestId === requestId) return result(entry, journal, 'failed', state.detachedError.message);
if (journal?.requestId === requestId) {
entry.runId = journal.runId || state.runId || entry.runId;
for (const event of journal.events || []) {
if (Number(event.seq) <= entry.lastSeq) continue;
if (Number(event.seq) > entry.lastSeq + 1) {
const gap = { type: 'event_gap', seq: Number(event.seq) - 1, requestId, runId: entry.runId,
tabId: handle.tabId, data: { eventsMissing: true } };
entry.updates.push(gap);
if (onUpdate) await onUpdate(gap);
}
const update = { ...safeUpdate(event), requestId, runId: entry.runId, tabId: handle.tabId };
entry.lastSeq = Number(event.seq);
entry.updates.push(update);
if (onUpdate) await onUpdate(update);
}
if (terminalStatuses.has(journal.status)) return result(entry, journal, journal.status);
} else if (state.running || state.starting) {
if (!matchesRun(state, entry)) throw new Error('Selected tab is owned by a different WebBrain run.');
}
await new Promise(resolve => setTimeout(resolve, pollMs));
}
await backend.stop(handle);
return result(entry, null, 'timeout', 'Run timed out; Stop was requested for the matching owned run.');
} catch (error) {
if (accepted) await backend.stop(handle).catch(() => {});
const ambiguous = dispatched && !accepted && !rejectionProven;
if (ambiguous && options.onJournal) {
try { await options.onJournal({ type: 'ambiguous', requestId, tabId: handle.tabId, backend: 'local' }); } catch { /* The original unknown acceptance remains unknown. */ }
}
const failure = new LocalBackendError(error, ambiguous ? 'ambiguous' : accepted ? 'failed' : 'blocked',
accepted ? 'local_run_failed' : ambiguous ? 'local_acceptance_unknown' : 'local_run_not_ready');
failure.noDispatch = !dispatched || rejectionProven;
failure.ambiguous = ambiguous;
throw failure;
} finally { activeRuns.delete(handle); }
},
async inspectSavedRun({ tabId, runId, requestId } = {}) {
assertConnected();
if (!Number.isSafeInteger(tabId) || tabId <= 0 || !requestId) {
throw new LocalBackendError('Saved-run inspection requires its exact positive tabId and requestId.', 'blocked', 'local_saved_run_identity_missing');
}
const state = await transport.send('agent_run_state', { tabId, requestId });
const journal = state?.runUi;
if (state?.error || !journal || journal.requestId !== requestId || runId && journal.runId !== runId) {
throw new LocalBackendError('The installed run journal does not match the saved identity.', 'blocked', 'local_saved_run_identity_mismatch');
}
return { backend: 'local', source: 'installed-extension-run-journal', tabId, requestId,
runId: journal.runId, status: journal.status, active: state.running === true || state.starting === true,
delivered: journal.runSucceeded === true, attachmentDeliveryState: journal.attachmentDeliveryState || '',
updates: (journal.events || []).map(safeUpdate) };
},
async collectDownload({ handle, marker, filename, resourceId, expectedSha256, afterTimestamp, after } = {}) {
ownHandle(handle);
if (config.cdpUrl && !['localhost', '127.0.0.1', '[::1]'].includes(new URL(config.cdpUrl).hostname.toLowerCase())) {
throw new LocalBackendError('Remote CDP download bytes are not available in this machine filesystem.', 'blocked', 'download_remote_filesystem_unavailable');
}
const unsupported = reason => { throw new LocalBackendError(reason, 'unsupported', reason); };
const since = new Date(afterTimestamp || after || 'invalid');
if (!marker || marker.length < 12 || !filename || path.basename(filename) !== filename || !filename.includes(marker)
|| !resourceId || !/^[a-f0-9]{64}$/i.test(expectedSha256 || '') || !Number.isFinite(since.getTime())) {
unsupported('download_exact_identity_missing');
}
if (!transport.downloads) unsupported('download_observation_unavailable');
const belongs = value => {
try {
const url = new URL(value);
return url.searchParams.get('id') === resourceId || decodeURIComponent(url.pathname).split('/').includes(resourceId);
} catch { return false; }
};
const selectedResource = belongs(handle.page.url());
const rows = await transport.downloads({ marker, after: since.toISOString() });
const candidates = rows.filter(row => row.state === 'complete' && row.exists !== false
&& path.basename(row.filename) === filename && new Date(row.startTime).getTime() >= since.getTime());
if (candidates.length !== 1) unsupported('download_unique_completed_file_unproven');
const [download] = candidates;
// CDN URLs can omit Drive IDs. In that case the exact current resource
// URL, unique marked filename and independently known bytes must agree.
if (!selectedResource && !belongs(download.url) && !belongs(download.referrer)) unsupported('download_resource_binding_unproven');
let bytes;
try {
const stat = await fs.stat(download.filename);
if (!stat.isFile() || stat.mtimeMs < since.getTime() - 1500) unsupported('download_file_freshness_unproven');
bytes = await fs.readFile(download.filename);
} catch (error) {
if (error instanceof LocalBackendError) throw error;
throw new LocalBackendError('The observed download could not be read from the local filesystem.', 'blocked', 'download_local_file_unavailable');
}
const sha256 = createHash('sha256').update(bytes).digest('hex');
if (sha256 !== expectedSha256.toLowerCase()) unsupported('download_actual_checksum_mismatch');
return { independent: true, resourceId, sha256, bytes: bytes.length };
},
async stop(runOrHandle) {
assertConnected();
const entry = activeRuns.get(runOrHandle) || [...activeRuns.values()]
.find(value => value.runId === runOrHandle || value.requestId === runOrHandle);
if (!entry) throw new Error('Stop requires a currently owned harness run.');
const state = await stateFor(entry.handle, entry.requestId);
if (!matchesRun(state, entry)) throw new Error('Stop refused because the tab is no longer owned by this run.');
if (!state.running && !state.starting && terminalStatuses.has(state.runUi?.status)) return { ok: true, alreadyTerminal: true };
const response = await transport.send('abort', { tabId: entry.handle.tabId });
if (response?.ok !== true) throw new Error(safeError(response?.error || 'Stop was not acknowledged.'));
return response;
},
async steer({ handle, task }) {
ownHandle(handle);
const entry = activeRuns.get(handle);
if (!entry || !String(task || '').trim()) throw new Error('Steering requires an active owned run and a correction.');
const state = await stateFor(handle, entry.requestId);
if (!matchesRun(state, entry) || !state.running) throw new Error('Steering refused because the matching run is not active.');
const response = await transport.send('chat_steer', { tabId: handle.tabId, requestId: entry.requestId,
messageId: `harness-steer-${crypto.randomUUID()}`, text: task });
if (response?.error || response?.accepted !== true) throw new Error(safeError(response?.error || 'Steering was not accepted.'));
return { accepted: true, requestId: entry.requestId, runId: entry.runId };
},
async checkpoint({ handle, selector, state = 'visible', timeoutMs: checkpointTimeout = timeoutMs, requireActiveRun = false }) {
ownHandle(handle);
if (!selector || !['visible', 'hidden', 'attached', 'detached'].includes(state)) throw new Error('Checkpoint requires a selector and supported state.');
checkpoints.delete(handle);
const deadline = Date.now() + checkpointTimeout;
const entry = requireActiveRun ? activeRuns.get(handle) : null;
const missed = reason => { throw new LocalBackendError(reason, 'blocked', 'local_checkpoint_missed'); };
if (requireActiveRun && !entry) missed('Active checkpoint requires the exact owned harness run.');
const readActive = async () => {
if (activeRuns.get(handle) !== entry) missed('The owned run ended before the active checkpoint.');
const actual = await stateFor(handle, entry.requestId);
if (actual.detachedError?.requestId === entry.requestId
|| actual.runUi?.requestId === entry.requestId && terminalStatuses.has(actual.runUi.status)) {
missed('The owned run became terminal before the active checkpoint.');
}
if ((actual.running || actual.starting) && !matchesRun(actual, entry)) missed('A different run owns the tab at the active checkpoint.');
if (actual.running && matchesRun(actual, entry)) {
entry.runId = actual.runUi?.runId || actual.runId || entry.runId;
return { runtimeRunning: true, requestId: entry.requestId, runId: entry.runId };
}
return null;
};
let timing = {};
if (requireActiveRun) {
while (Date.now() < deadline) {
timing = await readActive();
if (timing) break;
await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, Math.max(1, deadline - Date.now()))));
}
if (!timing) missed('The exact owned run did not begin before the checkpoint deadline.');
}
const remaining = deadline - Date.now();
if (remaining <= 0) missed('The observable checkpoint deadline was missed.');
try { await handle.page.locator(selector).waitFor({ state, timeout: remaining }); }
catch (error) {
if (requireActiveRun) missed('The requested selector state was not reached during the owned run.');
throw error;
}
if (requireActiveRun) {
timing = await readActive();
if (!timing) missed('The owned run stopped before the observable checkpoint resolved.');
}
const checkpoint = { reached: true, selector, state, url: handle.page.url(), at: Date.now(), ...timing };
checkpoints.set(handle, checkpoint);
return checkpoint;
},
async intervene({ handle, kind, selector, text, url, filePath, checkpoint, deltaX = 0, deltaY = 300, value } = {}) {
ownHandle(handle);
if (config.name === 'observer') throw new Error('Observer cannot simulate human mutations.');
const previous = checkpoints.get(handle);
if (previous?.runtimeRunning && activeRuns.get(handle)?.requestId !== previous.requestId) {
throw new LocalBackendError('The run identified by the intervention checkpoint is no longer owned.', 'blocked', 'local_checkpoint_missed');
}
if (checkpoint) await backend.checkpoint({ ...(typeof checkpoint === 'string' ? { selector: checkpoint } : checkpoint),
...(previous?.runtimeRunning ? { requireActiveRun: true } : {}), handle });
const reached = checkpoints.get(handle);
if (!reached || Date.now() - reached.at > 30000 || reached.url !== handle.page.url()) {
throw new Error('Human intervention requires a recent observable checkpoint in this exact tab.');
}
if (reached.runtimeRunning) {
const entry = activeRuns.get(handle);
const actual = entry && await stateFor(handle, reached.requestId);
if (!entry || entry.requestId !== reached.requestId || !actual.running || !matchesRun(actual, entry)
|| terminalStatuses.has(actual.runUi?.status)) {
throw new LocalBackendError('The exact run ended before the checkpoint-based human intervention.', 'blocked', 'local_checkpoint_missed');
}
}
checkpoints.delete(handle);
const action = ({ type: 'fill', draftchange: 'fill', 'draft-change': 'fill', selectionText: 'selection' })[kind] || kind;
if (action === 'navigate') await handle.page.goto(url, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
else if (action === 'reload') await handle.page.reload({ waitUntil: 'domcontentloaded', timeout: timeoutMs });
else if (action === 'click') await handle.page.locator(selector).click();
else if (action === 'fill') await handle.page.locator(selector).fill(text);
else if (action === 'press') await handle.page.locator(selector).press(text);
else if (action === 'upload') await handle.page.locator(selector).setInputFiles(filePath);
else if (action === 'select' && value !== undefined) await handle.page.locator(selector).selectOption(value);
else if (action === 'selection' || action === 'select') {
await handle.page.locator(selector).click();
await handle.page.locator(selector).press(text || 'ControlOrMeta+A');
} else if (action === 'scroll') {
if (![deltaX, deltaY].every(value => Number.isFinite(value) && Math.abs(value) <= 2000)) throw new Error('Human scroll deltas must be finite and bounded to 2000 pixels.');
if (selector) await handle.page.locator(selector).hover();
await handle.page.mouse.wheel(deltaX, deltaY);
}
else throw new Error('Unsupported explicit human intervention.');
return { performed: true, kind, finalUrl: handle.page.url() };
},
async attachFile(filePath) {
const absolute = path.resolve(filePath);
const stat = await fs.stat(absolute);
if (!stat.isFile() || stat.size > 20 * 1024 * 1024) throw new Error('Attachment must be a file no larger than 20 MiB.');
const name = path.basename(absolute);
const extension = path.extname(name).toLowerCase();
const bytes = await fs.readFile(absolute);
if (['.txt', '.md', '.csv', '.json'].includes(extension)) return { name, kind: 'text', textContent: bytes.toString('utf8') };
const mime = { '.pdf': 'application/pdf', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[extension];
if (!mime) throw new Error('Only WebBrain-supported text, image and PDF chat attachments are accepted.');
return { name, kind: extension === '.pdf' ? 'document' : 'image', mimeType: mime, dataUrl: `data:${mime};base64,${bytes.toString('base64')}` };
},
async close({ pendingEntries = [], saveReceipt } = {}) {
for (const entry of [...activeRuns.values()]) await backend.stop(entry.handle).catch(() => {});
// Closing a tab deletes the extension journal. Persist exact terminal
// receipts first; otherwise retain the browser for live reconciliation.
let preserveBrowser = false;
for (const entry of pendingEntries) {
try {
const receipt = await backend.inspectSavedRun(entry);
if (!saveReceipt || receipt.active || !terminalStatuses.has(receipt.status)) throw new Error('Journal is not durably terminal.');
await saveReceipt(entry, receipt);
} catch { preserveBrowser = true; }
}
if (preserveBrowser && !attached) return { preserved: true };
if (!preserveBrowser) for (const page of ownedPages) await page.close().catch(() => {});
ownedPages.clear(); handles.clear(); checkpoints.clear();
await transport?.close?.().catch(() => {});
transport = null;
if (attached && browser) await detachAttachedBrowser(browser, options.detachAttachedBrowser);
else if (context) await context.close();
context = null; browser = null; metadata = null;
if (profileKey) profileOwners.delete(profileKey);
profileKey = null;
},
};
return backend;
}