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';
const TERMINAL = new Set(['completed', 'failed', 'aborted', 'needs_user_input']);
const TERMINAL_SCHEDULED = new Set(['completed', 'failed', 'cancelled', 'canceled', 'needs_user_input']);
export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
export class WebBrainCloudClient {
constructor({ apiKey, baseUrl = 'https://webbrain.cloud', fetchImpl = globalThis.fetch }) {
if (!apiKey) throw new Error('WEBBRAIN_API_KEY is required.');
this.apiKey = apiKey;
this.baseUrl = String(baseUrl).replace(/\/$/, '');
this.fetch = fetchImpl;
}
async request(method, route, body) {
const response = await this.fetch(`${this.baseUrl}${route}`, {
method,
headers: {
authorization: `Bearer ${this.apiKey}`,
...(body === undefined ? {} : { 'content-type': 'application/json' }),
},
body: body === undefined ? undefined : JSON.stringify(body),
});
const text = await response.text();
let value;
try { value = text ? JSON.parse(text) : null; } catch { value = text; }
if (!response.ok) {
const error = new Error(value?.error || `WebBrain Cloud returned HTTP ${response.status}.`);
error.status = response.status;
error.body = value;
throw error;
}
return value;
}
async createIncognitoBrowser({ name, settings = {} }) {
const response = await this.request('POST', '/api/browser-sessions', {
type: 'incognito',
display_name: name,
webbrain_config: {
schema: 'webbrain-config/1',
settings,
},
});
return {
...response.browser_session,
webbrain_config_result: response.webbrain_config_result || null,
};
}
async waitForBrowser(sessionId, { timeoutMs = 600_000, intervalMs = 4_000 } = {}) {
const deadline = Date.now() + timeoutMs;
let latest = null;
while (Date.now() < deadline) {
const response = await this.request('GET', `/api/browser-sessions/${encodeURIComponent(sessionId)}`);
latest = response.browser_session;
if (latest.status === 'ready' && latest.runtime_ready !== false) return latest;
if (['failed', 'ended'].includes(latest.status)) {
throw new Error(`Browser provisioning ${latest.status}: ${latest.error || 'unknown error'}`);
}
await sleep(intervalMs);
}
throw new Error(`Browser did not become ready within ${timeoutMs}ms (last status: ${latest?.status || 'unknown'}).`);
}
async startRun(sessionId, {
task, mode = 'act', tabId, outputSchema, timeoutMs, capture = 'video', apiMutationsAllowed = false,
}) {
return await this.request('POST', `/api/browser-sessions/${encodeURIComponent(sessionId)}/runs`, {
task,
mode,
...(tabId === undefined || tabId === null ? {} : { tab_id: tabId }),
...(outputSchema === undefined || outputSchema === null ? {} : { output_schema: outputSchema }),
...(apiMutationsAllowed ? { api_mutations_allowed: true } : {}),
timeout_ms: timeoutMs,
capture,
wait: false,
});
}
#isAnsweredClarification(run, answeredClarifyIds) {
if (!answeredClarifyIds?.size || run.status !== 'needs_user_input') return false;
const pending = run.pending_input || run.pendingInput || {};
const clarifyId = String(pending.clarify_id || pending.clarifyId || '');
return Boolean(clarifyId) && answeredClarifyIds.has(clarifyId);
}
async respondToRun(sessionId, runId, clarifyId, answer) {
return await this.request(
'POST',
`/api/browser-sessions/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(runId)}/responses`,
{ clarify_id: clarifyId, answer },
);
}
async waitForRun(sessionId, runId, { timeoutMs = 900_000, intervalMs = 3_000, answeredClarifyIds = null } = {}) {
const deadline = Date.now() + timeoutMs;
let latest = null;
while (Date.now() < deadline) {
latest = await this.request(
'GET',
`/api/browser-sessions/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(runId)}`,
);
// A run row read right after an answer may not have flipped back to
// `running` yet. Re-reporting a clarification we already answered is a
// stale read, not a handoff — keep polling instead of grading it stuck.
if (TERMINAL.has(latest.status) && !this.#isAnsweredClarification(latest, answeredClarifyIds)) {
return latest;
}
await sleep(intervalMs);
}
const error = new Error(`Cloud run did not finish within ${timeoutMs}ms.`);
error.latest = latest;
throw error;
}
async exportTrace(sessionId, runId) {
return await this.request(
'GET',
`/api/browser-sessions/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(runId)}/export`,
);
}
async listScheduledJobs(sessionId, jobIds) {
const ids = [...new Set((jobIds || []).map(value => String(value || '').trim()).filter(Boolean))];
if (!ids.length) throw new Error('At least one scheduled job id is required.');
const query = ids.map(id => `job_id=${encodeURIComponent(id)}`).join('&');
return await this.request(
'GET',
`/api/browser-sessions/${encodeURIComponent(sessionId)}/scheduled-jobs?${query}`,
);
}
async waitForScheduledJobs(sessionId, jobIds, { timeoutMs = 600_000, intervalMs = 3_000 } = {}) {
const ids = [...new Set((jobIds || []).map(value => String(value || '').trim()).filter(Boolean))];
if (!ids.length) throw new Error('At least one scheduled job id is required.');
const deadline = Date.now() + timeoutMs;
let latest = { jobs: [] };
while (Date.now() < deadline) {
const response = await this.listScheduledJobs(sessionId, ids);
const byId = new Map((response.jobs || []).map(job => [String(job.id), job]));
latest = { jobs: ids.map(id => byId.get(id)).filter(Boolean) };
if (
latest.jobs.length === ids.length
&& latest.jobs.every(job => TERMINAL_SCHEDULED.has(String(job.status || '').toLowerCase()))
) return latest;
await sleep(intervalMs);
}
const error = new Error(`Scheduled jobs did not finish within ${timeoutMs}ms.`);
error.latest = latest;
throw error;
}
async destroyBrowser(sessionId) {
return await this.request('DELETE', `/api/browser-sessions/${encodeURIComponent(sessionId)}`);
}
async downloadsAccess(sessionId) {
return await this.request(
'POST',
`/api/browser-sessions/${encodeURIComponent(sessionId)}/downloads-access`,
{},
);
}
async downloadCapture(sessionId, runId, destination, { timeoutMs = 90_000 } = {}) {
const access = await this.downloadsAccess(sessionId);
const expected = `webbrain-ci-${runId}.webm`;
const deadline = Date.now() + timeoutMs;
const headers = {
authorization: `Basic ${Buffer.from(`${access.username}:${access.password}`).toString('base64')}`,
};
while (Date.now() < deadline) {
const listingResponse = await this.fetch(access.url, {
headers: { ...headers, accept: 'application/json' },
});
if (listingResponse.ok) {
const listing = await listingResponse.json();
const entry = listing.entries?.find((candidate) => candidate.name === expected);
if (entry) {
const fileResponse = await this.fetch(new URL(encodeURIComponent(expected), access.url), { headers });
if (!fileResponse.ok) throw new Error(`Capture download returned HTTP ${fileResponse.status}.`);
await fs.mkdir(path.dirname(destination), { recursive: true });
await fs.writeFile(destination, Buffer.from(await fileResponse.arrayBuffer()), { mode: 0o600 });
return { name: expected, size: Number(entry.size) || 0 };
}
}
await sleep(2_000);
}
throw new Error(`Capture ${expected} was not synchronized within ${timeoutMs}ms.`);
}
}
export class GnippetsE2EClient {
constructor({ baseUrl, controlToken, fetchImpl = globalThis.fetch }) {
this.baseUrl = String(baseUrl).replace(/\/$/, '');
this.controlToken = controlToken;
this.fetch = fetchImpl;
}
async request(method, route, body) {
const response = await this.fetch(`${this.baseUrl}${route}`, {
method,
headers: {
authorization: `Bearer ${this.controlToken}`,
accept: 'application/json',
'user-agent': 'Mozilla/5.0 (compatible; WebBrainCloudE2E/1.0; +https://webbrain.cloud)',
...(body === undefined ? {} : { 'content-type': 'application/json' }),
},
body: body === undefined ? undefined : JSON.stringify(body),
});
const text = await response.text();
let value;
try { value = text ? JSON.parse(text) : {}; } catch { value = {}; }
if (!response.ok) {
const header = (name) => String(response.headers?.get?.(name) || 'unknown')
.replace(/\s+/g, ' ')
.slice(0, 160);
let preview = text;
if (this.controlToken) preview = preview.split(this.controlToken).join('[redacted]');
preview = preview
.replace(/Bearer\s+[^\s<]+/gi, 'Bearer [redacted]')
.replace(/\s+/g, ' ')
.trim()
.slice(0, 240);
const diagnostics = {
server: header('server'),
cf_ray: header('cf-ray'),
cf_mitigated: header('cf-mitigated'),
content_type: header('content-type'),
body_preview: preview,
};
const summary = Object.entries(diagnostics)
.filter(([, diagnostic]) => diagnostic && diagnostic !== 'unknown')
.map(([name, diagnostic]) => `${name}=${diagnostic}`)
.join('; ');
const error = new Error(
value.error || `Gnippets E2E returned HTTP ${response.status}${summary ? ` (${summary})` : ''}.`,
);
error.status = response.status;
error.body = diagnostics;
throw error;
}
return value;
}
createRun(scenario) {
if (!this.controlToken) throw new Error('GNIPPETS_E2E_CONTROL_TOKEN is required for isolated Gnippets scenarios.');
return this.request('POST', '/api/e2e/v1/runs', { scenario });
}
getRun(runId) {
return this.request('GET', `/api/e2e/v1/runs/${encodeURIComponent(runId)}`);
}
deleteRun(runId) {
return this.request('DELETE', `/api/e2e/v1/runs/${encodeURIComponent(runId)}`);
}
}