Skip to content

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

fix(traces): assemble full exports outside runtime messaging

Codex release-state testb6efa1bd1860
diff --git a/docs/trace-format-compatibility.md b/docs/trace-format-compatibility.md
index 236474fc4..a52d1fbdb 100644
--- a/docs/trace-format-compatibility.md
+++ b/docs/trace-format-compatibility.md
@@ -16,7 +16,7 @@ WebBrain's trace data has three independent version layers:
Tool events may include an optional `data.outcome` summary containing bounded dispatch, application, provider, error, and CAPTCHA-gate diagnostics. In lossless recordings, this summary survives the content-budget marker, while answer tokens, cookies, provider keys, and form inputs are excluded from the summary. Readers should still honor `_truncated` and `losslessBudgetOmitted`; the summary does not reconstruct discarded content.
-`/export --traces --full` exports the stored conversation through the existing `webbrain-trace/1` session envelope, including stored screenshots. It adds no Markdown preview or turn-count truncation. Recording-time omissions and privacy projections remain explicit.
+`/export --traces --full` exports the stored conversation through the existing `webbrain-trace/1` session envelope, including stored screenshots. It adds no Markdown preview or turn-count truncation. Recording-time omissions and privacy projections remain explicit. The side panel reads the shared trace database and assembles the download locally; only the session identity crosses runtime messaging, so screenshot-heavy exports do not hit the browser message-size limit.
Treat a missing or malformed `traceFormatVersion` as the legacy baseline. Keep
missing optional fields harmless. Reject a numeric `traceFormatVersion` newer
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index d096d8b9b..60305e5cb 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -83,7 +83,6 @@ import { buildTerminalRuntimeEvent, enqueueCloudRuntimeEvent, flushCloudRuntimeO
import { buildShareGenerationItem, enqueueShareGeneration, flushShareOutbox, purgeShareGenerations } from '../trace/webbrain-share-outbox.js';
import { normalizeRuntimeTraceConfig } from '../trace/runtime-config.js';
import { tracesToMarkdown } from './trace-export.js';
-import { exportRecordedSession } from '../trace/session-export.js';
import { hcaptchaParamError } from './captcha-hcaptcha-providers.js';
import { AWS_WAF_COOKIE_PATHS, describeAwsWafObservation, getCaptchaCapabilities, prepareNativeCaptchaTasks, solveNativeCaptchaTasks } from './captcha-native-providers.js';
import { applyNativeCaptchaSolution, captureCaptchaDocuments, captchaAnswerDocumentStatus } from './captcha-solution-application.js';
@@ -28527,7 +28526,8 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
* this.conversations. Hydrates first so it works across service-worker restarts.
* Returns { ok, markdown|null, turnCount, reason }: reason 'no-conversation', or
* 'no-traces' (tracing off / nothing recorded) so the UI can say so instead of
- * downloading an empty-but-official-looking file.
+ * downloading an empty-but-official-looking file. Full exports return a small
+ * session descriptor so the UI can assemble the file directly from IndexedDB.
*/
async exportTraces(tabId, { full = false } = {}) {
await this._hydrate(tabId);
@@ -28535,8 +28535,10 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
if (!conversationId) return { ok: true, markdown: null, turnCount: 0, reason: 'no-conversation' };
if (full) {
try {
- const exported = await exportRecordedSession(trace, conversationId, chrome.runtime.getManifest().version || '');
- return { ok: true, ...exported, ...(exported.turnCount ? {} : { reason: 'no-traces' }) };
+ // Extension pages share this IndexedDB. Send only its identity: full
+ // sessions with screenshots can exceed the runtime message size limit.
+ await trace.flushPendingWrites();
+ return { ok: true, sessionId: conversationId };
} catch (error) { return { ok: false, error: String(error?.message || error) }; }
}
// Cap matching runs for this conversation only (not a global newest-N).
diff --git a/src/chrome/src/trace/recorder.js b/src/chrome/src/trace/recorder.js
index 8abd1a618..9f745a970 100644
--- a/src/chrome/src/trace/recorder.js
+++ b/src/chrome/src/trace/recorder.js
@@ -1080,6 +1080,13 @@ export async function repairStaleRuns({
// ----- Reader API (used by traces.html) --------------------------------------
+// Before another extension context reads the database, settle the writes that
+// were already queued. Snapshot the queue so an active run cannot postpone an
+// export indefinitely by continuing to record new events.
+export async function flushPendingWrites() {
+ await Promise.all([..._runWriteQueues.values()]);
+}
+
export async function listRuns({ limit = 500, conversationId = null } = {}) {
const db = await openDB();
const store = tx(db, ['runs'], 'readonly').objectStore('runs');
diff --git a/src/chrome/src/trace/session-export.js b/src/chrome/src/trace/session-export.js
index 273a8152b..8cf66b6ca 100644
--- a/src/chrome/src/trace/session-export.js
+++ b/src/chrome/src/trace/session-export.js
@@ -1,6 +1,8 @@
import { buildTraceExportPayload } from './export-contract.js';
import { sanitizeTraceExport } from '../agent/trace-export.js';
+// Run in the downloading extension page, never send this JSON through runtime
+// messaging: screenshots can make it larger than the browser message limit.
// Export the stored session without the Markdown preview's text/run limits.
// This deliberately preserves recording-time omission markers: an export
// cannot recover content that was never retained by the recorder.
diff --git a/src/chrome/src/ui/sidepanel.js b/src/chrome/src/ui/sidepanel.js
index 1ee718891..e8149efa0 100644
--- a/src/chrome/src/ui/sidepanel.js
+++ b/src/chrome/src/ui/sidepanel.js
@@ -8568,6 +8568,13 @@ async function parseSlashCommands(text, tabId = currentTabId, options = {}) {
let res;
try {
res = await sendToBackground('export_traces', { tabId, full: optionValues.has('--full') });
+ if (optionValues.has('--full') && res?.ok && res.sessionId) {
+ const [store, { exportRecordedSession }] = await Promise.all([
+ import('../trace/recorder.js'),
+ import('../trace/session-export.js'),
+ ]);
+ res = { ok: true, ...await exportRecordedSession(store, res.sessionId, chrome.runtime.getManifest().version || '') };
+ }
} catch (e) {
addPersistentSlashMessage(`${t('sp.export_traces.error')} (${e?.message || e})`);
return '';
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index f6185c5d1..ecf037836 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -78,7 +78,6 @@ import { buildTerminalRuntimeEvent, enqueueCloudRuntimeEvent, flushCloudRuntimeO
import { buildShareGenerationItem, enqueueShareGeneration, flushShareOutbox, purgeShareGenerations } from '../trace/webbrain-share-outbox.js';
import { normalizeRuntimeTraceConfig } from '../trace/runtime-config.js';
import { tracesToMarkdown } from './trace-export.js';
-import { exportRecordedSession } from '../trace/session-export.js';
import { hcaptchaParamError } from './captcha-hcaptcha-providers.js';
import { AWS_WAF_COOKIE_PATHS, describeAwsWafObservation, getCaptchaCapabilities, prepareNativeCaptchaTasks, solveNativeCaptchaTasks } from './captcha-native-providers.js';
import { applyNativeCaptchaSolution, captureCaptchaDocuments, captchaAnswerDocumentStatus } from './captcha-solution-application.js';
@@ -26085,7 +26084,8 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
* this.conversations. Hydrates first so it works across background restarts.
* Returns { ok, markdown|null, turnCount, reason }: reason 'no-conversation', or
* 'no-traces' (tracing off / nothing recorded) so the UI can say so instead of
- * downloading an empty-but-official-looking file.
+ * downloading an empty-but-official-looking file. Full exports return a small
+ * session descriptor so the UI can assemble the file directly from IndexedDB.
*/
async exportTraces(tabId, { full = false } = {}) {
await this._hydrate(tabId);
@@ -26093,8 +26093,10 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (!conversationId) return { ok: true, markdown: null, turnCount: 0, reason: 'no-conversation' };
if (full) {
try {
- const exported = await exportRecordedSession(trace, conversationId, browser.runtime.getManifest().version || '');
- return { ok: true, ...exported, ...(exported.turnCount ? {} : { reason: 'no-traces' }) };
+ // Extension pages share this IndexedDB. Send only its identity: full
+ // sessions with screenshots can exceed the runtime message size limit.
+ await trace.flushPendingWrites();
+ return { ok: true, sessionId: conversationId };
} catch (error) { return { ok: false, error: String(error?.message || error) }; }
}
// Cap matching runs for this conversation only (not a global newest-N).
diff --git a/src/firefox/src/trace/recorder.js b/src/firefox/src/trace/recorder.js
index e86264322..740a96136 100644
--- a/src/firefox/src/trace/recorder.js
+++ b/src/firefox/src/trace/recorder.js
@@ -1062,6 +1062,13 @@ export async function repairStaleRuns({
// ----- Reader API (used by traces.html) --------------------------------------
+// Before another extension context reads the database, settle the writes that
+// were already queued. Snapshot the queue so an active run cannot postpone an
+// export indefinitely by continuing to record new events.
+export async function flushPendingWrites() {
+ await Promise.all([..._runWriteQueues.values()]);
+}
+
export async function listRuns({ limit = 500, conversationId = null } = {}) {
const db = await openDB();
const store = tx(db, ['runs'], 'readonly').objectStore('runs');
diff --git a/src/firefox/src/trace/session-export.js b/src/firefox/src/trace/session-export.js
index 273a8152b..8cf66b6ca 100644
--- a/src/firefox/src/trace/session-export.js
+++ b/src/firefox/src/trace/session-export.js
@@ -1,6 +1,8 @@
import { buildTraceExportPayload } from './export-contract.js';
import { sanitizeTraceExport } from '../agent/trace-export.js';
+// Run in the downloading extension page, never send this JSON through runtime
+// messaging: screenshots can make it larger than the browser message limit.
// Export the stored session without the Markdown preview's text/run limits.
// This deliberately preserves recording-time omission markers: an export
// cannot recover content that was never retained by the recorder.
diff --git a/src/firefox/src/ui/sidepanel.js b/src/firefox/src/ui/sidepanel.js
index e0128c73c..4b3ae47c0 100644
--- a/src/firefox/src/ui/sidepanel.js
+++ b/src/firefox/src/ui/sidepanel.js
@@ -8264,6 +8264,13 @@ async function parseSlashCommands(text, tabId = currentTabId, options = {}) {
let res;
try {
res = await sendToBackground('export_traces', { tabId, full: optionValues.has('--full') });
+ if (optionValues.has('--full') && res?.ok && res.sessionId) {
+ const [store, { exportRecordedSession }] = await Promise.all([
+ import('../trace/recorder.js'),
+ import('../trace/session-export.js'),
+ ]);
+ res = { ok: true, ...await exportRecordedSession(store, res.sessionId, browser.runtime.getManifest().version || '') };
+ }
} catch (e) {
addPersistentSlashMessage(`${t('sp.export_traces.error')} (${e?.message || e})`);
return '';
diff --git a/test/trace-full-export.mjs b/test/trace-full-export.mjs
index 00f3c45cf..e38a47abd 100644
--- a/test/trace-full-export.mjs
+++ b/test/trace-full-export.mjs
@@ -88,6 +88,133 @@ for (const [build, engine] of [['chrome', chromium], ['firefox', firefox]]) {
for (const command of ['/export --full', '/export --config --full', '/export --traces --full extra']) assert.ok(context.parse(command).error, command);
});
+ test(`${build}: full export returns a small descriptor only after pending writes settle`, async () => {
+ const { Agent } = await import(`../src/${build}/src/agent/agent.js`);
+ // Exercise the real method with a controlled recorder queue. No database
+ // payload should be read or assembled in the background full-export path.
+ let release;
+ let hydrated = false;
+ const context = vm.createContext({ trace: { flushPendingWrites: () => new Promise(resolve => { release = resolve; }) } });
+ const exportTraces = vm.runInContext(`({${Agent.prototype.exportTraces.toString()}}).exportTraces`, context);
+ const agent = { conversationIds: new Map(), async _hydrate(tabId) {
+ hydrated = true; this.conversationIds.set(tabId, 'session');
+ } };
+ let finished = false;
+ const pending = exportTraces.call(agent, 1, { full: true }).then(result => { finished = true; return result; });
+ await new Promise(resolve => setImmediate(resolve));
+ assert.equal(hydrated, true); assert.equal(finished, false);
+ release();
+ assert.deepEqual(JSON.parse(JSON.stringify(await pending)), { ok: true, sessionId: 'session' });
+ });
+
+ test(`${build}: slash export downloads over 64 MiB from shared IndexedDB without a large message`, async () => {
+ const source = await readFile(`src/${build}/src/ui/sidepanel.js`, 'utf8');
+ const start = source.indexOf(" if (command.value === '/export' && action === 'traces') {");
+ const end = source.indexOf(" if (command.value === '/export' && action === 'conversation') {", start);
+ assert.ok(start >= 0 && end > start);
+ const harness = `export async function run(response, full = true) {
+ const tabId = 1, command = { value: '/export' }, action = 'traces', optionValues = new Set(full ? ['--full'] : []);
+ const sendToBackground = async () => response === undefined ? globalThis.backgroundExport() : response;
+ const t = key => key, addPersistentSlashMessage = message => globalThis.exportMessages.push(message);
+ ${source.slice(start, end)}
+ }`;
+ const browser = await engine.launch();
+ try {
+ const context = await browser.newContext({ acceptDownloads: true });
+ await context.route('http://trace-download.local/**', async route => {
+ const path = new URL(route.request().url()).pathname;
+ if (path === '/') return route.fulfill({ contentType: 'text/html', body: '<!doctype html>' });
+ if (path === '/src/ui/export-harness.js') return route.fulfill({ contentType: 'text/javascript', body: harness });
+ const file = resolve(`src/${build}`, '.' + path);
+ if (!file.startsWith(resolve(`src/${build}`) + '/')) return route.abort();
+ await route.fulfill({ contentType: 'text/javascript', body: await readFile(file) });
+ });
+ const writer = await context.newPage();
+ await writer.goto('http://trace-download.local/');
+ await writer.evaluate(async () => {
+ globalThis.chrome = globalThis.browser = { storage: { local: { get: async () => ({ tracingEnabled: true, losslessTrace: true }) } } };
+ const trace = await import('/src/trace/recorder.js');
+ const { Agent } = await import('/src/agent/agent.js');
+ globalThis.exportAgent = new Agent({ getActive: () => ({ promptTier: 'full' }) });
+ exportAgent._hydrate = async tabId => exportAgent.conversationIds.set(tabId, 'large-session');
+ await trace.listRuns(); // Initialize the shared database schema.
+ const runId = 'large-run';
+ // 200 stored screenshots, 256 KiB each: portable base64 JSON >64 MiB.
+ const db = await new Promise((resolve, reject) => {
+ const req = indexedDB.open('webbrain_traces', 2);
+ req.onsuccess = () => resolve(req.result); req.onerror = () => reject(req.error);
+ });
+ const bytes = new Uint8Array(256 * 1024).fill(97); bytes[bytes.length - 1] = 122;
+ const blob = new Blob([bytes], { type: 'image/png' });
+ await new Promise((resolve, reject) => {
+ const tx = db.transaction(['runs', 'events', 'shots'], 'readwrite');
+ tx.oncomplete = resolve; tx.onerror = () => reject(tx.error); tx.onabort = () => reject(tx.error);
+ tx.objectStore('runs').put({ runId, conversationId: 'large-session', lossless: true, startedAt: 1 });
+ for (let seq = 1; seq <= 200; seq++) {
+ tx.objectStore('events').put({ runId, seq, kind: 'screenshot', data: { caption: `shot-${seq}` } });
+ tx.objectStore('shots').put({ runId, seq, blob });
+ }
+ });
+ db.close();
+ // Intentionally leave this queued. The descriptor must not overtake it.
+ void trace.recordToolCall(runId, 201, { name: 'solve_captcha', result: { success: false, error: 'last recorded outcome' } });
+ });
+ const panel = await context.newPage();
+ let responseBytes = 0;
+ await panel.exposeFunction('backgroundExport', async () => {
+ const response = await writer.evaluate(() => exportAgent.exportTraces(1, { full: true }));
+ responseBytes = Buffer.byteLength(JSON.stringify(response));
+ assert.ok(responseBytes < 1024, `Only a session descriptor may cross runtime messaging; got ${responseBytes} bytes`);
+ return response;
+ });
+ await panel.goto('http://trace-download.local/');
+ await panel.evaluate(() => {
+ globalThis.chrome = globalThis.browser = { runtime: { getManifest: () => ({ version: 'test' }) } };
+ globalThis.exportMessages = [];
+ });
+ const downloadPromise = panel.waitForEvent('download');
+ await panel.evaluate(async () => (await import('/src/ui/export-harness.js')).run());
+ const download = await downloadPromise;
+ assert.match(download.suggestedFilename(), /^webbrain-traces-\d+\.json$/);
+ const bytes = await readFile(await download.path());
+ assert.ok(bytes.length > 64 * 1024 * 1024, `Fixture must exceed Chrome's message cap: ${bytes.length}`);
+ assert.ok(responseBytes < 1024);
+ const payload = JSON.parse(bytes.toString());
+ assert.equal(payload.session.sessionId, 'large-session');
+ assert.equal(payload.exportedByWebBrainVersion, 'test');
+ const events = payload.runs[0].events;
+ const shots = events.filter(event => event.kind === 'screenshot');
+ assert.equal(shots.length, 200);
+ for (const [index, event] of shots.entries()) {
+ assert.equal(event.data.caption, `shot-${index + 1}`);
+ const shot = Buffer.from(event.data.screenshot_base64.split(',')[1], 'base64');
+ assert.equal(shot.length, 256 * 1024); assert.equal(shot[0], 97); assert.equal(shot.at(-1), 122);
+ }
+ assert.equal(events.at(-1).data.outcome.error, 'last recorded outcome');
+ assert.deepEqual(await panel.evaluate(() => exportMessages), ['sp.export_traces.done']);
+
+ // Empty/error descriptors keep their messages and never initiate downloads.
+ let unexpectedDownloads = 0;
+ panel.on('download', () => unexpectedDownloads++);
+ await panel.evaluate(async () => {
+ exportMessages.length = 0;
+ const { run } = await import('/src/ui/export-harness.js');
+ await run({ ok: true, reason: 'no-conversation', turnCount: 0 });
+ await run({ ok: true, sessionId: 'missing-session' });
+ await run({ ok: false, error: 'Unreadable log' });
+ });
+ assert.equal(unexpectedDownloads, 0);
+ assert.deepEqual(await panel.evaluate(() => exportMessages), [
+ 'sp.export_traces.no_conversation', 'sp.export_traces.none', 'sp.export_traces.error (Unreadable log)',
+ ]);
+ const markdownPromise = panel.waitForEvent('download');
+ await panel.evaluate(async () => (await import('/src/ui/export-harness.js')).run({ ok: true, markdown: '# Summary', turnCount: 1 }, false));
+ const markdown = await markdownPromise;
+ assert.match(markdown.suggestedFilename(), /\.md$/);
+ assert.equal(await readFile(await markdown.path(), 'utf8'), '# Summary');
+ } finally { await browser.close(); }
+ });
+
test(`${build}: exhausted recording budget retains solver outcome and exports it as JSON`, async () => {
const browser = await engine.launch();
try {