Skip to content

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

10.1 KB
Raw Blame
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)}`);
  }
}