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
#!/usr/bin/env node
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const pdfExtractionModulePath = path.join(root, 'src', 'chrome', 'src', 'agent', 'pdf-extraction.js');
const pdfToolsModulePath = path.join(root, 'src', 'chrome', 'src', 'agent', 'pdf-tools.js');
const pdfExtractionHostPath = path.join(root, 'src', 'chrome', 'src', 'offscreen', 'pdf-extraction-host.js');
const offscreenHtmlPath = path.join(root, 'src', 'chrome', 'src', 'offscreen', 'offscreen.html');
const pdfjsVendorPath = path.join(root, 'src', 'chrome', 'vendor', 'pdfjs');
function buildSinglePagePdf(text) {
const contents = `BT /F1 24 Tf 72 720 Td (${text}) Tj ET`;
const objects = [
'<< /Type /Catalog /Pages 2 0 R >>',
'<< /Type /Pages /Kids [3 0 R] /Count 1 >>',
'<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>',
'<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>',
`<< /Length ${contents.length} >>\nstream\n${contents}\nendstream`,
];
let pdf = '%PDF-1.4\n';
const offsets = objects.map((body, index) => {
const offset = pdf.length;
pdf += `${index + 1} 0 obj\n${body}\nendobj\n`;
return offset;
});
const xrefOffset = pdf.length;
pdf += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
for (const offset of offsets) pdf += `${String(offset).padStart(10, '0')} 00000 n \n`;
pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`;
return new TextEncoder().encode(pdf);
}
async function testVendoredPdfjsExtractsTextThroughCompatEntryPoints() {
// The modern build builds one DOMMatrix while it evaluates. Node has none,
// and text extraction never renders, so an empty stand-in is enough.
const hadDomMatrix = 'DOMMatrix' in globalThis;
if (!hadDomMatrix) globalThis.DOMMatrix = class DOMMatrix {};
let pdfjs;
try {
pdfjs = await import(pathToFileURL(path.join(pdfjsVendorPath, 'index.mjs')).href);
} finally {
if (!hadDomMatrix) delete globalThis.DOMMatrix;
}
// Node runs PDF.js's main-thread fallback, which imports workerSrc and reads
// WorkerMessageHandler from it, so this also covers worker.mjs's re-export.
pdfjs.GlobalWorkerOptions.workerSrc = pathToFileURL(path.join(pdfjsVendorPath, 'worker.mjs')).href;
const { extractPdfTextFromBytes } = await import(pathToFileURL(pdfExtractionModulePath).href);
const result = await extractPdfTextFromBytes(pdfjs, buildSinglePagePdf('Hello from WebBrain'));
assert.equal(result.success, true);
assert.equal(result.totalPages, 1);
assert.deepEqual(result.pages, ['Hello from WebBrain']);
}
async function testPdfjsCompatFillsMissingBuiltIns() {
// Delete the built-ins in a fresh Node process so the polyfills themselves
// run, whatever this Node version already ships.
const compatUrl = pathToFileURL(path.join(pdfjsVendorPath, 'compat.mjs')).href;
const script = `
import assert from 'node:assert/strict';
for (const Collection of [Map, WeakMap]) {
delete Collection.prototype.getOrInsert;
delete Collection.prototype.getOrInsertComputed;
}
delete Math.sumPrecise;
delete Uint8Array.fromBase64;
delete Uint8Array.prototype.toBase64;
delete Uint8Array.prototype.toHex;
delete Response.prototype.bytes;
const existing = function getOrInsert() { return 'existing'; };
Map.prototype.getOrInsert = existing;
await import(${JSON.stringify(compatUrl)});
assert.equal(Map.prototype.getOrInsert, existing, 'compat must not replace a method the browser has');
assert.equal(Object.getOwnPropertyDescriptor(Math, 'sumPrecise').enumerable, false);
const counts = new Map([['seen', 1]]);
let calls = 0;
assert.equal(counts.getOrInsertComputed('seen', () => { calls++; return 2; }), 1);
assert.equal(counts.getOrInsertComputed('new', (key) => { calls++; return key.length; }), 3);
assert.equal(calls, 1);
assert.throws(() => counts.getOrInsertComputed('x', null), TypeError);
const key = {};
const weak = new WeakMap();
assert.equal(weak.getOrInsert(key, 'first'), 'first');
assert.equal(weak.getOrInsert(key, 'second'), 'first');
assert.equal(weak.getOrInsertComputed({}, () => 'computed'), 'computed');
assert.equal(Math.sumPrecise([0.1, 0.2, 0.3]), 0.6);
assert.equal(Math.sumPrecise([1e20, 0.1, -1e20]), 0.1);
assert.equal(Math.sumPrecise([1e100, 1, -1e100, 1e-100, 1e50, -1, -1e50]), 1e-100);
assert.equal(Math.sumPrecise(new Set([1, 2, 3])), 6);
assert.ok(Object.is(Math.sumPrecise([]), -0));
assert.ok(Object.is(Math.sumPrecise([-0, -0]), -0));
assert.ok(Object.is(Math.sumPrecise([-0, 0]), 0));
assert.equal(Math.sumPrecise([Infinity, 1]), Infinity);
assert.ok(Number.isNaN(Math.sumPrecise([Infinity, -Infinity])));
assert.ok(Number.isNaN(Math.sumPrecise([NaN, 1])));
assert.throws(() => Math.sumPrecise([1, '2']), TypeError);
const hello = new TextEncoder().encode('Hello');
assert.equal(hello.toBase64(), 'SGVsbG8=');
assert.deepEqual(Uint8Array.fromBase64('SGVsbG8='), hello);
const urlSafe = Uint8Array.from([251, 255]);
assert.equal(urlSafe.toBase64(), '+/8=');
assert.equal(urlSafe.toBase64({ alphabet: 'base64url', omitPadding: true }), '-_8');
assert.deepEqual(Uint8Array.fromBase64('-_8', { alphabet: 'base64url' }), urlSafe);
const large = Uint8Array.from({ length: 100003 }, (_, i) => (i * 31) % 256);
assert.deepEqual(Uint8Array.fromBase64(large.toBase64()), large);
assert.equal(Uint8Array.from([0, 1, 254, 255]).toHex(), '0001feff');
assert.deepEqual(await new Response('abc').bytes(), Uint8Array.from([97, 98, 99]));
`;
execFileSync(process.execPath, ['--input-type=module', '--eval', script], { stdio: 'pipe' });
}
async function testMv3PdfExtractionUsesTheSharedOffscreenHost() {
const pdfTools = await readFile(pdfToolsModulePath, 'utf8');
const host = await readFile(pdfExtractionHostPath, 'utf8');
const offscreenHtml = await readFile(offscreenHtmlPath, 'utf8');
assert.match(pdfTools, /ensureOffscreen\(\)/);
assert.match(pdfTools, /PDF_EXTRACTION_READY_MESSAGE/);
assert.match(pdfTools, /type: PDF_EXTRACTION_MESSAGE/);
assert.doesNotMatch(
pdfTools,
/import\(chrome\.runtime\.getURL\('vendor\/pdfjs\//,
'MV3 service workers reject dynamic import() at runtime',
);
assert.match(host, /import\(chrome\.runtime\.getURL\('vendor\/pdfjs\/index\.mjs'\)\)/);
assert.match(host, /chrome\.runtime\.getURL\('vendor\/pdfjs\/worker\.mjs'\)/);
assert.match(host, /extractPdfTextFromBytes/);
assert.match(host, /isTrustedPdfExtractionSender\(sender\)/);
assert.match(offscreenHtml, /<script type="module" src="pdf-extraction-host\.js"><\/script>/);
// The offscreen document outlives any single read, so a failed PDF.js import
// must not be memoized into every later read_pdf.
assert.match(host, /pdfjsPromise\.catch\(\(\) => \{ pdfjsPromise = null; \}\);/);
}
async function testPdfUrlAndSenderBoundaries() {
const {
fetchPdfBytes,
isTrustedPdfExtractionSender,
normalizePdfUrl,
} = await import(pathToFileURL(pdfExtractionModulePath).href);
const runtime = {
id: 'trusted-extension',
getURL: path => `chrome-extension://trusted-extension/${path}`,
};
const backgroundUrl = runtime.getURL('src/background.js');
assert.equal(isTrustedPdfExtractionSender({ id: runtime.id, url: backgroundUrl }, runtime), true);
assert.equal(isTrustedPdfExtractionSender({ id: runtime.id, url: runtime.getURL('src/ui/settings.html') }, runtime), false);
assert.equal(isTrustedPdfExtractionSender({ id: runtime.id, url: backgroundUrl, tab: { id: 7 } }, runtime), false);
assert.equal(isTrustedPdfExtractionSender({ id: 'other-extension', url: backgroundUrl }, runtime), false);
// The trusted path follows the manifest, so renaming the service worker
// entry cannot silently start rejecting every extraction.
const renamedRuntime = {
...runtime,
getManifest: () => ({ background: { service_worker: 'src/sw/main.js' } }),
};
assert.equal(isTrustedPdfExtractionSender(
{ id: runtime.id, url: renamedRuntime.getURL('src/sw/main.js') }, renamedRuntime), true);
assert.equal(isTrustedPdfExtractionSender(
{ id: runtime.id, url: backgroundUrl }, renamedRuntime), false);
assert.equal(normalizePdfUrl('https://example.test/document.pdf'), 'https://example.test/document.pdf');
assert.equal(normalizePdfUrl('file:///tmp/document.pdf'), 'file:///tmp/document.pdf');
assert.throws(() => normalizePdfUrl('data:application/pdf;base64,JVBERg=='), /must use http.*https.*file/i);
assert.throws(() => normalizePdfUrl('javascript:alert(1)'), /must use http.*https.*file/i);
// A PDF tab owned by the native MIME handler reports our viewer page as its
// URL; read_pdf falls back to that, so the real URL must be unwrapped.
const handlerUrl = `${runtime.getURL('src/ui/pdf-handler.html')}?url=${encodeURIComponent('https://example.test/paper.pdf')}&tabId=7`;
assert.equal(normalizePdfUrl(handlerUrl, runtime), 'https://example.test/paper.pdf');
assert.throws(
() => normalizePdfUrl(`${runtime.getURL('src/ui/settings.html')}?url=${encodeURIComponent('https://example.test/x.pdf')}`, runtime),
/must use http.*https.*file/i,
'Only the PDF handler page may unwrap an inner URL.');
assert.throws(
() => normalizePdfUrl(`${runtime.getURL('src/ui/pdf-handler.html')}?url=${encodeURIComponent('javascript:alert(1)')}`, runtime),
/must use http.*https.*file/i,
'An unwrapped inner URL must still pass the scheme allowlist.');
// The viewer page follows the manifest too, so renaming it cannot start
// rejecting our own PDF tabs with a bogus scheme error.
const renamedHandlerRuntime = {
...runtime,
getManifest: () => ({ mime_types_handler: { 'application/pdf': { handler_url: 'src/ui/viewer.html' } } }),
};
assert.equal(
normalizePdfUrl(
`${runtime.getURL('src/ui/viewer.html')}?url=${encodeURIComponent('https://example.test/paper.pdf')}&tabId=7`,
renamedHandlerRuntime),
'https://example.test/paper.pdf');
assert.throws(
() => normalizePdfUrl(handlerUrl, renamedHandlerRuntime),
/must use http.*https.*file/i,
'Only the manifest-declared viewer page may unwrap an inner URL.');
let fetchCalls = 0;
const originalFetch = globalThis.fetch;
globalThis.fetch = async () => {
fetchCalls += 1;
throw new Error('disallowed URL reached fetch');
};
try {
await assert.rejects(fetchPdfBytes('chrome-extension://trusted-extension/private.pdf'), /must use http.*https.*file/i);
assert.equal(fetchCalls, 0, 'Disallowed schemes must be rejected before fetch.');
} finally {
globalThis.fetch = originalFetch;
}
}
async function testPdfExtractionPreservesBoundedPageMetadataAndTruncation() {
const { extractPdfTextFromBytes } = await import(pathToFileURL(pdfExtractionModulePath).href);
const cleanedPages = [];
const pageTexts = new Map([
[1, ['First', 'page']],
[2, ['x'.repeat(1200)]],
]);
const pdfjs = {
getDocument({ data, verbosity }) {
assert.deepEqual(Array.from(data), [1, 2, 3]);
assert.equal(verbosity, 0);
return {
promise: Promise.resolve({
numPages: 2,
getMetadata: async () => ({ info: { Title: 'Fixture PDF' } }),
getPage: async pageNumber => ({
getTextContent: async () => ({
items: pageTexts.get(pageNumber).map(str => ({ str })),
}),
cleanup: () => cleanedPages.push(pageNumber),
}),
}),
};
},
};
const result = await extractPdfTextFromBytes(pdfjs, new Uint8Array([1, 2, 3]), {
fromPage: 1,
toPage: 2,
maxChars: 1000,
});
assert.equal(result.title, 'Fixture PDF');
assert.equal(result.totalPages, 2);
assert.equal(result.fromPage, 1);
assert.equal(result.toPage, 2);
assert.equal(result.pageCount, 2);
assert.equal(result.truncated, true);
assert.equal(result.byteLength, 3);
assert.match(result.pages[1], /page truncated/);
assert.deepEqual(cleanedPages, [1, 2]);
}
async function testPdfFacadeRequestsOffscreenExtractionAndPreservesClaudeBytes() {
const originalChrome = globalThis.chrome;
const originalFetch = globalThis.fetch;
const messages = [];
let readyAttempts = 0;
let fetchCalls = 0;
globalThis.chrome = {
offscreen: { hasDocument: async () => true },
runtime: {
sendMessage: async message => {
messages.push(message);
if (message.type === 'offscreen-pdf-extract-ready') {
readyAttempts += 1;
return readyAttempts < 3 ? undefined : { ok: true, ready: true };
}
return {
ok: true,
result: {
success: true,
title: 'Facade fixture',
totalPages: 1,
fromPage: 1,
toPage: 1,
pageCount: 1,
pages: ['fixture text'],
hasExtractableText: true,
truncated: false,
byteLength: 3,
...(message.options?.includeBase64 ? { _pdfBase64: 'BAUG' } : {}),
},
};
},
},
};
globalThis.fetch = async () => {
fetchCalls += 1;
throw new Error('The service-worker facade must not fetch the PDF.');
};
try {
const { buildClaudeDocumentBlock, extractPdfText } = await import(pathToFileURL(pdfToolsModulePath).href);
const plainResult = await extractPdfText('https://example.test/document.pdf', {
fromPage: 2,
toPage: 4,
maxChars: 5000,
});
assert.equal(plainResult.title, 'Facade fixture');
assert.equal(plainResult._pdfBase64, undefined);
const claudeResult = await extractPdfText('https://example.test/document.pdf', {
includeDocument: true,
});
assert.equal(claudeResult._pdfBase64, 'BAUG');
assert.equal(buildClaudeDocumentBlock(claudeResult._pdfBase64, 'fixture.pdf').source.data, 'BAUG');
assert.equal(fetchCalls, 0);
assert.deepEqual(messages, [
{ type: 'offscreen-pdf-extract-ready' },
{ type: 'offscreen-pdf-extract-ready' },
{ type: 'offscreen-pdf-extract-ready' },
{
type: 'offscreen-pdf-extract',
url: 'https://example.test/document.pdf',
options: { fromPage: 2, toPage: 4, maxChars: 5000, includeBase64: false },
},
{ type: 'offscreen-pdf-extract-ready' },
{
type: 'offscreen-pdf-extract',
url: 'https://example.test/document.pdf',
options: { fromPage: undefined, toPage: undefined, maxChars: undefined, includeBase64: true },
},
]);
} finally {
if (originalChrome === undefined) delete globalThis.chrome;
else globalThis.chrome = originalChrome;
globalThis.fetch = originalFetch;
}
}
const tests = [
['MV3 PDF extraction uses the shared offscreen host', testMv3PdfExtractionUsesTheSharedOffscreenHost],
['PDF extraction rejects unsafe URLs and untrusted senders', testPdfUrlAndSenderBoundaries],
['PDF extraction preserves bounded page metadata and truncation', testPdfExtractionPreservesBoundedPageMetadataAndTruncation],
['PDF facade waits for host readiness and reuses Claude bytes', testPdfFacadeRequestsOffscreenExtractionAndPreservesClaudeBytes],
['Vendored PDF.js extracts text through the compat entry points', testVendoredPdfjsExtractsTextThroughCompatEntryPoints],
['PDF.js compat fills missing built-ins without replacing native ones', testPdfjsCompatFillsMissingBuiltIns],
];
let failed = 0;
for (const [name, run] of tests) {
try {
await run();
console.log(` ✓ ${name}`);
} catch (error) {
failed += 1;
console.log(` ✗ ${name}\n ${error.message}`);
}
}
console.log(`\n${tests.length - failed} PDF read tests passed, ${failed} failed`);
process.exitCode = failed ? 1 : 0;