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 test from 'node:test';
import assert from 'node:assert/strict';
const deferred = () => { let resolve; const promise = new Promise(done => { resolve = done; }); return { resolve, promise }; };
const tick = () => new Promise(resolve => setTimeout(resolve, 5));
async function until(predicate) { for (let n = 0; n < 100; n++) { if (predicate()) return; await tick(); } assert.fail('Condition did not settle'); }
const storage = new Map();
const area = { get: async key => ({ [key]: storage.get(key) }), set: async value => { for (const [key, item] of Object.entries(value)) storage.set(key, structuredClone(item)); }, remove: async key => storage.delete(key) };
globalThis.chrome = globalThis.browser = {
storage: { local: area, session: area },
runtime: { getURL: value => `chrome-extension://test/${value}`, sendMessage: async () => ({}) },
tabs: { get: async id => ({ id, url: 'https://example.com/', title: 'Example' }), sendMessage: async () => ({}) },
scripting: { executeScript: async () => [{ result: null }] },
};
for (const browser of ['chrome', 'firefox']) {
const { CloudHandoffGate } = await import(`../src/${browser}/src/agent/cloud-handoff.js`);
const { createCloudRunController, buildCloudPersistenceRows } = await import(`../src/${browser}/src/cloud-runs.js`);
const { Agent } = await import(`../src/${browser}/src/agent/agent.js`);
function harness(processMessage, options = {}) {
const stored = {};
const local = {};
const api = { storage: { local: { get: async key => ({ [key]: structuredClone(local[key]) }), set: async data => Object.assign(local, structuredClone(data)) }, session: { get: async key => ({ [key]: structuredClone(stored[key]) }), set: async data => Object.assign(stored, structuredClone(data)) } },
tabs: { get: async id => ({ id, url: 'https://example.com/' }), query: async () => [{ id: 7, url: 'https://example.com/' }], update: async () => {} } };
let clarificationResolve;
const agent = { isRunning: () => false, hasOtherRunningTabs: () => false, canPauseAtClarification: () => true,
strictSecretMode: true, processMessage, abort() {}, _persistNow: async () => ({ ok: true }),
submitClarifyResponse(_tab, _id, answer) { clarificationResolve?.(answer); return true; } };
let seq = 0;
const controller = createCloudRunController({ chromeApi: api, agent, makeRunId: () => `run_handoff_${++seq}`, ensureOffscreen: async () => {}, ...options });
return { controller, stored, local, agent, api, setClarificationResolver(value) { clarificationResolve = value; } };
}
test(`${browser}: pausing acknowledges only a settled boundary and keeps its tab reservation`, async () => {
const tool = deferred(); let actions = 0, observations = 0, returnedNote;
const h = harness(async (_tab, _task, update, _mode, _attachments, options) => {
actions++;
await tool.promise;
const handoff = await options.handoffBoundary();
returnedNote = handoff.note;
observations++;
await options.handoffObserved();
options.onRunFinished('done');
return 'Checked the page';
});
const run = await h.controller.startRun({ task: 'Check the page' });
const pausing = await h.controller.pause({ runId: run.runId });
assert.equal(pausing.status, 'pausing');
assert.equal(pausing.handoff.state, 'pausing');
assert.equal(observations, 0);
await assert.rejects(h.controller.resume({ runId: run.runId }), error => error.status === 409);
await assert.rejects(h.controller.startRun({ task: 'Another bot' }), error => error.status === 409);
tool.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused');
assert.equal(h.stored.webbrainCloudRunSnapshots[0].status, 'paused');
assert.equal(actions, 1);
const returning = await h.controller.resume({ runId: run.runId, note: 'I signed in' });
assert.equal(returning.status, 'resuming');
await until(() => h.controller.runs.get(run.runId).status === 'completed');
assert.equal(observations, 1);
assert.equal(returnedNote, 'I signed in');
assert.equal(JSON.stringify(await h.controller.status({ runId: run.runId })).includes('I signed in'), false, 'the note is not put in public updates');
});
test(`${browser}: a worker restart preserves manual control and reservation without replay`, async () => {
const tool = deferred(); let calls = 0;
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { calls++; await tool.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); tool.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused');
const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });
const restored = await restarted.status({ runId: run.runId });
assert.equal(restored.status, 'paused');
assert.equal(restored.handoff.interrupted, true);
assert.equal(restored.handoff.resumable, false);
assert.equal(restored.completedAt, null);
await assert.rejects(restarted.resume({ runId: run.runId }), error => error.status === 409);
await assert.rejects(restarted.startRun({ task: 'Another bot' }), error => error.status === 409);
await assert.rejects(restarted.startRun({ task: 'Another bot in another tab', tabId: 8 }), error => error.status === 409);
for (const kind of ['scheduled', 'interactive', 'cloud']) await assert.rejects(restarted.guardRunStart(8, { kind }), error => error.status === 409);
assert.equal(calls, 1, 'neither restart nor Hand back replays the old task');
assert.equal((await restarted.abort({ runId: run.runId })).status, 'aborted');
assert.equal(restarted.isRunning(7), false);
await restarted.guardRunStart(8, { kind: 'scheduled' });
await h.controller.abort({ runId: run.runId });
});
test(`${browser}: manual control preserves a clarification and handback never answers it`, async () => {
const question = deferred(); let responses = 0, reads = 0;
const h = harness(async (_tab, _task, update, _mode, _attachments, options) => {
update('clarify', { clarifyId: 'login', question: 'Have you signed in?', options: ['Yes', 'Stop'], requireExplicitAnswer: true });
await question.promise;
const handoff = await options.handoffBoundary();
assert.equal(handoff.note, 'I signed in'); reads++;
await options.handoffObserved(); options.onRunFinished('done'); return 'Done';
});
h.setClarificationResolver(answer => { responses++; assert.equal(answer, 'Yes'); question.resolve(); });
const run = await h.controller.startRun({ task: 'Read the account' });
await until(() => h.controller.runs.get(run.runId).status === 'needs_user_input');
const paused = await h.controller.pause({ runId: run.runId });
assert.equal(paused.status, 'paused');
assert.equal(paused.pendingInput.clarifyId, 'login');
await assert.rejects(h.controller.respond({ runId: run.runId, clarifyId: 'login', answer: 'Yes' }), error => error.status === 409);
const returning = await h.controller.resume({ runId: run.runId, note: 'I signed in' });
assert.equal(returning.status, 'resuming');
assert.equal(returning.pendingInput.clarifyId, 'login');
assert.equal(responses, 0); assert.equal(reads, 0);
await h.controller.respond({ runId: run.runId, clarifyId: 'login', answer: 'Yes' });
await until(() => h.controller.runs.get(run.runId).status === 'completed');
assert.equal(responses, 1); assert.equal(reads, 1);
});
test(`${browser}: pre-handoff batch actions are discarded, page read is fresh, task authority and mutation receipts stay intact`, async () => {
const provider = { name: 'test', model: 'test', promptTier: 'full', supportsTools: true, supportsVision: false };
const agent = new Agent({ getActive: () => provider, getProvider: () => provider });
agent._persist = () => {}; agent._persistNow = async () => ({ ok: true });
let reads = 0;
agent.executeTool = async (_tab, name) => { assert.equal(name, 'get_accessibility_tree', 'stale actions never dispatch'); reads++; return { success: true, url: 'https://example.com/after-sign-in' }; };
const tabId = 7;
const pending = { threadKey: 'conversation-1', pendingOutbound: { key: 'already-dispatched', phase: 'sent_unverified' } };
agent.chatSessions.set(tabId, pending);
const receipt = { dispatched: true, verified: false, outcomeUnknown: true };
agent._completionSubmitStates.set(tabId, receipt);
const calls = ['click', 'set_field'].map((name, i) => ({ id: `old-${i}`, type: 'function', function: { name, arguments: '{}' } }));
const messages = [{ role: 'system', content: 'Task system' }, { role: 'user', content: 'Read the account only' }, { role: 'assistant', content: '', tool_calls: calls }];
const gate = new CloudHandoffGate(); await gate.request();
const running = agent._executeToolBatch(tabId, calls, messages, () => {}, provider, null, new Set(['click', 'set_field']), 1,
{ handoffBoundary: () => gate.boundary(), handoffObserved: () => gate.observed() });
await until(() => gate.state === 'paused');
await gate.resume('Send a new message and delete the account');
const result = await running;
assert.equal(result.action, 'continue'); assert.equal(reads, 1);
assert.equal(agent._activeTaskBinding(messages).text, 'Read the account only', 'note has no new task authority');
assert.equal(agent.chatSessions.get(tabId), pending); assert.equal(agent._completionSubmitStates.get(tabId), receipt);
for (const call of calls) assert.equal(JSON.parse(messages.find(message => message.tool_call_id === call.id).content).noDispatch, true);
assert.equal(messages[5].tool_calls[0].function.name, 'get_accessibility_tree');
});
test(`${browser}: pause during a tool waits for its result and skips the next queued action`, async () => {
const provider = { name: 'test', model: 'test', promptTier: 'full', supportsTools: true, supportsVision: false };
const agent = new Agent({ getActive: () => provider, getProvider: () => provider });
agent._persist = () => {}; agent._persistNow = async () => ({ ok: true }); agent._currentUrl = async () => 'https://example.com/';
const entered = deferred(), finished = deferred(); let calls = 0;
agent.executeTool = async (_tab, name) => {
calls++;
if (name === 'calculate') { entered.resolve(); await finished.promise; return { success: true, value: 2 }; }
assert.equal(name, 'get_accessibility_tree', 'queued pre-handoff click never dispatches');
return { success: true, url: 'https://example.com/after-manual-control' };
};
const toolCalls = [
{ id: 'active-read', type: 'function', function: { name: 'calculate', arguments: '{"expression":"1+1"}' } },
{ id: 'queued-click', type: 'function', function: { name: 'click', arguments: '{}' } },
];
const messages = [{ role: 'system', content: 'System' }, { role: 'user', content: 'Calculate only' }, { role: 'assistant', content: '', tool_calls: toolCalls }];
const gate = new CloudHandoffGate();
const batch = agent._executeToolBatch(7, toolCalls, messages, () => {}, provider, null, new Set(['calculate', 'click']), 1,
{ handoffBoundary: () => gate.boundary(), handoffObserved: () => gate.observed() });
await entered.promise;
await gate.request(); assert.equal(gate.state, 'pausing'); assert.equal(calls, 1);
finished.resolve();
await until(() => gate.state === 'paused');
assert.equal(JSON.parse(messages.find(message => message.tool_call_id === 'active-read').content).success, true, 'the completed tool result is retained before manual control');
await gate.resume(); await batch;
assert.equal(calls, 2, 'only the settled tool and fresh browser observation ran');
assert.equal(JSON.parse(messages.find(message => message.tool_call_id === 'queued-click').content).noDispatch, true);
});
test(`${browser}: failed handback observation keeps manual control and blocks new work`, async () => {
const ready = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise;
await options.handoffBoundary();
throw new Error('Could not inspect the browser after handoff.');
});
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused');
await h.controller.resume({ runId: run.runId });
await until(() => h.controller.runs.get(run.runId).handoff?.interrupted === true);
const interrupted = await h.controller.status({ runId: run.runId });
assert.equal(interrupted.status, 'paused'); assert.equal(interrupted.handoff.resumable, false); assert.equal(interrupted.completedAt, null);
assert.equal(h.controller.isRunning(7), true);
await assert.rejects(h.controller.startRun({ task: 'Queued bot', tabId: 8 }), error => error.status === 409);
await assert.rejects(h.controller.resume({ runId: run.runId }), error => error.status === 409);
await h.controller.abort({ runId: run.runId }); assert.equal(h.controller.isRunning(7), false);
});
test(`${browser}: pause acknowledgement waits for durable storage and abort wakes the paused agent`, async () => {
const ready = deferred(), writing = deferred(), written = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Stopped'; });
const write = h.api.storage.session.set;
h.api.storage.session.set = async data => {
if (data.webbrainCloudRunSnapshots?.[0]?.status === 'paused') { writing.resolve(); await written.promise; }
return write(data);
};
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve(); await writing.promise;
let exposed = false;
const status = h.controller.status({ runId: run.runId }).then(value => { exposed = true; return value; });
let pauseExposed = false;
const repeatPause = h.controller.pause({ runId: run.runId }).then(value => { pauseExposed = true; return value; });
await tick(); assert.equal(exposed, false, 'the viewer does not get control until the checkpoint is durable');
assert.equal(pauseExposed, false, 'repeating Take over also waits for the checkpoint');
written.resolve(); assert.equal((await status).status, 'paused');
assert.equal((await repeatPause).status, 'paused');
await h.controller.abort({ runId: run.runId });
await until(() => h.controller.runs.get(run.runId).status === 'aborted');
assert.equal(h.controller.isRunning(7), false);
});
test(`${browser}: another Cloud startup prevents handoff until it settles`, async () => {
const pending = deferred(), entered = deferred(), done = deferred();
let started = 0;
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
started++; await done.promise; options.onRunFinished('done'); return 'Read';
});
const run = await h.controller.startRun({ task: 'Read', tabId: 7 });
const get = h.api.tabs.get;
h.api.tabs.get = async id => { if (id === 8) { entered.resolve(); await pending.promise; } return get(id); };
const second = h.controller.startRun({ task: 'Read in another tab', tabId: 8 });
await entered.promise;
try {
await assert.rejects(h.controller.pause({ runId: run.runId }), error => error.status === 409);
assert.equal(h.controller.runs.get(run.runId).handoff, undefined);
} finally { pending.resolve(); await second; done.resolve(); }
await until(() => [...h.controller.runs.values()].every(value => value.status === 'completed'));
assert.equal(started, 2);
});
test(`${browser}: other active Cloud or native tabs prevent manual control`, async () => {
const done = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await done.promise; options.onRunFinished('done'); return 'Read';
});
const run = await h.controller.startRun({ task: 'Read', tabId: 7 });
const other = await h.controller.startRun({ task: 'Read', tabId: 8 });
try {
await assert.rejects(h.controller.pause({ runId: run.runId }), error => error.status === 409);
h.controller.runs.get(other.runId).status = 'completed';
h.agent.hasOtherRunningTabs = id => id === 7;
await assert.rejects(h.controller.pause({ runId: run.runId }), error => error.status === 409);
assert.equal(h.controller.runs.get(run.runId).handoff, undefined);
} finally { done.resolve(); }
await until(() => h.controller.runs.get(run.runId).status === 'completed');
});
test(`${browser}: startup guards hydrate interrupted handoffs before permitting any agent`, async () => {
const h = harness(async () => assert.fail('No new run should start'));
h.stored.webbrainCloudRunSnapshots = [{ runId: 'old', tabId: 7, status: 'paused', createdAt: '2020-01-01',
handoff: { state: 'paused', resumable: true, interrupted: false } }];
for (const kind of ['cloud', 'scheduled', 'interactive']) {
await assert.rejects(h.controller.guardRunStart(8, { kind }), error => error.status === 409);
}
assert.equal(h.controller.isRunning(7), true);
await h.controller.abort({ runId: 'old' });
await h.controller.guardRunStart(8, { kind: 'interactive' });
});
test(`${browser}: unavailable persisted state cannot silently authorize a new agent`, async () => {
const h = harness(async () => assert.fail('No run should start'));
h.api.storage.session.get = async () => { throw new Error('Session storage unavailable'); };
await assert.rejects(h.controller.guardRunStart(8, { kind: 'interactive' }), /Session storage unavailable/);
await assert.rejects(h.controller.startRun({ task: 'Read' }), /Session storage unavailable/);
assert.equal(h.controller.runs.size, 0);
});
test(`${browser}: history limits cannot evict an old active handoff`, () => {
const handoff = { runId: 'old-paused', tabId: 7, status: 'paused', createdAt: '2000-01-01',
handoff: { state: 'paused', resumable: true, interrupted: false } };
const history = Array.from({ length: 60 }, (_, index) => ({ runId: `history-${index}`, status: 'completed',
createdAt: `2026-01-01T00:00:${String(index).padStart(2, '0')}Z` }));
const rows = buildCloudPersistenceRows([...history, handoff]);
assert.equal(rows.length, 50);
assert.equal(rows[0].runId, 'old-paused');
assert.equal(rows[0].handoff.state, 'paused');
});
test(`${browser}: internal permission waits cannot acknowledge an unsettled action`, async () => {
const answer = deferred(); let posted = false;
const h = harness(async (_tab, _task, update, _mode, _attachments, options) => {
update('clarify', { clarifyId: 'submit-form', promptKind: 'submitConfirmation', question: 'Submit?', options: ['once', 'deny'] });
await answer.promise; posted = true; options.onRunFinished('done'); return 'Submitted';
});
h.agent.canPauseAtClarification = () => false;
h.setClarificationResolver(() => answer.resolve());
const run = await h.controller.startRun({ task: 'Submit the form' });
await until(() => h.controller.runs.get(run.runId).status === 'needs_user_input');
await assert.rejects(h.controller.pause({ runId: run.runId }), error => error.status === 409);
assert.equal(h.controller.runs.get(run.runId).handoff, undefined);
assert.equal(posted, false);
await h.controller.respond({ runId: run.runId, clarifyId: 'submit-form', answer: 'once' });
await until(() => h.controller.runs.get(run.runId).status === 'completed');
assert.equal(posted, true);
});
test(`${browser}: native standalone clarification is safe but native form approval is not`, async () => {
const provider = { name: 'test', model: 'test' };
const agent = new Agent({ getActive: () => provider });
agent.clarifyTimeoutSec = -1;
const ready = deferred(); let question, approval;
const standalone = agent._executeToolImpl(7, 'clarify', { question: 'Have you signed in?', options: ['Yes', 'Stop'] },
(type, data) => { if (type === 'clarify') { question = data; ready.resolve(); } });
const form = agent._promptSubmitConfirmation(7, { host: 'example.com', summary: 'Submit this form' },
(type, data) => { if (type === 'clarify') approval = data; });
try {
await ready.promise;
assert.equal(agent.canPauseAtClarification(7, question.clarifyId), true);
assert.equal(agent.canPauseAtClarification(7, approval.clarifyId), false);
} finally { agent._cancelClarifications(7, 'Fixture cleanup'); await Promise.all([standalone, form]); }
assert.equal(agent.canPauseAtClarification(7, question.clarifyId), false);
agent._runningTabs.add(8);
assert.equal(agent.hasOtherRunningTabs(7), true);
assert.equal(agent.hasOtherRunningTabs(8), false);
});
for (const restart of ['extension reload', 'browser startup without session storage']) {
test(`${browser}: ${restart} restores only a durable manual guard and never replays`, async () => {
const ready = deferred(); let calls = 0;
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { calls++; await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Private task with secret-provider-token' });
await h.controller.pause({ runId: run.runId }); ready.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused');
await h.controller.status({ runId: run.runId });
const guard = h.local.webbrainCloudHandoffGuards[0];
assert.deepEqual(Object.keys(guard).sort(), ['createdAt', 'pausedAt', 'runId', 'tabId', 'updatedAt']);
assert.equal(JSON.stringify(h.local).includes('secret-provider-token'), false);
delete h.stored.webbrainCloudRunSnapshots;
if (restart.includes('without')) delete h.api.storage.session;
const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });
const restored = await restarted.status({ runId: run.runId });
assert.equal(restored.status, 'paused'); assert.equal(restored.handoff.interrupted, true); assert.equal(restored.handoff.resumable, false);
assert.equal(restored.task, undefined); assert.equal(restored.result, undefined); assert.equal(calls, 1);
await assert.rejects(restarted.resume({ runId: run.runId }), error => error.status === 409);
await assert.rejects(restarted.startRun({ task: 'Other bot', tabId: 8 }), error => error.status === 409);
await assert.rejects(restarted.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);
assert.equal((await restarted.abort({ runId: run.runId })).status, 'aborted');
assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
await restarted.guardRunStart(8, { kind: 'interactive' });
await h.controller.abort({ runId: run.runId });
});
}
test(`${browser}: a durable guard overrides a matching stale terminal snapshot`, async () => {
const ready = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
h.stored.webbrainCloudRunSnapshots[0].status = 'aborted'; h.stored.webbrainCloudRunSnapshots[0].handoff = null;
const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });
const restored = await restarted.status({ runId: run.runId });
assert.equal(restored.status, 'paused'); assert.equal(restored.handoff.interrupted, true);
await restarted.abort({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
await h.controller.abort({ runId: run.runId });
});
test(`${browser}: durable local acknowledgement blocks publication and direct resume while writing`, async () => {
const ready = deferred(), writing = deferred(), written = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });
const write = h.api.storage.local.set;
h.api.storage.local.set = async data => { if (data.webbrainCloudHandoffGuards?.[0]?.pausedAt) { writing.resolve(); await written.promise; } return write(data); };
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve(); await writing.promise;
assert.equal(h.controller.runs.get(run.runId).status, 'pausing');
let exposed = false, resumed = false;
const status = h.controller.status({ runId: run.runId }).then(value => { exposed = true; return value; });
const returning = h.controller.resume({ runId: run.runId }).then(() => { resumed = true; }, error => { assert.equal(error.status, 409); });
await tick(); assert.equal(exposed, false); assert.equal(resumed, false);
written.resolve(); await status; await returning;
await h.controller.abort({ runId: run.runId });
});
test(`${browser}: failed guard writes retain read-only ownership and abort waits for native quiescence`, async () => {
const ready = deferred(), finished = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); await finished.promise; options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Read' });
const write = h.api.storage.local.set;
h.api.storage.local.set = async () => { throw Error('Fixture guard write failure'); };
await assert.rejects(h.controller.pause({ runId: run.runId }), /guard write failure/);
assert.equal(h.controller.runs.get(run.runId).handoff.resumable, false);
await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);
h.api.storage.local.set = write;
const aborting = await h.controller.abort({ runId: run.runId }); assert.equal(aborting.status, 'aborting');
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1, 'a cancellation request must retain the durable guard');
ready.resolve(); await tick(); assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);
finished.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');
await h.controller.status({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
});
test(`${browser}: guard removal failures preserve the lock until explicit cancellation retries`, async () => {
const ready = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });
await restarted.status({ runId: run.runId });
const write = h.api.storage.local.set;
h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) throw Error('Fixture clear failure'); return write(data); };
await assert.rejects(restarted.abort({ runId: run.runId }), /clear failure/);
assert.equal(restarted.runs.get(run.runId).status, 'paused');
assert.equal(restarted.runs.get(run.runId).handoff.interrupted, true);
assert.equal(restarted.runs.get(run.runId).updates.at(-1).data.state, 'paused', 'failed cancellation cannot publish a null handoff');
assert.equal(restarted.isRunning(7), true);
await assert.rejects(restarted.guardRunStart(8, { kind: 'interactive' }), error => error.status === 409);
h.api.storage.local.set = write;
assert.equal((await restarted.abort({ runId: run.runId })).status, 'aborted'); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
await h.controller.abort({ runId: run.runId });
});
test(`${browser}: handback guard-clear failure stops before any further action`, async () => {
const ready = deferred(); let observations = 0, actions = 0;
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise; await options.handoffBoundary(); observations++;
await options.handoffObserved(); actions++; options.onRunFinished('done'); return 'Read';
});
const run = await h.controller.startRun({ task: 'Read only' });
await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
const write = h.api.storage.local.set;
h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) throw Error('Fixture observed-clear failure'); return write(data); };
await h.controller.resume({ runId: run.runId }); await until(() => h.controller.runs.get(run.runId).handoff?.interrupted);
const stopped = await h.controller.status({ runId: run.runId });
assert.equal(stopped.status, 'paused'); assert.equal(stopped.handoff.resumable, false); assert.equal(observations, 1); assert.equal(actions, 0);
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);
await assert.rejects(h.controller.startRun({ task: 'Another bot', tabId: 8 }), error => error.status === 409);
h.api.storage.local.set = write; await h.controller.abort({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
});
test(`${browser}: queued persistence cannot resurrect a confirmed cleared guard`, async () => {
const ready = deferred(), clearing = deferred(), cleared = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} }); await restarted.status({ runId: run.runId });
const write = h.api.storage.local.set;
h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) { clearing.resolve(); await cleared.promise; } return write(data); };
const first = restarted.abort({ runId: run.runId }); await clearing.promise;
const queued = restarted.abort({ runId: run.runId }); await tick(); cleared.resolve();
await first; await queued; await restarted.status({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
await h.controller.abort({ runId: run.runId });
});
test(`${browser}: failed or malformed durable guard reads prevent run startup`, async () => {
const valid = { runId: 'owned_1', tabId: 7, createdAt: '2026-10-12T23:00:00.000Z', updatedAt: '2026-10-12T23:00:00.000Z', pausedAt: null };
const readFailure = Symbol('read failure');
for (const value of [readFailure, null, false, 0, '', [{ runId: '', tabId: 7 }], [{ ...valid, runId: 123 }], [{ ...valid, runId: ' ' }],
[valid, valid], [{ ...valid, tabId: '7' }], [{ ...valid, createdAt: 'yesterday' }]]) {
let calls = 0;
const h = harness(async () => { calls++; });
h.api.storage.local.get = async () => { if (value === readFailure) throw Error('Fixture read failure'); return { webbrainCloudHandoffGuards: value }; };
await assert.rejects(h.controller.startRun({ task: 'Read' })); assert.equal(calls, 0);
}
});
test(`${browser}: failed live cancellation clear stays interrupted until owner retries`, async () => {
const ready = deferred();
const h = harness(async (_tab, _task, update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); update('clarify', { clarifyId: 'late', question: 'Late question' }); options.onRunFinished('done'); return 'Read'; });
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
const write = h.api.storage.local.set;
h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) throw Error('Fixture live clear failure'); return write(data); };
assert.equal((await h.controller.abort({ runId: run.runId })).status, 'aborting');
await until(() => h.controller.runs.get(run.runId).handoff?.interrupted);
const stopped = await h.controller.status({ runId: run.runId });
assert.equal(stopped.status, 'paused'); assert.equal(stopped.handoff.resumable, false); assert.equal(stopped.pendingInput, null); assert.equal(stopped.completedAt, null);
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);
await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);
h.api.storage.local.set = write; assert.equal((await h.controller.abort({ runId: run.runId })).status, 'aborted'); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
});
test(`${browser}: valid caller correlation IDs remain usable for handoff and reload`, async () => {
for (const runId of ['request:17', 'tenant/run/1', 'browser-ü-任务']) {
const ready = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read';
});
await h.controller.startRun({ task: 'Read only', runId });
await h.controller.pause({ runId }); ready.resolve();
await until(() => h.controller.runs.get(runId).status === 'paused'); await h.controller.status({ runId });
delete h.stored.webbrainCloudRunSnapshots;
const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent });
assert.equal((await restarted.status({ runId })).handoff.interrupted, true);
await restarted.abort({ runId }); await h.controller.abort({ runId });
}
const h = harness(async () => assert.fail('Oversized ID must not dispatch'));
await assert.rejects(h.controller.startRun({ task: 'Read', runId: 'x'.repeat(16 * 1024 + 1) }), error => error.status === 400);
assert.equal(h.controller.runs.size, 0);
});
test(`${browser}: cancellation during a pending pause guard write cannot resurrect manual control`, async () => {
for (const fail of [false, true]) {
const ready = deferred(), writing = deferred(), written = deferred(), finished = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise; await options.handoffBoundary(); await finished.promise; options.onRunFinished('done'); return 'Read';
});
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId });
const set = h.api.storage.local.set;
let failed = false;
h.api.storage.local.set = async data => {
if (data.webbrainCloudHandoffGuards?.[0]?.pausedAt) {
writing.resolve(); await written.promise;
if (fail && !failed) { failed = true; throw Error('Fixture pending pause write failure'); }
}
return set(data);
};
ready.resolve(); await writing.promise;
const aborting = h.controller.abort({ runId: run.runId });
await tick(); assert.equal(h.controller.runs.get(run.runId).status, 'aborting');
await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);
written.resolve(); await aborting;
assert.equal(h.controller.runs.get(run.runId).handoff, null, 'a delayed pause callback cannot restore writable state');
finished.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');
assert.equal((await h.controller.status({ runId: run.runId })).status, 'aborted');
assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
}
});
test(`${browser}: cancellation stays nonterminal through native and recording cleanup`, async () => {
const ready = deferred(), settled = deferred(), flushing = deferred(), flushed = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise; await options.handoffBoundary(); await settled.promise; options.onRunFinished('done'); return 'Read';
}, {
startRecording: async () => ({ ok: true, state: { recordingId: 'capture-1' } }),
stopRecording: async () => { flushing.resolve(); await flushed.promise; return { ok: true }; },
});
const run = await h.controller.startRun({ task: 'Read', capture: 'video' });
await h.controller.pause({ runId: run.runId }); ready.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
assert.equal((await h.controller.abort({ runId: run.runId })).status, 'aborting');
for (const kind of ['cloud', 'scheduled', 'interactive']) await assert.rejects(h.controller.guardRunStart(8, { kind }), error => error.status === 409);
await assert.rejects(h.controller.startRun({ task: 'Another bot', tabId: 8 }), error => error.status === 409);
settled.resolve(); await flushing.promise;
const pending = await h.controller.status({ runId: run.runId });
assert.equal(pending.completedAt, null); assert.notEqual(pending.status, 'aborted');
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1, 'recording still owns the profile');
flushed.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');
await h.controller.status({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
await h.controller.guardRunStart(8, { kind: 'interactive' });
});
test(`${browser}: a failed public paused checkpoint becomes nonresumable`, async () => {
const ready = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read';
});
const run = await h.controller.startRun({ task: 'Read' });
await h.controller.pause({ runId: run.runId });
const set = h.api.storage.session.set;
h.api.storage.session.set = async data => {
if (data.webbrainCloudRunSnapshots?.[0]?.handoff?.resumable && data.webbrainCloudRunSnapshots[0].status === 'paused') throw Error('Fixture public checkpoint failure');
return set(data);
};
ready.resolve(); await until(() => h.controller.runs.get(run.runId).handoff?.interrupted);
assert.equal(h.controller.runs.get(run.runId).handoff.resumable, false);
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);
await assert.rejects(h.controller.resume({ runId: run.runId }));
h.api.storage.session.set = set;
await until(() => !h.controller.runs.get(run.runId).pendingInput);
await h.controller.abort({ runId: run.runId }); await until(() => h.controller.runs.get(run.runId).status === 'aborted');
});
test(`${browser}: abort racing a fresh-observation guard clear retains ownership through recording cleanup`, async () => {
const ready = deferred(), clearing = deferred(), cleared = deferred(), continued = deferred(), flushing = deferred(), flushed = deferred();
const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {
await ready.promise; await options.handoffBoundary(); await options.handoffObserved();
await continued.promise; options.onRunFinished('done'); return 'Read';
}, {
startRecording: async () => ({ ok: true, state: { recordingId: 'capture-2' } }),
stopRecording: async () => { flushing.resolve(); await flushed.promise; return { ok: true }; },
});
const run = await h.controller.startRun({ task: 'Read', capture: 'video' });
await h.controller.pause({ runId: run.runId }); ready.resolve();
await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });
const set = h.api.storage.local.set;
let held = false;
h.api.storage.local.set = async data => {
if (!held && !data.webbrainCloudHandoffGuards.length) {
held = true; clearing.resolve(); await cleared.promise;
}
return set(data);
};
await h.controller.resume({ runId: run.runId }); await clearing.promise;
const aborting = h.controller.abort({ runId: run.runId });
await tick();
await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);
cleared.resolve();
assert.equal((await aborting).status, 'aborting');
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1, 'cancellation during clear restores the durable reservation');
continued.resolve(); await flushing.promise;
for (const kind of ['cloud', 'scheduled', 'interactive']) await assert.rejects(h.controller.guardRunStart(8, { kind }), error => error.status === 409);
await assert.rejects(h.controller.startRun({ task: 'Another bot', tabId: 8 }), error => error.status === 409);
const pending = await h.controller.status({ runId: run.runId });
assert.equal(pending.completedAt, null); assert.notEqual(pending.status, 'aborted');
assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);
flushed.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');
assert.equal((await h.controller.status({ runId: run.runId })).status, 'aborted');
assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);
await h.controller.guardRunStart(8, { kind: 'interactive' });
});
if (browser === 'firefox') test('Firefox keeps its in-process Cloud bridge transport', async () => {
const calls = [];
const h = harness(async () => assert.fail('Bridge controls must not start browser work'), {
bridge: {
start: async options => { calls.push(['start', options.url]); return { connected: true }; },
stop: async () => { calls.push(['stop']); return { connected: false }; },
status: async () => { calls.push(['status']); return { connected: true }; },
},
ensureOffscreen: () => assert.fail('Firefox has no offscreen document'),
});
h.api.runtime = { sendMessage: () => assert.fail('Firefox uses its injected background bridge') };
assert.equal((await h.controller.startBridge('ws://127.0.0.1:17374/extension')).connected, true);
assert.equal((await h.controller.bridgeStatus()).connected, true);
assert.equal((await h.controller.stopBridge()).connected, false);
assert.deepEqual(calls, [['start', 'ws://127.0.0.1:17374/extension'], ['status'], ['stop']]);
});
}