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 assert from 'node:assert/strict';
import fs from 'node:fs';
import vm from 'node:vm';
import { test } from 'node:test';
import { withoutFixedChoiceAnswers } from './semantic-decision-stub.mjs';
import { makeSchedulerHarness } from './lib/scheduler-harness.mjs';
import { CDPClient, cdpClient } from '../src/chrome/src/cdp/cdp-client.js';
const area = { get: async () => ({}), set: async () => {}, remove: async () => {} };
const api = { storage: { local: area, session: area },
runtime: { getURL: value => `extension://test/${value}`, sendMessage: async () => ({}) },
tabs: { get: async id => ({ id, url: 'https://example.com/new', title: 'Example' }), sendMessage: async () => ({}) },
scripting: { executeScript: async () => [{ result: null }] } };
globalThis.chrome = api;
globalThis.browser = api;
const deferred = () => { let resolve; const promise = new Promise(r => { resolve = r; }); return { promise, resolve }; };
const sender = (tabId, frameId = 0, documentId = 'document-1') => ({ tab: { id: tabId }, frameId, documentId, url: 'https://example.com/new' });
let nextTab = 600;
test('CDP evaluateFunction sends page data as arguments and releases the global target', async () => {
const client = new CDPClient(), tab = 599, calls = [];
client.sessions.set(tab, {});
client.sendCommand = async (_tab, method, params) => {
calls.push({ method, params });
if (method === 'Runtime.evaluate') return { result: { objectId: 'page-global' } };
if (method === 'Runtime.callFunctionOn') return { result: { value: 'done' } };
return {};
};
const guard = { documentToken: 'doc', revision: 3, operationId: 'op' };
const declaration = 'function (guard, token) { return [guard, token]; }';
const response = await client.evaluateFunction(tab, declaration, [guard, 'abort'], { timeoutMs: 15000 });
assert.deepEqual(response, { result: { value: 'done' } });
assert.deepEqual(calls.map(call => call.method), ['Runtime.enable', 'Runtime.evaluate', 'Runtime.callFunctionOn', 'Runtime.releaseObject']);
assert.equal(calls[1].params.expression, 'globalThis');
assert.equal(calls[2].params.objectId, 'page-global');
assert.equal(calls[2].params.functionDeclaration, declaration);
assert.deepEqual(calls[2].params.arguments, [{ value: guard }, { value: 'abort' }]);
assert.equal(calls[2].params.awaitPromise, true);
assert.equal(calls[2].params.timeout, 15000);
assert.deepEqual(calls[3].params, { objectId: 'page-global' });
});
function setup(Agent, implementation = {}) {
const provider = { name: 'feedback test', model: 'test', promptTier: 'full', contextWindow: 128000,
supportsTools: false, supportsVision: false, ...implementation };
const agent = new Agent({ getActive: () => provider, getProvider: () => provider, getVisionProvider: async () => null });
agent._hydrate = async () => {};
agent._persist = () => {};
agent._persistNow = async () => ({ ok: true });
agent._startTraceRun = async () => null;
agent._endTraceRun = async () => {};
agent._enrichUserMessageWithCurrentPage = async (_tab, _messages, content) => ({ role: 'user', content });
agent._beginReadCompleteness = async () => null;
agent._maybeRunPlannerGate = async () => ({ proceed: true });
agent._manageContext = async () => {};
agent._checkCostAllowance = async () => null;
agent._recordCostUsage = async () => null;
agent._currentUrl = async () => 'https://example.com/new';
agent._maybeEmitAskModeHandoff = async () => {};
agent._shouldAutoScreenshot = () => false;
agent._pageFeedbackIdleMs = 0;
agent.executeTool = async (_tab, name) => {
assert.equal(name, 'get_accessibility_tree', 'Superseded action must never be dispatched');
return { success: true, pageContent: 'The current view' };
};
return agent;
}
function bind(agent, tabId, frameId = 0, documentId = 'document-1', docToken = 'content-1', frameName = '') {
const from = sender(tabId, frameId, documentId);
const state = agent.pageMonitorState(from, docToken, frameName);
assert.equal(state.active, true);
let seq = 0;
return { state, from, send: value => agent.observePageFeedback(from, {
...state, seq: ++seq, kind: 'input', source: 'user', revision: seq, target: 'input#filter', ...value,
}) };
}
function allowBatchPreparation(agent) {
agent._skipPermissionGate = true;
for (const name of ['_chromeProtectedPageFailure', '_captchaMutationPreflight', '_workflowPreSubmitDispatchBlock',
'_messageRecipientGuardBlock', '_detectLikelySubmitAction', '_socialPublicationPreSubmitBlock']) agent[name] = async () => null;
agent._ensureGateSetting = async () => true;
agent._adoptLiveSocialPublishWorkflow = async () => false;
agent._isFormValidationCandidate = () => false;
agent._preflightRichTextToolbarTarget = async () => ({ block: null });
agent._auditRichTextToolbarTarget = async () => {};
}
for (const build of ['chrome', 'firefox']) {
const { Agent } = await import(`../src/${build}/src/agent/agent.js`);
const { beforePageAgentDispatch } = await import(`../src/${build}/src/agent/page-feedback.js`);
const { verifyBrowserCompletion } = await import(`../src/${build}/src/agent/completion-runtime.js`);
for (const outcome of ['succeeded', 'failed']) {
test(`${build}: retained success candidate verifies fresh ${outcome} evidence`, async () => {
const agent = setup(Agent, { chat: async () => assert.fail('Completion should use the bounded judge request') });
const tab = nextTab++;
let page = { success: true, pageContent: 'article "Old timeline" [ref_1]' }, requests = 0;
agent.executeTool = async (_tab, name) => {
assert.equal(name, 'get_accessibility_tree');
return page;
};
agent._completionDocumentStamp = async () => 'same-document';
agent._progressTaskKeyHash = () => 'publish-task';
agent._progressTaskAnchorText = () => 'Publish a WebBrain post';
agent._chatWithCostAllowance = async (_provider, messages, options) => {
requests++;
assert.equal(options.tools, undefined);
assert.match(JSON.stringify(messages), /Fresh result/);
assert.doesNotMatch(JSON.stringify(messages), /Old timeline/);
return { content: JSON.stringify({ outcome, reason: 'Fresh result establishes the outcome.' }) };
};
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab), messages = [{ role: 'system', content: '' }, { role: 'user', content: 'Publish a WebBrain post' }];
agent.conversations.set(tab, messages);
binding.send({ kind: 'dom', source: 'page', target: 'time' });
await agent._applyPendingPageFeedback(tab, messages);
page = { success: true, pageContent: `article "Fresh result: ${outcome}" [ref_1]` };
binding.send({ kind: 'dom', source: 'page', target: 'time' });
const args = { summary: 'Published successfully', outcome: 'success' };
assert.equal(await agent._applyPendingPageFeedback(tab, messages, () => {}, {
responseToolCalls: [{ function: { name: 'done', arguments: JSON.stringify(args) } }],
}), false);
const verdict = await verifyBrowserCompletion(agent, tab, { pageUrl: 'https://example.com/new', summary: args.summary });
assert.equal(verdict.outcome, outcome, 'Retaining a success candidate must not override fresh negative evidence');
assert.equal(verdict.engine, 'llm');
assert.equal(requests, 1);
} finally { agent._releaseRunEntry(tab); }
});
}
// An Act completion also survives automatic churn (unknown-attribution and
// child-frame DOM); its batch still runs the completion verifier.
const completionSurvives = change => ['feed', 'partial', 'unknown', 'iframe'].includes(change);
for (const change of ['feed', 'user', 'unknown', 'iframe', 'navigation', 'viewport', 'style', 'failed_read',
'partial', 'missing_outcome', 'malformed', 'mixed', 'duplicate', 'pending']) {
test(`${build}: explicit completion ${completionSurvives(change) ? 'survives' : 'rejects'} ${change} feedback`, async () => {
const agent = setup(Agent), tab = nextTab++;
let page = { success: true, pageContent: 'article "Published WebBrain post" [ref_1]' };
agent.executeTool = async () => page;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab), messages = [{ role: 'system', content: '' }, { role: 'user', content: 'Publish a WebBrain post' }];
binding.send({ kind: 'dom', source: 'page', target: 'time' });
await agent._applyPendingPageFeedback(tab, messages);
page = { success: change !== 'failed_read', pageContent: 'article "Updated timeline" [ref_1]' };
binding.send({ kind: change === 'viewport' ? 'resize' : 'dom',
source: change === 'user' ? 'user' : change === 'unknown' ? 'unknown' : 'page',
target: change === 'style' ? 'style' : 'time' });
if (change === 'iframe') agent._queuePageFeedback(tab, { kind: 'dom', source: 'page', frameId: 1, target: 'time' });
if (change === 'navigation') agent._queuePageFeedback(tab, { kind: 'navigation', source: 'page', frameId: 0 });
if (change === 'pending') agent.executeTool = async () => {
binding.send({ kind: 'input', source: 'user' });
return page;
};
const args = { summary: 'Published', outcome: change === 'partial' ? 'partial' : 'success' };
if (change === 'missing_outcome') delete args.outcome;
const call = { function: { name: 'done', arguments: change === 'malformed' ? '{' : JSON.stringify(args) } };
const calls = change === 'duplicate' ? [call, call] : change === 'mixed'
? [call, { function: { name: 'click_ax', arguments: '{"ref_id":"ref_1"}' } }] : [call];
assert.equal(await agent._applyPendingPageFeedback(tab, messages, () => {}, { responseToolCalls: calls }), !completionSurvives(change));
assert.equal(agent._activeTaskBinding(messages).text, 'Publish a WebBrain post');
} finally { agent._releaseRunEntry(tab); }
});
}
for (const change of ['feed', 'label', 'href', 'ancestor', 'user', 'unknown', 'iframe', 'base', 'truncated', 'missing', 'submit', 'coordinates']) {
// Unknown-attribution and child-frame DOM are automatic content churn; the
// legacy AX comparison still certifies an unchanged target context.
const survives = ['feed', 'unknown', 'iframe'].includes(change);
test(`${build}: response navigation ${survives ? 'survives' : 'rejects'} ${change} feedback`, async () => {
const agent = setup(Agent), tab = nextTab++;
const original = 'region "Timeline" [ref_1]\n article "News A" [ref_2]\n time "1m" [ref_3]\nregion "Account" [ref_4]\n link "Yeni Gönderi" [ref_5] href="/publish"\nform [ref_7]\n button "Publish" [ref_8] type="submit"';
let page = { success: true, pageContent: original };
agent.executeTool = async () => page;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab), messages = [{ role: 'system', content: '' }, { role: 'user', content: 'Post about WebBrain' }];
binding.send({ kind: 'dom', source: 'page', target: 'time' });
assert.equal(await agent._applyPendingPageFeedback(tab, messages), true);
assert.equal(messages.at(-1).webbrainAppOwnedKind, 'page_feedback');
assert.equal(agent._activeTaskBinding(messages).text, 'Post about WebBrain');
page = { success: true, pageContent: original.replace('News A', 'News B').replace('1m', '2m') };
if (change === 'label') page.pageContent = page.pageContent.replace('Yeni Gönderi', 'Delete account');
if (change === 'href') page.pageContent = page.pageContent.replace('/publish', '/delete');
if (change === 'ancestor') page.pageContent = page.pageContent.replace('Account', 'Other account');
if (change === 'missing') page.pageContent = page.pageContent.replace('ref_5', 'ref_6');
if (change === 'truncated') page.depthTruncated = true;
binding.send({ kind: 'dom', source: change === 'user' ? 'user' : change === 'unknown' ? 'unknown' : 'page', target: change === 'base' ? 'base' : 'time' });
if (change === 'iframe') agent._queuePageFeedback(tab, { kind: 'dom', source: 'page', frameId: 1, target: 'time' });
const call = { function: { name: change === 'coordinates' ? 'click' : 'click_ax',
arguments: JSON.stringify(change === 'coordinates' ? { x: 50, y: 50 } : { ref_id: change === 'submit' ? 'ref_8' : 'ref_5' }) } };
const superseded = await agent._applyPendingPageFeedback(tab, messages, () => {}, { responseToolCalls: [call] });
assert.equal(superseded, !survives);
assert.equal(agent._activeTaskBinding(messages).text, 'Post about WebBrain');
} finally { agent._releaseRunEntry(tab); }
});
}
if (build === 'chrome') {
test('Chrome execute_js returns without dispatch when the page-side revision gate rejects it', async () => {
const tab = nextTab++, agent = setup(Agent);
const previousSendMessage = api.tabs.sendMessage;
const previousEnable = cdpClient.enableDevDiagnostics, previousEvaluate = cdpClient.evaluate;
const previousEvaluateFunction = cdpClient.evaluateFunction;
let declaration = '', passedArgs = [];
try {
await agent._claimRunEntry(tab, 'interactive');
await agent._beginPageFeedbackRun(tab, 'interactive');
const run = agent._pageFeedbackRuns.get(tab);
run.frames.set(0, { token: 'execute-js-document', id: 'document-1' });
api.tabs.sendMessage = async (_tab, message) => message.action === 'page_monitor_dispatch'
? { ready: true, guard: { runToken: run.token, documentToken: 'execute-js-document',
revision: 7, operationId: message.params.operationId } }
: { ready: true };
cdpClient.enableDevDiagnostics = async () => {};
cdpClient.evaluateFunction = async (_tab, value, args) => {
declaration = value; passedArgs = args;
assert.equal(typeof args[0], 'object');
assert.equal(typeof args[1], 'string');
return { result: { value: { __webbrainPageFeedbackAborted: args[1] } } };
};
const result = await agent._executeDevJavaScript(tab, { code: 'window.__shouldNotRun = true;' });
assert.equal(result.dispatched, false);
assert.equal(result.noDispatch, true);
assert.match(result.error, /page changed during JavaScript preparation/i);
assert.match(declaration, /cancelable: true/);
assert.match(declaration, /if \(!window\.dispatchEvent\(gate\)\) return/);
assert.ok(declaration.indexOf('return (async () =>') > declaration.indexOf('dispatchEvent(gate)'));
assert.match(declaration, /window\.__shouldNotRun = true/);
assert.doesNotMatch(declaration, /execute-js-document|operationId/,
'The page guard must travel as a protocol argument instead of source text');
assert.equal(passedArgs[0].documentToken, 'execute-js-document');
assert.ok(passedArgs[1]);
assert.equal(cdpClient.evaluate, previousEvaluate, 'Guarded execution must not use Runtime.evaluate source construction');
} finally {
cdpClient.enableDevDiagnostics = previousEnable;
cdpClient.evaluate = previousEvaluate;
cdpClient.evaluateFunction = previousEvaluateFunction;
api.tabs.sendMessage = previousSendMessage;
if (agent._pageFeedbackRuns.has(tab)) agent._finishPageFeedbackRun(tab);
agent._releaseRunEntry(tab);
}
});
test('Chrome CDP click fallbacks pass the monitor guard and skip stale DOM clicks', async () => {
const tab = nextTab++;
const previousSendMessage = api.tabs.sendMessage;
const responses = [];
const { pageFeedbackMethods } = await import('../src/chrome/src/agent/page-feedback.js');
class ClickAgent {
static STATE_CHANGE_TOOLS = new Set(['click']);
isRunning() { return true; }
_checkAbort() { return false; }
_persist() {}
}
Object.assign(ClickAgent.prototype, pageFeedbackMethods);
const agent = new ClickAgent();
api.tabs.sendMessage = async (_tab, message) => {
if (message.action === 'page_monitor_dispatch') {
const guard = { runToken: message.params.runToken, documentToken: 'click-document',
revision: 9, operationId: message.params.operationId };
responses.push(guard);
return { ready: true, guard };
}
return { ready: true };
};
await agent._beginPageFeedbackRun(tab, 'interactive');
try {
for (const fallback of ['closed-shadow-node', 'open-shadow-selector']) {
const client = new CDPClient(), declarationCalls = [];
client.resolveSelector = async () => ({ inViewport: false, hitOk: false, nodeId: fallback === 'closed-shadow-node' ? 42 : null,
tag: 'BUTTON', x: 20, y: 30, width: 40, height: 20, text: 'Save' });
client.armFileInputClickGuard = async () => {};
client.consumeFileInputClickGuard = async () => ({ blocked: false });
client.sendCommand = async (_tab, method, params) => {
if (method === 'DOM.resolveNode') return { object: { objectId: 'click-target' } };
if (method === 'Runtime.callFunctionOn') {
declarationCalls.push({ method, params });
return { result: { value: { pageFeedbackPending: true, noDispatch: true, dispatched: false } } };
}
return {};
};
client.evaluateFunction = async (_tab, functionDeclaration, args) => {
declarationCalls.push({ method: 'Runtime.callFunctionOn-global', functionDeclaration, args });
return { result: { value: { pageFeedbackPending: true, noDispatch: true, dispatched: false } } };
};
client.evaluate = async () => { throw new Error('Fallback must pass guarded arguments, not build Runtime.evaluate source'); };
const result = await client.clickElement(tab, '#target', { beforeDispatch: async () => ({ success: true }) });
assert.equal(result.pageFeedbackPending, true);
assert.equal(result.noDispatch, true);
assert.equal(result.dispatched, false);
const call = declarationCalls[0];
const functionDeclaration = call.functionDeclaration || call.params.functionDeclaration;
assert.match(functionDeclaration, /beforePageAgentDomAction\(pageGuard, 'focus'\)/);
assert.match(functionDeclaration, /beforePageAgentDomAction\(pageGuard, 'click'\)/);
const focusCall = functionDeclaration.includes('this.focus()') ? 'this.focus()' : 'el.focus()';
const clickCall = functionDeclaration.includes('this.click()') ? 'this.click()' : 'el.click()';
assert.ok(functionDeclaration.lastIndexOf("beforePageAgentDomAction(pageGuard, 'focus')") < functionDeclaration.indexOf(focusCall));
assert.ok(functionDeclaration.lastIndexOf("beforePageAgentDomAction(pageGuard, 'click')") < functionDeclaration.indexOf(clickCall));
const passedGuard = call.args
? call.args.at(-1)
: call.params.arguments.at(-1).value;
assert.deepEqual(passedGuard, responses.at(-1));
}
} finally {
agent._finishPageFeedbackRun(tab);
api.tabs.sendMessage = previousSendMessage;
}
});
}
test(`${build}: observations are isolated by run, frame, document and sequence`, async () => {
const agent = setup(Agent), tab = nextTab++;
assert.equal(agent.pageMonitorState(sender(tab), 'a').active, false);
await agent._claimRunEntry(tab, 'interactive');
try {
const main = bind(agent, tab), child = bind(agent, tab, 2, 'child-doc', 'child-token');
assert.equal(main.send({}).accepted, true);
assert.equal(child.send({ kind: 'selection' }).accepted, true);
assert.equal(agent.observePageFeedback(main.from, { ...main.state, seq: 1, kind: 'input', source: 'user' }).accepted, false);
assert.equal(agent.observePageFeedback(sender(tab + 1), { ...main.state, seq: 2 }).accepted, false);
assert.equal(agent.observePageFeedback(main.from, { ...main.state, seq: 2, runToken: 'old-run' }).accepted, false);
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'document-2', url: 'https://example.com/new', transitionType: 'typed' }, 'committed');
assert.equal(main.send({}).accepted, false);
assert.equal(child.send({}).accepted, false);
assert.equal(agent.pageMonitorState(main.from, 'old-document').active, false);
const replacement = bind(agent, tab, 0, 'document-2', 'replacement');
assert.equal(replacement.send({}).accepted, true);
} finally { agent._releaseRunEntry(tab); }
assert.equal(agent._pageFeedbackRuns.size, 0);
});
test(`${build}: detached-frame gestures release the idle gate after their lease expires`, async () => {
const agent = setup(Agent), tab = nextTab++;
agent._pageFeedbackGestureLeaseMs = 20;
await agent._claimRunEntry(tab, 'interactive');
try {
const child = bind(agent, tab, 2, 'detached-child', 'detached-token');
assert.equal(child.send({ kind: 'activity', interacting: true }).accepted, true);
const run = agent._pageFeedbackRuns.get(tab);
assert.equal(run.gestures.has(2), true);
// Removing a frame does not always produce a committed navigation or a
// final interacting:false message from the destroyed document.
run.frames.delete(2); run.documents.delete(2);
await agent._waitForPageFeedbackIdle(tab);
assert.equal(run.gestures.has(2), false);
assert.equal(run.gestureLeases.has(2), false);
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: run startup awaits every accessible frame and cleanup stops all of them`, async () => {
const agent = setup(Agent), tab = nextTab++, entered = deferred(), release = deferred();
const states = new Map([[0, false], [2, false]]);
const previousNavigation = api.webNavigation, previousMessage = api.tabs.sendMessage;
api.webNavigation = { getAllFrames: async () => [
{ frameId: 0, documentId: 'top-doc', parentFrameId: -1, url: 'https://example.com/' },
{ frameId: 2, documentId: 'child-doc', parentFrameId: 0, url: 'https://example.com/frame' },
{ frameId: 9, parentFrameId: 0 },
] };
const sendFrame = async (frameId, message) => {
if (frameId === 9) throw new Error('Restricted frame');
if (message.action !== 'page_monitor_state') return {};
if (frameId === 2 && message.active) { entered.resolve(); await release.promise; }
states.set(frameId, message.active); return { ready: true };
};
// Model real broadcast semantics: all frames receive the message, but the
// caller only waits for the first responding frame unless it targets each.
api.tabs.sendMessage = async (_tab, message, options) => options?.frameId === undefined
? Promise.any([0, 2, 9].map(frameId => sendFrame(frameId, message))) : sendFrame(options.frameId, message);
let complete = false;
const starting = agent._claimRunEntry(tab, 'interactive').then(() => { complete = true; });
try {
await entered.promise;
await new Promise(resolve => setImmediate(resolve));
assert.equal(complete, false, 'A top-frame response must not bypass a delayed child acknowledgement');
assert.equal(agent._pageFeedbackRuns.get(tab).documents.get(2)?.parentFrameId, 0,
'Frame startup records parent IDs so later _parent navigation can be correlated');
release.resolve(); await starting;
assert.deepEqual([...states.values()], [true, true]);
agent._releaseRunEntry(tab);
await new Promise(resolve => setImmediate(resolve));
assert.deepEqual([...states.values()], [false, false]);
} finally {
release.resolve(); await starting; agent._releaseRunEntry(tab);
api.webNavigation = previousNavigation; api.tabs.sendMessage = previousMessage;
}
});
test(`${build}: navigation bursts and DOM storms remain bounded and retain navigation intent`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
let binding = bind(agent, tab);
for (let i = 0; i < 100; i++) binding.send({ kind: 'dom', source: 'page', target: `button#${i}` });
assert.equal(agent._pageFeedbackRuns.get(tab).events.size, 32);
for (const [type, qualifiers] of [['history', []], ['fragment', []], ['committed', ['forward_back']]]) {
agent.observePageNavigation({ tabId: tab, frameId: 0, url: `https://example.com/${type}`,
transitionQualifiers: qualifiers, transitionType: type === 'history' ? 'typed' : 'link' }, type);
}
const navigation = [...agent._pageFeedbackRuns.get(tab).events.values()].find(event => event.kind === 'navigation');
assert.equal(navigation.before, 'https://example.com/new');
assert.equal(navigation.after, 'https://example.com/committed');
assert.equal(navigation.source, 'user');
for (let i = 0; i < 100; i++) agent._queuePageFeedback(tab, { kind: 'dom', source: 'page', frameId: 0, target: `div#storm${i}` });
assert.equal(agent._pageFeedbackRuns.get(tab).events.size, 32);
assert.ok([...agent._pageFeedbackRuns.get(tab).events.values()].some(event => event.kind === 'navigation'),
'Animation/DOM storms must not evict the persistent main-frame navigation notice');
const messages = [], updates = [];
await agent._applyPendingPageFeedback(tab, messages, (type, data) => updates.push({ type, data }));
assert.equal(updates.filter(update => update.data.navigation).length, 1);
assert.match(messages[0].content, /navigationType/);
assert.equal(agent._pageFeedbackRuns.get(tab).events.size, 0);
} finally { agent._releaseRunEntry(tab); }
});
for (const streaming of [false, true]) {
test(`${build}/${streaming ? 'stream' : 'chat'}: final-step page feedback suppresses a superseded completion`, async () => {
const tab = nextTab++, entered = deferred(), release = deferred(), staleCompletion = 'The task is complete on the old page.';
let providerCalls = 0, recoveryPrompt = '';
const provider = { name: 'feedback final-step test', model: 'test', promptTier: 'full', contextWindow: 128000,
supportsTools: true, supportsVision: false };
provider.chat = async function (messages) {
providerCalls++;
if (providerCalls === 1 && !streaming) {
entered.resolve(); await release.promise;
return { content: staleCompletion, toolCalls: null };
}
recoveryPrompt = JSON.stringify(messages);
return { content: null, toolCalls: [{ id: 'feedback_recovery_done',
function: { name: 'done', arguments: JSON.stringify({ summary: 'The page changed before the task was verified.', outcome: 'partial' }) } }] };
};
if (streaming) {
provider.chatStream = async function* () {
providerCalls++;
entered.resolve(); await release.promise;
yield { type: 'text', content: staleCompletion };
yield { type: 'done' };
};
}
const agent = setup(Agent, provider), updates = [];
agent.planBeforeAct = false;
agent.maxSteps = 1;
agent.autoScreenshot = 'off';
agent._skipPermissionGate = true;
agent._maybeRunPlannerGate = async () => ({ proceed: true, requestKind: 'execute', requiresStateChange: true });
agent._maybeReinjectAdapter = async () => {};
agent._ensureProgressSessionForCurrentTask = async () => ({ mode: 'inactive' });
agent._currentTaskLedgerRows = () => [];
agent._persist = () => {};
const run = streaming ? agent.processMessageStream.bind(agent) : agent.processMessage.bind(agent);
const running = run(tab, 'finish the existing task', (type, data) => updates.push({ type, data }), 'act');
try {
await entered.promise;
const binding = bind(agent, tab);
assert.equal(binding.send({ kind: 'input', source: 'user', target: 'input#filter' }).accepted, true);
release.resolve();
const final = await running;
assert.equal(providerCalls, 2, 'Only the bounded step-limit handoff may follow the one allowed agent step');
assert.equal(String(final).includes(staleCompletion), false, 'A completion formed against the previous page must be discarded');
assert.ok(updates.some(update => update.type === 'page_feedback'), 'The current page observation should be delivered');
assert.match(final, /page changed before the task was verified/i, 'The handoff must be based on the refreshed page context');
assert.ok(recoveryPrompt.includes('BROWSER STATE UPDATE'), 'The bounded recovery receives the page feedback in its model context');
assert.equal((agent.conversations.get(tab) || []).some(message => String(message.content || '').includes('BROWSER STATE UPDATE')), false,
'A finished run\'s page observation must not carry into the next run');
} finally {
release.resolve();
if (agent._pageFeedbackRuns.has(tab)) agent._finishPageFeedbackRun(tab);
agent._releaseRunEntry(tab);
}
});
}
test(`${build}: viewport resize invalidates coordinates and waits for geometry to settle`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
agent.screenshotCaptures.set(tab, { captureId: 'stale-coordinates' });
agent._jevSessions = new Map([[tab, { disabled: false, queue: ['prepared'], snapshot: {} }]]);
assert.equal(binding.send({ kind: 'resize', source: 'unknown', target: 'viewport', viewport: { width: 900, height: 600, scale: 1 } }).accepted, true);
assert.equal(agent.screenshotCaptures.has(tab), false);
assert.equal(agent._jevSessions.get(tab).disabled, true);
assert.deepEqual(agent._jevSessions.get(tab).queue, []);
assert.equal(agent._pageFeedbackRuns.get(tab).lastUserAt, 0, 'Resize alone does not prove physical user input');
assert.ok(agent._pageFeedbackRuns.get(tab).lastActivityAt > 0, 'Unknown geometry activity must settle before replanning');
agent._pageFeedbackRuns.get(tab).lastActivityAt = 0;
binding.send({ kind: 'resize', source: 'page', target: 'viewport', viewport: { width: 500, height: 200 } });
assert.equal(agent._pageFeedbackRuns.get(tab).lastActivityAt, 0, 'Page layout changes to embedded frame dimensions must not extend the user idle gate');
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: agent resize feedback invalidates caches without queueing or idle delay`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
agent._jevSessions = new Map([[tab, { disabled: false, queue: ['prepared'], snapshot: {} }]]);
agent.screenshotCaptures.set(tab, { captureId: 'stale-resize' });
let clearedTypeField = false;
agent.clearLastTypeFieldIdent = id => { if (id === tab) clearedTypeField = true; };
assert.equal(binding.send({ kind: 'resize', source: 'agent', target: 'viewport',
viewport: { width: 900, height: 600, scale: 1 } }).accepted, true);
const run = agent._pageFeedbackRuns.get(tab);
assert.equal(run.events.size, 0, 'Agent geometry changes do not become page feedback');
assert.equal(run.lastActivityAt, 0, 'Agent geometry changes do not add an idle delay');
assert.equal(agent.screenshotCaptures.has(tab), false);
assert.equal(agent._jevSessions.get(tab).disabled, true);
assert.deepEqual(agent._jevSessions.get(tab).queue, []);
assert.equal(clearedTypeField, true);
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: resize_window brackets browser updates with the active monitor marker`, async () => {
const agent = setup(Agent), tab = nextTab++;
const previousGet = api.tabs.get, previousSend = api.tabs.sendMessage, previousWindows = api.windows;
const messages = [];
api.tabs.get = async id => ({ id, url: 'https://example.com/new', windowId: 23 });
api.tabs.sendMessage = async (_id, message) => { messages.push(message); return { ready: true }; };
api.windows = { get: async () => ({ state: 'normal' }), update: async () => ({}) };
agent._getWindowInfo = async () => ({ success: true, viewport: { width: 900, height: 600 }, note: 'test' });
await agent._claimRunEntry(tab, 'interactive');
try {
await agent._beginPageFeedbackRun(tab, 'interactive');
const result = await agent._resizeWindow(tab, { width: 900, height: 600 });
assert.equal(result.resized, true);
const markers = messages.filter(message => ['page_monitor_resize_begin', 'page_monitor_resize_finish'].includes(message.action));
assert.deepEqual(markers.map(message => message.action), ['page_monitor_resize_begin', 'page_monitor_resize_finish']);
assert.equal(markers[0].params.runToken, markers[1].params.runToken);
assert.equal(markers[0].params.operationId, markers[1].params.operationId);
assert.deepEqual(markers[1].params.expectedViewport, { width: 900, height: 600 });
} finally {
if (agent._pageFeedbackRuns.has(tab)) agent._finishPageFeedbackRun(tab);
agent._releaseRunEntry(tab);
api.tabs.get = previousGet;
api.tabs.sendMessage = previousSend;
if (previousWindows === undefined) delete api.windows; else api.windows = previousWindows;
}
});
test(`${build}: navigation arriving during a page read gets its own feedback ID`, async () => {
const agent = setup(Agent), tab = nextTab++, entered = deferred(), release = deferred();
const updates = [], messages = [];
await agent._claimRunEntry(tab, 'interactive');
try {
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/first', transitionType: 'typed' }, 'history');
agent.executeTool = async () => { entered.resolve(); await release.promise; return { success: true }; };
const first = agent._applyPendingPageFeedback(tab, messages, (_type, data) => updates.push(data));
await entered.promise;
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/second', transitionType: 'typed' }, 'history');
release.resolve();
await first;
await agent._applyPendingPageFeedback(tab, messages, (_type, data) => updates.push(data));
assert.equal(updates.length, 2);
assert.notEqual(updates[0].id, updates[1].id, 'Both navigation notices must survive UI deduplication');
assert.equal(updates[0].after, 'https://example.com/first');
assert.equal(updates[1].after, 'https://example.com/second');
} finally { agent._releaseRunEntry(tab); }
});
for (const tool of ['navigate', 'go_back', 'go_forward']) {
test(`${build}: ${tool} does not hide navigation during the unsaved-changes probe`, async () => {
const agent = setup(Agent), tab = nextTab++, entered = deferred(), release = deferred();
delete agent.executeTool;
allowBatchPreparation(agent);
const destination = 'https://example.com/destination';
agent._probeUnsavedChanges = async () => {
entered.resolve(); await release.promise;
return { success: false, dispatched: false, noDispatch: true, error: 'Unsaved fields block navigation' };
};
await agent._claimRunEntry(tab, 'interactive');
try {
const action = agent.executeTool(tab, tool, { url: destination });
await entered.promise;
agent.observePageNavigation({ tabId: tab, frameId: 0, url: destination, transitionType: 'reload' }, 'history');
const queuedDuringPreparation = agent._hasPendingPageFeedback(tab);
release.resolve();
assert.equal((await action).noDispatch, true);
assert.equal(queuedDuringPreparation, true, 'Only a dispatched navigation may hide its own browser event');
} finally { release.resolve(); agent._releaseRunEntry(tab); }
});
}
test(`${build}: a child-frame click only correlates compatible frame navigation`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
const child = bind(agent, tab, 2, 'child', 'child-token', 'ChildFrame');
const parent = bind(agent, tab, 1, 'parent', 'parent-token', 'ParentFrame');
bind(agent, tab, 3, 'sibling', 'sibling-token', 'SiblingTarget');
const run = agent._pageFeedbackRuns.get(tab);
run.documents.set(2, { id: 'child', parentFrameId: 1 });
run.documents.set(1, { id: 'parent', parentFrameId: 0 });
run.documents.set(3, { id: 'sibling', parentFrameId: 1 });
child.send({ kind: 'activity', source: 'agent', operation: 'click' });
for (const frameId of [0, 3, 2]) agent.observePageNavigation({ tabId: tab, frameId,
url: `https://example.com/frame-${frameId}`, transitionType: 'link' }, 'history');
const events = [...agent._pageFeedbackRuns.get(tab).events.values()];
assert.deepEqual(events.map(event => event.frameId), [0, 3],
'A click without a known destination explains only its own frame\'s same-document route update');
agent._pageFeedbackRuns.get(tab).events.clear();
child.send({ kind: 'activity', source: 'agent', operation: 'click', navigationTarget: '_top',
navigationUrl: 'https://example.com/top' });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/top', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'An explicit _top click can correlate its exact top-frame destination');
agent.observePageNavigation({ tabId: tab, frameId: 3, url: 'https://example.com/sibling', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'A declared top target must still preserve sibling changes');
agent._pageFeedbackRuns.get(tab).events.clear();
child.send({ kind: 'activity', source: 'agent', operation: 'click', navigationUrl: 'https://example.com/expected' });
agent.observePageNavigation({ tabId: tab, frameId: 2, url: 'https://example.com/unrelated', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'The clicked frame\'s own same-document route update is the click\'s effect');
agent.observePageNavigation({ tabId: tab, frameId: 3, url: 'https://example.com/unrelated-sibling', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'A route update in another frame remains visible');
agent._pageFeedbackRuns.get(tab).events.clear();
child.send({ kind: 'activity', source: 'agent', operation: 'click', navigationTarget: '_parent',
navigationUrl: 'https://example.com/parent' });
agent.observePageNavigation({ tabId: tab, frameId: 1, url: 'https://example.com/parent', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'A nested frame _parent click correlates to its actual parent');
agent._pageFeedbackRuns.get(tab).events.clear();
child.send({ kind: 'activity', source: 'agent', operation: 'click', navigationTargetName: 'SiblingTarget',
navigationUrl: 'https://example.com/sibling' });
agent.observePageNavigation({ tabId: tab, frameId: 3, url: 'https://example.com/sibling', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'A named target click correlates to the uniquely named sibling frame');
agent._pageFeedbackRuns.get(tab).events.clear();
parent.send({ kind: 'activity', source: 'agent', operation: 'click', navigationTargetName: 'missing-frame',
navigationUrl: 'https://example.com/ambiguous' });
agent.observePageNavigation({ tabId: tab, frameId: 3, url: 'https://example.com/ambiguous', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'An unresolved named target cannot suppress another frame navigation');
agent._pageFeedbackRuns.get(tab).events.clear();
child.send({ kind: 'activity', source: 'agent', operation: 'click', navigationUrl: 'https://example.com/expected' });
agent.observePageNavigation({ tabId: tab, frameId: 2, parentFrameId: 1, documentId: 'child-redirect',
url: 'https://example.com/unrelated-redirect', transitionType: 'link', transitionQualifiers: ['server_redirect'] }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'The first same-frame redirect may commit at a URL different from the armed destination');
child.send({ kind: 'activity', source: 'agent', operation: 'click', navigationTarget: '_top', navigationUrl: 'javascript:alert(1)' });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/safe', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'Non-web click targets cannot correlate browser navigation');
agent._pageFeedbackRuns.get(tab).events.clear();
const main = bind(agent, tab, 0, 'main-before', 'main-before-token');
main.send({ kind: 'activity', source: 'agent', operation: 'click', navigationUrl: 'https://example.com/expected' });
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'main-unrelated',
url: 'https://example.com/unrelated', transitionType: 'link' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'A full-document navigation to a different URL remains visible');
} finally { agent._releaseRunEntry(tab); }
});
if (build === 'firefox') for (const transport of ['content', 'bidi']) {
test(`firefox: ${transport} navigation skips dispatch after feedback during an allowed probe`, async () => {
const { firefoxBidi } = await import('../src/firefox/src/bidi/client.js');
const agent = setup(Agent), tab = nextTab++, entered = deferred(), release = deferred();
delete agent.executeTool;
allowBatchPreparation(agent);
let dispatches = 0;
const originalUpdate = api.tabs.update, originalRequest = firefoxBidi.request;
api.tabs.update = async () => { dispatches++; return {}; };
firefoxBidi.request = async () => { dispatches++; return { success: true }; };
if (transport === 'bidi') firefoxBidi.runs.set(tab, { runId: 'native-navigation', bound: true });
agent._probeUnsavedChanges = async () => { entered.resolve(); await release.promise; return null; };
await agent._claimRunEntry(tab, 'interactive');
try {
const destination = 'https://example.com/destination';
const action = agent.executeTool(tab, 'navigate', { url: destination });
await entered.promise;
agent.observePageNavigation({ tabId: tab, frameId: 0, url: destination, transitionType: 'reload' }, 'history');
release.resolve();
const result = await action;
assert.equal(dispatches, 0);
assert.equal(result.noDispatch, true);
assert.equal(result.pageFeedbackPending, true);
} finally {
release.resolve(); agent._releaseRunEntry(tab);
firefoxBidi.runs.delete(tab); firefoxBidi.request = originalRequest; api.tabs.update = originalUpdate;
}
});
}
for (const kind of ['interactive', 'cloud', 'scheduled', 'workflow']) {
test(`${build}: ${kind} feedback refreshes the page without creating a trusted text correction`, async () => {
const agent = setup(Agent), tab = nextTab++, updates = [];
const options = { cloudRun: kind === 'cloud', scheduledRun: kind === 'scheduled', detachedRequestId: 'request' };
await agent._claimRunEntry(tab, kind, options);
try {
agent._beginSteeringRun(tab, () => {}, options);
agent._recordSocialPublicationSteering = () => assert.fail('Observation became a trusted instruction');
const binding = bind(agent, tab);
assert.equal(binding.send({}).accepted, true);
agent._jevSettings = async () => assert.fail('Stale fast-path task was resurrected');
assert.equal(await agent._maybeJevFastTurn(tab, 'Original task', [], 'act', new Set(), {}, null), null);
const messages = [];
assert.equal(await agent._applyPendingRunFeedback(tab, messages, (type, data) => updates.push({ type, data })), true);
assert.match(messages[0].content, /observations, not a new user instruction/);
assert.match(messages[0].content, /untrusted_page_content/);
assert.match(messages[0].content, /The current view/);
assert.equal(updates.filter(update => update.type === 'steering_applied').length, 0);
assert.equal(updates.filter(update => update.type === 'page_feedback').length, 1);
} finally { agent._finishSteeringRun(tab); agent._releaseRunEntry(tab); }
});
}
for (const streaming of [false, true]) {
test(`${build}: ${streaming ? 'stream' : 'chat'} discards an in-flight response after page feedback`, async () => {
const entered = deferred(), release = deferred(), requests = [];
const response = async messages => {
requests.push(structuredClone(messages));
if (requests.length === 1) { entered.resolve(); await release.promise;
return { content: 'Old answer', toolCalls: [{ id: 'old-click', function: { name: 'click', arguments: '{"text":"Old target"}' } }] }; }
return { content: 'Updated answer' };
};
const agent = setup(Agent, { chat: response, async *chatStream(messages) {
const value = await response(messages);
yield { type: 'text', content: value.content };
if (value.toolCalls) yield { type: 'tool_call', content: value.toolCalls.map(call => ({ ...call, index: 0 })) };
yield { type: 'done' };
} });
const tab = nextTab++, updates = [];
const options = { detachedRequestId: 'request', askStreamingEnabled: false };
const run = streaming ? agent.processMessageStream(tab, 'Original task', (type, data) => updates.push({ type, data }), 'ask', options)
: agent.processMessage(tab, 'Original task', (type, data) => updates.push({ type, data }), 'ask', [], options);
await entered.promise;
assert.equal(bind(agent, tab).send({ kind: 'dom', source: 'page' }).accepted, true);
release.resolve();
assert.equal(await run, 'Updated answer');
assert.equal(requests.length, 2);
assert.match(requests[1].at(-1).content, /BROWSER STATE UPDATE/);
assert.equal(requests[1].some(message => message.tool_calls?.some(call => call.id === 'old-click')), false);
assert.equal(agent._pageFeedbackRuns.size, 0);
});
}
test(`${build}: tool feedback preserves completed results and skips undispatched siblings`, async () => {
const agent = setup(Agent), tab = nextTab++, entered = deferred(), release = deferred();
allowBatchPreparation(agent);
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
let dispatched = 0;
agent.executeTool = async () => { dispatched++; entered.resolve(); await release.promise; return { success: true, pageContent: 'Old view' }; };
const calls = [1, 2].map(index => ({ id: `read-${index}`, function: { name: 'get_accessibility_tree', arguments: '{}' } }));
const messages = [{ role: 'assistant', content: null, tool_calls: calls }];
const result = agent._executeToolBatch(tab, calls, messages, () => {}, {}, null, new Set(['get_accessibility_tree']), 1);
await entered.promise;
binding.send({ kind: 'scroll' }); release.resolve();
assert.equal((await result).action, 'continue');
assert.equal(dispatched, 1);
assert.equal(messages.filter(message => message.role === 'tool').length, 2);
assert.equal(JSON.parse(messages.at(-1).content).pageFeedbackPending, true);
assert.equal(JSON.parse(messages.at(-1).content).noDispatch, true);
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: the idle gate restarts for physical activity, not automatic DOM updates, and Stop wakes it`, async () => {
const agent = setup(Agent), tab = nextTab++;
agent._pageFeedbackIdleMs = 40;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
binding.send({});
const at = agent._pageFeedbackRuns.get(tab).lastUserAt;
binding.send({ kind: 'dom', source: 'user' });
assert.equal(agent._pageFeedbackRuns.get(tab).lastUserAt, at);
const started = Date.now();
await agent._waitForPageFeedbackIdle(tab);
assert.ok(Date.now() - started >= 30);
binding.send({ kind: 'scroll', source: 'user' });
const externalScrollAt = Date.now();
await agent._waitForPageFeedbackIdle(tab);
assert.ok(Date.now() - externalScrollAt >= 30, 'A physical scroll receives the idle gate');
binding.send({ kind: 'click', source: 'user' });
const automaticScrollAt = Date.now();
const ticker = setInterval(() => binding.send({ kind: 'scroll', source: 'unknown' }), 5);
try { await agent._waitForPageFeedbackIdle(tab); }
finally { clearInterval(ticker); }
assert.ok(Date.now() - automaticScrollAt >= 30 && Date.now() - automaticScrollAt < 100,
'Repeated unattributed scroll events must not restart the physical-input idle deadline');
binding.send({ kind: 'activity', interacting: true });
const waiting = agent._waitForPageFeedbackIdle(tab);
agent.abort(tab);
await assert.rejects(waiting, { name: 'AbortError' });
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: native dispatch checks feedback after preparation and correlates agent navigation`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
await beforePageAgentDispatch(api, tab, { kind: 'navigate', url: 'https://example.com/destination' });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/destination', transitionType: 'link' }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), false);
await beforePageAgentDispatch(api, tab, { kind: 'navigate', history: true });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/agent-back', transitionQualifiers: ['forward_back'] }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), false);
await beforePageAgentDispatch(api, tab, { kind: 'click', selector: '#old' });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/manual-back', transitionQualifiers: ['forward_back'] }, 'history');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'A browser Back action is not the preceding agent click');
binding.send({});
await assert.rejects(beforePageAgentDispatch(api, tab, { kind: 'input' }), { code: 'page_feedback_pending' });
await beforePageAgentDispatch(api, tab, { kind: 'input', release: true });
await beforePageAgentDispatch(api, tab, { kind: 'input', release: true, documentToken: 'navigated-away-document' });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/manual', transitionType: 'typed' }, 'history');
const messages = [], updates = [];
await agent._applyPendingPageFeedback(tab, messages, (type, data) => updates.push({ type, data }));
assert.equal(updates.at(-1).data.navigation, true);
assert.equal(updates.at(-1).data.after, 'https://example.com/manual');
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: frame click preparation installs a fence without claiming the click`, async () => {
const agent = setup(Agent), tab = nextTab++, previousMessage = api.tabs.sendMessage;
const messages = [];
api.tabs.sendMessage = async (_tab, message, options) => {
messages.push({ message, frameId: options?.frameId });
if (message.action === 'page_monitor_dispatch') return { ready: true, guard: {
documentToken: 'child-token', revision: 0, operationId: message.params.operationId,
navigationCandidate: true,
} };
return { ready: true };
};
await agent._claimRunEntry(tab, 'interactive');
try {
bind(agent, tab, 2, 'child-doc', 'child-token');
const run = agent._pageFeedbackRuns.get(tab);
run.navigation = { at: Date.now(), url: '', kind: 'click', frameId: 2 };
const guard = await beforePageAgentDispatch(api, tab, {
kind: 'click', selector: '#inside', frameId: 2, fenceOnly: true, prepareMonitor: true,
});
assert.equal(guard.operationId, messages.find(entry => entry.message.action === 'page_monitor_dispatch').message.params.operationId);
assert.deepEqual(messages.filter(entry => ['page_monitor_prepare', 'page_monitor_dispatch'].includes(entry.message.action))
.map(entry => entry.message.action), ['page_monitor_prepare', 'page_monitor_dispatch']);
assert.equal(messages.at(-1).frameId, 2);
assert.equal(messages.at(-1).message.params.fenceOnly, true);
assert.equal(run.navigation.kind, 'click', 'A preparation fence cannot consume an earlier navigation correlation');
} finally {
agent._releaseRunEntry(tab);
api.tabs.sendMessage = previousMessage;
}
});
test(`${build}: intervention during the dispatch handshake blocks the prepared action`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
await assert.rejects(beforePageAgentDispatch({ tabs: { sendMessage: async (_tab, _msg, options) => {
assert.equal(options.frameId, 0);
binding.send({ kind: 'click', target: 'button#new' });
} } }, tab, { kind: 'click', selector: '#old' }), { code: 'page_feedback_pending' });
assert.equal(agent._hasPendingPageFeedback(tab), true);
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: click preparation and proven no-dispatch navigation do not hide external navigation`, async () => {
const { installPageFeedback } = await import(`../src/${build}/src/agent/page-feedback.js`);
class FixtureAgent {
static STATE_CHANGE_TOOLS = new Set(['click', 'navigate']);
isRunning() { return true; }
_checkAbort() { return false; }
async executeTool(tabId, name) {
await beforePageAgentDispatch(api, tabId, { kind: name });
if (name === 'click') {
this.observePageNavigation({ tabId, frameId: 0, url: 'https://example.com/reloaded', transitionType: 'reload' }, 'committed');
assert.equal(this._hasPendingPageFeedback(tabId), true, 'Preparation must not arm click navigation correlation');
}
return { success: false, dispatched: false, noDispatch: true };
}
}
installPageFeedback(FixtureAgent);
const agent = new FixtureAgent(), tab = nextTab++;
await agent._beginPageFeedbackRun(tab, 'interactive');
try {
const click = await agent.executeTool(tab, 'click', {});
assert.equal(click.pageFeedbackPending, true);
agent._pageFeedbackRuns.get(tab).events.clear();
await agent.executeTool(tab, 'navigate', {});
assert.equal(agent._pageFeedbackRuns.get(tab).navigation, null, 'Failed navigation must release its correlation');
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/automatic', transitionType: 'reload' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), true);
} finally { agent._finishPageFeedbackRun(tab); }
});
test(`${build}: finishing an action releases attribution in all dispatched frames`, async () => {
const { installPageFeedback } = await import(`../src/${build}/src/agent/page-feedback.js`);
class FixtureAgent {
static STATE_CHANGE_TOOLS = new Set(['click']);
isRunning() { return true; }
_checkAbort() { return false; }
async executeTool(tabId) {
await beforePageAgentDispatch(api, tabId, { kind: 'click', frameId: 2 });
return { success: true };
}
}
installPageFeedback(FixtureAgent);
const agent = new FixtureAgent(), tab = nextTab++, finished = [];
const originalMessage = api.tabs.sendMessage;
api.tabs.sendMessage = async (_tab, message, options) => {
if (message.action === 'page_monitor_finish') finished.push(options.frameId);
return {};
};
try {
await agent._beginPageFeedbackRun(tab, 'interactive');
assert.equal((await agent.executeTool(tab, 'click', {})).success, true);
assert.deepEqual(finished.sort(), [0, 2]);
} finally { agent._finishPageFeedbackRun(tab); api.tabs.sendMessage = originalMessage; }
});
test(`${build}: feedback interruption after dispatch retains uncertain action evidence`, async () => {
const agent = setup(Agent), tab = nextTab++;
agent.executeTool = Agent.prototype.executeTool;
agent._uncertainTextMutationBlock = async () => null;
agent._executeToolImpl = async (_tab, _name, _args, _update, context) => {
context._contentActionDispatchState.started = true;
const error = new Error('External interaction after pointer down');
error.code = 'page_feedback_pending'; throw error;
};
await agent._claimRunEntry(tab, 'interactive');
try {
const result = await agent.executeTool(tab, 'click', { text: 'Continue' });
assert.equal(result.dispatched, true);
assert.equal(result.outcomeUnknown, true);
assert.notEqual(result.noDispatch, true);
assert.equal(result.retryable, false);
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: click navigation markers expire after one event and redirects stay document-scoped`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
let binding = bind(agent, tab);
binding.send({ kind: 'activity', source: 'agent', operation: 'click', navigationUrl: 'https://example.com/destination' });
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'agent-document',
url: 'https://example.com/destination', transitionType: 'link' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'The click-caused commit is correlated');
assert.equal(agent._pageFeedbackRuns.get(tab).navigation, null, 'The click marker is consumed after commit');
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'timer-reload',
url: 'https://example.com/destination', transitionType: 'reload' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'A later reload to the same URL is still visible');
assert.equal([...agent._pageFeedbackRuns.get(tab).events.values()].at(-1).source, 'unknown');
agent._pageFeedbackRuns.get(tab).events.clear();
binding = bind(agent, tab, 0, 'timer-reload', 'content-timer-reload');
binding.send({ kind: 'activity', source: 'agent', operation: 'click' });
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'redirected-document',
url: 'https://example.com/final', transitionType: 'link', transitionQualifiers: ['server_redirect'] }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'An uncorrelated redirect remains visible even after an agent click');
assert.equal(agent._pageFeedbackRuns.get(tab).navigation, null);
agent._pageFeedbackRuns.get(tab).events.clear();
binding = bind(agent, tab, 0, 'redirected-document', 'content-redirected');
binding.send({ kind: 'activity', source: 'agent', operation: 'click', navigationUrl: 'https://example.com/redirect-start' });
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'redirect-chain-document',
url: 'https://example.com/first-redirect-target', transitionType: 'link', transitionQualifiers: ['server_redirect'] }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'A click destination may commit at its first redirect target');
assert.equal(agent._pageFeedbackRuns.get(tab).navigation.documentId, 'redirect-chain-document');
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'redirect-chain-document',
url: 'https://example.com/final-two', transitionType: 'link', transitionQualifiers: ['client_redirect'] }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'Redirect continuation stays on its exact document');
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'later-navigation',
url: 'https://example.com/automatic', transitionType: 'reload' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'A later navigation outside the redirect chain is visible');
assert.equal(agent._pageFeedbackRuns.get(tab).navigation, null);
} finally { agent._releaseRunEntry(tab); }
});
test(`${build}: GET form submission correlates serialized query by its private base action`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
await agent._beginPageFeedbackRun(tab, 'interactive');
let binding = bind(agent, tab);
binding.send({ kind: 'activity', source: 'agent', operation: 'submit', navigationUrl: 'https://example.com/search',
navigationFormGet: true });
const armed = agent._pageFeedbackRuns.get(tab).navigation;
assert.equal(armed.url, 'https://example.com/search', 'The correlation marker contains only the action path');
assert.equal(armed.kind, 'submit');
assert.equal(armed.formGet, true);
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'form-result',
url: 'https://example.com/search?q=private-form-value', transitionType: 'form_submit' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'A GET form submission can append its successful controls to the query');
assert.equal(agent._pageFeedbackRuns.get(tab).navigation, null);
binding = bind(agent, tab, 0, 'form-result', 'form-result-token');
binding.send({ kind: 'activity', source: 'agent', operation: 'submit', navigationUrl: 'https://example.com/search',
navigationFormGet: true });
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'wrong-form-result',
url: 'https://example.com/other?q=value', transitionType: 'form_submit' }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), true, 'Form-specific correlation still requires the same origin and action path');
} finally { agent._finishPageFeedbackRun(tab); agent._releaseRunEntry(tab); }
});
test(`${build}: first redirect of an armed URL navigation stays agent-attributed`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'interactive');
try {
await agent._beginPageFeedbackRun(tab, 'interactive');
bind(agent, tab);
await beforePageAgentDispatch(api, tab, { kind: 'navigate', url: 'https://example.com/redirect-start' });
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'first-redirect-document',
url: 'https://example.com/redirect-final', transitionType: 'link', transitionQualifiers: ['server_redirect'] }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'The first redirect may commit at a URL different from the armed destination');
assert.equal(agent._pageFeedbackRuns.get(tab).navigation.documentId, 'first-redirect-document');
agent.observePageNavigation({ tabId: tab, frameId: 0, documentId: 'first-redirect-document',
url: 'https://example.com/redirect-final-two', transitionType: 'link', transitionQualifiers: ['client_redirect'] }, 'committed');
assert.equal(agent._hasPendingPageFeedback(tab), false, 'Redirect continuation remains bound to the first committed document');
} finally { agent._finishPageFeedbackRun(tab); agent._releaseRunEntry(tab); }
});
test(`${build}: content feedback uses authenticated sender identity; composer delivery never gates monitoring`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'cloud', { cloudRun: true });
try {
const source = fs.readFileSync(new URL(`../src/${build}/src/background.js`, import.meta.url), 'utf8');
const start = source.indexOf('async function handleMessage(msg, sender) {');
const end = source.indexOf(" if (msg.action === 'chat_steer')", start);
const context = vm.createContext({ agent });
vm.runInContext(`${source.slice(start, end)} }`, context);
const state = await context.handleMessage({ action: 'get_page_monitor_state', documentToken: 'doc' }, sender(tab));
assert.equal(state.active, true);
assert.equal((await context.handleMessage({ action: 'page_feedback', tabId: tab, feedback: {
...state, seq: 1, kind: 'click', source: 'user' } }, {})).accepted, false);
assert.equal((await context.handleMessage({ action: 'page_feedback', feedback: {
...state, seq: 1, kind: 'click', source: 'user' } }, sender(tab))).accepted, true);
assert.equal(source.slice(start, end).includes('composerDeliveryMode'), false);
} finally { agent._releaseRunEntry(tab); }
});
for (const change of ['valid', 'scope', 'target']) {
test(`${build}: workflow revalidates an undispatched step after ${change} feedback`, async () => {
const agent = setup(Agent), tab = nextTab++, updates = [], dispatched = [];
agent.ensureConversationId = async () => 'workflow-conversation';
agent._startSavedWorkflowTraceRun = async () => null;
agent._endSavedWorkflowTraceRun = async () => {};
agent._promptWorkflowTargetHealing = async () => null;
let changed = false, attempt = 0;
agent._currentUrl = async () => changed && change === 'scope' ? 'https://other.example/new' : 'https://example.com/new';
agent.executeTool = async (_tab, name) => {
assert.equal(name, 'get_accessibility_tree');
return { success: true, pageContent: changed && change === 'target' ? 'main "Missing target" [ref_main]'
: `button "Continue" [ref_${changed ? 'fresh' : 'old'}] id="continue"` };
};
agent._executeToolBatch = async (_tab, calls, _messages, update) => {
const call = calls[0];
if (call.function.name === 'scroll') {
dispatched.push('scroll');
update('tool_result', { name: 'scroll', result: { success: true } });
} else if (attempt++ === 0) {
const binding = bind(agent, tab);
changed = true;
binding.send({ kind: 'dom', source: 'page', target: 'button#continue' });
if (change === 'scope') agent.observePageNavigation({ tabId: tab, frameId: 0,
url: 'https://other.example/new', transitionType: 'typed' }, 'history');
update('tool_result', { name: 'click_ax', result: { success: false, noDispatch: true, pageFeedbackPending: true } });
} else {
dispatched.push(JSON.parse(call.function.arguments).ref_id);
update('tool_result', { name: 'click_ax', result: { success: true, dispatched: true, verified: true } });
}
return { action: 'continue' };
};
const scope = { origin: 'https://example.com', pathFamily: '/new' };
const workflow = { id: 'monitor-workflow', name: 'Continue workflow', start: scope,
steps: [{ id: 'scroll', tool: 'scroll', args: { direction: 'down' }, expected: { kind: 'tool_success' } },
{ id: 'click', tool: 'click_ax', scope, args: {}, target: { role: 'button', name: 'Continue', id: 'continue' },
expected: { kind: 'tool_verified' } }] };
const result = await agent.replaySavedWorkflow(tab, workflow, {}, (type, data) => updates.push({ type, data }));
if (change === 'valid') {
assert.equal(result.status, 'completed');
assert.equal(result.matchedSteps, 2);
assert.deepEqual(dispatched, ['scroll', 'ref_fresh']);
} else {
assert.equal(result.status, 'fallback');
assert.equal(result.matchedSteps, 1);
assert.deepEqual(dispatched, ['scroll']);
assert.match(result.prompt, /from step 2/);
assert.match(result.prompt, /BROWSER STATE UPDATE/);
assert.match(result.prompt, /untrusted_page_content/);
}
assert.ok(updates.some(update => update.type === 'page_feedback'));
assert.equal(agent._pageFeedbackRuns.size, 0);
});
}
test(`${build}: workflow fallback refreshes the page after replay mutations`, async () => {
const agent = setup(Agent), tab = nextTab++;
await agent._claimRunEntry(tab, 'workflow');
await agent._beginPageFeedbackRun(tab, 'workflow');
const run = agent._pageFeedbackRuns.get(tab);
run.latestObservation = 'stale page tree from before replay';
let reads = 0;
agent.executeTool = async (_tab, name, args, _onUpdate, executionContext) => {
assert.equal(name, 'get_accessibility_tree');
assert.deepEqual(args, { filter: 'visible', maxChars: 12000 });
assert.equal(executionContext.pageFeedbackRead, true);
reads++;
return { success: true, pageContent: 'Fresh page tree at workflow fallback' };
};
try {
const prompt = await agent._workflowFeedbackFallbackPrompt(tab, 'Continue from the failed step.', () => {});
assert.equal(reads, 1, 'fallback should capture the page after replay has stopped');
assert.match(prompt, /Fresh page tree at workflow fallback/);
assert.doesNotMatch(prompt, /stale page tree from before replay/);
assert.match(run.latestObservation, /Fresh page tree at workflow fallback/);
} finally {
agent._finishPageFeedbackRun(tab);
agent._releaseRunEntry(tab);
}
});
test(`${build}: cloud feedback redacts navigation details in both secret modes`, async () => {
const { createCloudRunController } = await import(`../src/${build}/src/cloud-runs.js`);
for (const strictSecretMode of [false, true]) {
const agent = { isRunning: () => false, strictSecretMode, abort() {},
async processMessage(_tab, _task, update, _mode, _attachments, options) {
update('page_feedback', { id: 'navigation-id', source: 'user', kinds: ['navigation'], navigation: true,
before: 'https://user:[email protected]/?private=value', after: 'https://example.com/?secret=token',
page: 'Sensitive contents' });
options.onRunFinished('done'); return 'Finished';
} };
const controller = createCloudRunController({ chromeApi: { ...api,
tabs: { ...api.tabs, update: async () => {}, query: async () => [{ id: tab, url: 'https://example.com' }] } }, agent,
makeRunId: () => `cloud-feedback-${strictSecretMode}`, ensureOffscreen: async () => {} });
const tab = nextTab++;
const run = await controller.startRun({ task: 'Read this page', tabId: tab });
for (let i = 0; i < 100 && controller.runs.get(run.runId).status === 'running'; i++) await new Promise(r => setTimeout(r, 5));
const done = await controller.status({ runId: run.runId });
const note = done.updates.find(update => update.type === 'page_feedback');
assert.equal(note.data.navigation, true);
assert.equal(note.data.id, 'navigation-id');
assert.equal(/password|private=value|secret=token|Sensitive contents/.test(JSON.stringify(note)), false);
}
});
test(`${build}: scheduled feedback carries the owning job identity`, async () => {
const module = await import(`../src/${build}/src/agent/scheduler.js`);
const now = Date.UTC(2026, 0, 1, 12), iso = new Date(now).toISOString();
const harness = makeSchedulerHarness(module, { now, jobs: [{ id: 'monitor-job', kind: 'task', status: 'pending',
tabId: 77, mode: 'act', prompt: 'Read the page', title: 'Read', target: { type: 'current_tab', tabId: 77,
originalUrl: 'https://example.com/' }, schedule: { type: 'once' }, nextRunAt: iso, scheduledAt: iso, runCount: 0 }],
processMessage: async (_tab, _message, update, _mode, _attachments, options) => {
update('page_feedback', { id: 'scheduled-notice', navigation: true, source: 'user', kinds: ['navigation'] });
update('tool_result', { name: 'done', result: { done: true, success: true, outcome: 'success' } });
options.onRunFinished?.('done'); return 'Finished';
} });
await harness.manager.handleAlarm(harness.alarmName('monitor-job'));
for (let i = 0; i < 100 && !harness.updates.some(update => update.type === 'page_feedback'); i++) await new Promise(r => setTimeout(r, 5));
const note = harness.updates.find(update => update.type === 'page_feedback');
assert.equal(note.tabId, 77);
assert.equal(note.data.scheduledJobId, 'monitor-job');
assert.equal(note.data.id, 'scheduled-notice');
});
}
test('shared page monitoring modules stay identical between browser builds', () => {
for (const file of ['agent/page-feedback.js', 'content/page-monitor.js', 'content/page-monitor-shadow.js', 'ui/page-feedback-ui.js']) {
const read = build => fs.readFileSync(new URL(`../src/${build}/src/${file}`, import.meta.url), 'utf8');
assert.equal(read('chrome'), read('firefox'));
}
});
test('Firefox supplements empty-frame monitoring after document start', () => {
const manifest = JSON.parse(fs.readFileSync(new URL('../src/firefox/manifest.json', import.meta.url), 'utf8'));
const monitor = manifest.content_scripts.find(entry => entry.run_at === 'document_end' && entry.js.includes('src/content/page-monitor.js'));
assert.ok(monitor); assert.equal(monitor.all_frames, true); assert.equal(monitor.match_about_blank, true);
assert.deepEqual(monitor.js, ['src/content/page-monitor-recovery.js', 'src/content/page-monitor.js']);
const shadow = manifest.content_scripts.find(entry => entry.run_at === 'document_end' && entry.world === 'MAIN'
&& entry.js.includes('src/content/page-monitor-shadow.js'));
assert.ok(shadow); assert.equal(shadow.all_frames, true); assert.equal(shadow.match_about_blank, true);
});
test('both manifests signal shadow attachment from MAIN in all monitored frames', () => {
for (const build of ['chrome', 'firefox']) {
const manifest = JSON.parse(fs.readFileSync(new URL(`../src/${build}/manifest.json`, import.meta.url), 'utf8'));
const entry = manifest.content_scripts.find(item => item.js.includes('src/content/page-monitor-shadow.js'));
assert.equal(entry.world, 'MAIN');
assert.equal(entry.run_at, 'document_start');
assert.equal(entry.all_frames, true);
assert.equal(entry.match_about_blank, true);
}
});
test('monitor registrations include related-origin frames in both execution worlds', () => {
for (const build of ['chrome', 'firefox']) {
const manifest = JSON.parse(fs.readFileSync(new URL(`../src/${build}/manifest.json`, import.meta.url), 'utf8'));
const entries = manifest.content_scripts.filter(entry => entry.js.some(file => /\/page-monitor(?:-shadow)?\.js$/.test(file)));
assert.equal(entries.length, build === 'firefox' ? 4 : 2);
for (const entry of entries) assert.ok(entry.all_frames && entry.match_about_blank && entry.match_origin_as_fallback);
}
});
test('Chrome WebMCP invocation rechecks feedback immediately before CDP dispatch', async () => {
const { Agent } = await import('../src/chrome/src/agent/agent.js');
const agent = setup(Agent), tab = nextTab++;
agent.executeTool = Agent.prototype.executeTool;
const originalGetContext = cdpClient.getWebMCPToolContext;
const originalEnable = cdpClient.enableWebMCP;
const originalFrameUrls = cdpClient._webMCPFrameUrls;
const originalSendCommand = cdpClient.sendCommand;
const previousSession = cdpClient.webMcpSessions.get(tab);
const calls = [];
const tool = { toolId: 'wmcp_guarded', name: 'submit', frameId: 'main-frame', sessionId: 'session-main', annotations: {} };
const state = { closed: false, toolsById: new Map([[tool.toolId, tool]]), pendingInvocations: new Map(), completedResponses: new Map() };
let contextReads = 0;
try {
await agent._claimRunEntry(tab, 'interactive');
agent.setWebMCPEnabled(true);
agent.conversationModes.set(tab, 'act');
await agent._beginPageFeedbackRun(tab, 'chat');
cdpClient.webMcpSessions.set(tab, state);
cdpClient.enableWebMCP = async () => state;
cdpClient._webMCPFrameUrls = async () => new Map([[tool.frameId, 'https://example.com/checkout']]);
cdpClient.getWebMCPToolContext = async () => {
contextReads++;
if (contextReads === 2) {
// Arrives after agent-side context/permission preparation but before the
// CDP client's own asynchronous validation finishes.
agent._queuePageFeedback(tab, { kind: 'input', source: 'user', frameId: 0, revision: 1, target: 'input#address' });
}
return { toolId: tool.toolId, frameId: tool.frameId, targetUrl: 'https://example.com/checkout', declaredReadOnly: false };
};
cdpClient.sendCommand = async (_tabId, method) => {
calls.push(method);
if (method === 'WebMCP.invokeTool') return { invocationId: 'should-not-dispatch' };
return {};
};
const prepared = await agent._prepareWebMCPToolCall(tab, 'execute_webmcp_tool', { tool_id: tool.toolId, input: {} });
const result = await agent.executeTool(tab, 'execute_webmcp_tool', prepared.args);
assert.equal(result.pageFeedbackPending, true);
assert.equal(result.noDispatch, true);
assert.equal(calls.includes('WebMCP.invokeTool'), false, 'stale WebMCP invocation must be stopped at the CDP boundary');
} finally {
agent._finishPageFeedbackRun(tab);
agent._releaseRunEntry(tab);
cdpClient.getWebMCPToolContext = originalGetContext;
cdpClient.enableWebMCP = originalEnable;
cdpClient._webMCPFrameUrls = originalFrameUrls;
cdpClient.sendCommand = originalSendCommand;
if (previousSession) cdpClient.webMcpSessions.set(tab, previousSession);
else cdpClient.webMcpSessions.delete(tab);
}
});
for (const path of ['local', 'memory']) {
for (const intervention of ['preparation', 'handshake', 'none']) {
test(`Chrome ${path} upload honors feedback arriving during ${intervention}`, async () => {
const { Agent } = await import('../src/chrome/src/agent/agent.js');
const { CDPClient } = await import('../src/chrome/src/cdp/cdp-client.js');
const agent = setup(Agent), tab = nextTab++, mutations = [], notices = [];
await agent._claimRunEntry(tab, 'interactive');
const originalMessage = api.tabs.sendMessage;
try {
const binding = bind(agent, tab), child = bind(agent, tab, 2, 'upload-doc', 'upload-token');
const client = new CDPClient(), monitorGuards = [], runtimeCalls = [];
client._pageAgentObjectTarget = async () => {
if (intervention === 'preparation') binding.send({ kind: 'click' });
return { documentToken: child.state.documentToken, documentRevision: 0, nativeTarget: 'upload-target' };
};
api.tabs.sendMessage = async (_tab, message, options) => {
if (message.action === 'page_monitor_prepare') return { ready: true };
if (message.action === 'page_monitor_dispatch') {
assert.equal(options.frameId, 2);
notices.push(message);
if (intervention === 'handshake') binding.send({ kind: 'click' });
const guard = { runToken: message.params.runToken, documentToken: child.state.documentToken,
revision: 0, operationId: message.params.operationId };
monitorGuards.push(guard);
return { ready: true, guard };
}
return {};
};
client.sendCommand = async (_tab, method, params) => {
const assignment = method === 'Runtime.callFunctionOn' && params.functionDeclaration.includes('this.files = transfer.files');
if (method === 'DOM.setFileInputFiles' || assignment) mutations.push(method);
if (assignment) runtimeCalls.push(params);
return { result: { value: { success: true, dispatched: true, connected: true, fileInput: true, disabled: false, accept: '' } } };
};
let started = false;
const options = { beforeDispatch: () => { started = true; } };
const upload = path === 'local' ? client.setFileInputFiles(tab, 'file-input', ['fixture.txt'], options)
: client.setFileInputData(tab, 'file-input', { base64: 'eA==', filename: 'fixture.txt' }, options);
if (intervention === 'none') {
assert.equal((await upload).success, true);
assert.equal(started, true);
assert.equal(mutations.length, 1);
assert.equal(notices.length, 1);
if (path === 'memory') {
const call = runtimeCalls[0];
assert.deepEqual(call.arguments.at(-1), { value: monitorGuards[0] });
assert.ok(call.functionDeclaration.indexOf("beforePageAgentDomAction(pageGuard, 'input', this)")
< call.functionDeclaration.indexOf('this.files = transfer.files'));
}
} else {
await assert.rejects(upload, { code: 'page_feedback_pending' });
assert.equal(started, false);
assert.equal(mutations.length, 0);
}
} finally { api.tabs.sendMessage = originalMessage; agent._releaseRunEntry(tab); }
});
}
}
// Exercise the production feedback method and actual recorder note boundary.
// Only extension transport and the durable append sink are simulated.
async function feedbackDecisionTraceMethod(build, records) {
const policy = await import(`../src/${build}/src/agent/page-feedback-policy.js`);
const recovery = await import(`../src/${build}/src/agent/page-feedback-recovery.js`);
const media = await import(`../src/${build}/src/agent/media-download-binding.js`);
const answerScope = await import(`../src/${build}/src/agent/ask-response-scope.js`);
const completion = await import(`../src/${build}/src/agent/completion-verifier.js`);
const { projectTraceEventData } = await import(`../src/${build}/src/trace/privacy.js`);
const feedbackPath = new URL(`../src/${build}/src/agent/page-feedback.js`, import.meta.url);
const source = fs.readFileSync(feedbackPath, 'utf8');
const recorder = fs.readFileSync(new URL(`../src/${build}/src/trace/recorder.js`, import.meta.url), 'utf8');
const noteStart = recorder.indexOf('export function recordNote(');
const noteEnd = recorder.indexOf('\nasync function _retryCount(', noteStart);
assert.ok(noteStart >= 0 && noteEnd > noteStart);
const recordNote = vm.runInNewContext(recorder.slice(noteStart, noteEnd).replace('export ', '') + '\nrecordNote;', {
_appendEvent: (runId, kind, data) => records.push(structuredClone({ runId, kind, data, metadata: projectTraceEventData(kind, data) })),
});
const imports = source.match(/^import [^\n]+;\r?\n/gm) || [];
assert.equal(imports.length, 6);
const context = vm.createContext({ ...policy, ...recovery, ...media, ...answerScope, ...completion, trace: { recordNote },
chrome: api, browser: api, setTimeout, clearTimeout, crypto: globalThis.crypto });
return vm.runInContext(source.replace(/^import [^\n]+;\r?\n/gm, '').replace(/^export /gm, '')
+ '\nObject.assign(pageFeedbackMethods._applyPendingPageFeedback, { diagnosticSummary: typeof feedbackEventSummary === \"function\" ? feedbackEventSummary : null });', context);
}
for (const build of ['chrome', 'firefox']) {
const { Agent } = await import(`../src/${build}/src/agent/agent.js`);
test(`${build}: feedback decision trace distinguishes page activity, user input and binding changes`, async () => {
const records = [], apply = await feedbackDecisionTraceMethod(build, records);
for (const change of ['passive', 'page_focus', 'page_input', 'user_input', 'style', 'child', 'document', 'steering', 'run']) {
const agent = setup(Agent), tab = nextTab++, messages = [{ role: 'system', content: '' },
{ role: 'user', content: 'Publish the current draft' }];
agent._applyPendingPageFeedback = apply;
const previousNavigation = api.webNavigation;
await agent._claimRunEntry(tab, 'interactive');
try {
api.webNavigation = { getAllFrames: async () => [{ frameId: 0, documentId: 'document-1' }] };
const binding = bind(agent, tab), child = bind(agent, tab, 2, 'child-private-document', 'child-private-token');
await agent._capturePageFeedbackModelState(tab);
agent.currentRunId.set(tab, 'diagnostic-private-run-id');
const originalStateCurrent = agent._pageFeedbackStateCurrent; let stateChecks = 0;
agent._pageFeedbackStateCurrent = (...args) => { stateChecks++; return originalStateCurrent.apply(agent, args); };
if (change === 'document') api.webNavigation = { getAllFrames: async () => [{ frameId: 0, documentId: 'replacement-private-document' }] };
if (change === 'steering') agent._steeringRuns.set(tab, { messages: [], revision: 0, authorizedRevision: 0, acceptedIds: new Set(['private-steering-id']) });
if (change === 'run') agent.executeTool = async () => {
const run = agent._pageFeedbackRuns.get(tab);
agent._pageFeedbackRuns.set(tab, { ...run });
return { success: true, pageContent: 'Current view' };
};
const event = { kind: change === 'page_focus' ? 'activity' : ['page_input', 'user_input'].includes(change) ? 'input' : 'dom',
source: change === 'user_input' ? 'user' : 'page',
target: change === 'style' ? 'style#PRIVATE_STYLE_TARGET' : 'PRIVATE_TARGET_WITH_SECRET' };
assert.equal((change === 'child' ? child : binding).send(event).accepted, true);
const superseded = await agent._applyPendingPageFeedback(tab, messages, () => {}, {
responseToolCalls: [{ function: { name: 'done', arguments: JSON.stringify({ summary: 'Published', outcome: 'success' }) } }],
});
const note = records.at(-1);
assert.equal(note.kind, 'note'); assert.equal(note.data.note, 'page_feedback_decision'); assert.equal(note.data.step, 0);
const details = note.data.extra;
assert.deepEqual(note.metadata.extra.context, details.context, 'Safe causal details survive the actual metadata-only trace projection');
// An Act completion survives passive and automatic page activity.
const retained = ['passive', 'page_focus', 'page_input', 'child'].includes(change);
assert.equal(superseded, !retained, `Diagnostic fields must not change existing retention decisions: ${change}`);
assert.equal(details.reason, change === 'passive' ? 'passive_dom'
: ['page_focus', 'page_input', 'child'].includes(change) ? 'automatic_page' : 'intervention_or_document');
assert.equal(details.disposition, retained ? 'retained' : 'superseded');
assert.equal(stateChecks, ['document', 'run'].includes(change) ? 0 : 1, 'Preserve the original state-check short circuit and call count');
assert.deepEqual(details.context.bindingAtRefresh, { documentMatches: change !== 'document', currentRun: change !== 'run',
stateCurrent: ['document', 'run'].includes(change) ? null : change !== 'steering',
sameDocument: !['document', 'run', 'steering'].includes(change) });
assert.deepEqual(details.context.feedback.observed, { count: 1, omitted: 0, events: [{ kind: event.kind, source: event.source,
frameId: change === 'child' ? 2 : 0, baseStyleLink: change === 'style' }] });
assert.deepEqual(details.context.feedback.pendingAtRefresh, { count: 0, omitted: 0, events: [] });
assert.deepEqual(details.context.feedback.pendingAtDecision, { count: 0, omitted: 0, events: [] });
assert.doesNotMatch(JSON.stringify(details), /PRIVATE|private|https?:|document-1|content-1/);
} finally { api.webNavigation = previousNavigation; agent._releaseRunEntry(tab); }
}
});
test(`${build}: feedback decision trace bounds all queues and retains pending input attribution`, async () => {
const records = [], agent = setup(Agent), tab = nextTab++, messages = [{ role: 'system', content: '' }, { role: 'user', content: 'Publish' }];
agent._applyPendingPageFeedback = await feedbackDecisionTraceMethod(build, records);
await agent._claimRunEntry(tab, 'interactive');
try {
const binding = bind(agent, tab);
await agent._capturePageFeedbackModelState(tab);
agent.currentRunId.set(tab, 'diagnostic-private-run-id');
for (let index = 0; index < 32; index++) assert.equal(binding.send({ kind: 'dom', source: 'page',
target: index === 0 ? 'link#PRIVATE_STYLE_TARGET' : `PRIVATE_URL_https://secret.invalid/${index}` }).accepted, true);
agent.executeTool = async () => {
for (let index = 0; index < 12; index++) assert.equal(binding.send({ kind: 'input', source: 'user',
target: `PRIVATE_INPUT_TOKEN_${index}` }).accepted, true);
return { success: true, pageContent: 'Current view' };
};
assert.equal(await agent._applyPendingPageFeedback(tab, messages, () => {}, {
responseToolCalls: [{ function: { name: 'done', arguments: '{"summary":"Published","outcome":"success"}' } }],
}), true);
const details = records.at(-1).data.extra;
assert.deepEqual(records.at(-1).metadata.extra.context, details.context, 'Safe bounded queues survive exhausted content budgets');
assert.equal(details.reason, 'intervention_or_document');
assert.equal(details.context.feedback.observed.count, 32); assert.equal(details.context.feedback.observed.omitted, 24);
assert.equal(details.context.feedback.observed.events[0].baseStyleLink, true);
for (const name of ['pendingAtRefresh', 'pendingAtDecision']) {
assert.equal(details.context.feedback[name].count, 12); assert.equal(details.context.feedback[name].omitted, 4);
assert.ok(details.context.feedback[name].events.every(event => event.kind === 'input' && event.source === 'user' && event.frameId === 0));
}
for (const queue of Object.values(details.context.feedback)) {
assert.equal(queue.events.length, 8);
for (const event of queue.events) assert.deepEqual(Object.keys(event), ['kind', 'source', 'frameId', 'baseStyleLink']);
}
assert.ok(JSON.stringify(details.context.feedback).length < 2500);
const defensive = agent._applyPendingPageFeedback.diagnosticSummary([null, { kind: 'PRIVATE_KIND', source: 'PRIVATE_SOURCE', frameId: -1,
target: { toString() { throw new Error('Diagnostic must not coerce page data'); } } },
{ kind: 'dom', source: 'page', frameId: 0, target: 'style#' + 'PRIVATE'.repeat(100000) }]);
assert.deepEqual(JSON.parse(JSON.stringify(defensive)).events, [
{ kind: 'other', source: 'unknown', frameId: null, baseStyleLink: false },
{ kind: 'other', source: 'unknown', frameId: null, baseStyleLink: false },
{ kind: 'dom', source: 'page', frameId: 0, baseStyleLink: true },
]);
assert.doesNotMatch(JSON.stringify(details), /PRIVATE|private|https?:|document-1|content-1/);
} finally { agent._releaseRunEntry(tab); }
});
}
// A current read inspects the fresh page; it does not act on the former focus.
// Exercise the normal MAIN barrier, batch and real verify_form implementation.
for (const build of ['chrome', 'firefox']) {
const { Agent } = await import(`../src/${build}/src/agent/agent.js`);
test(`${build}: current read-only form verification survives top-frame page focus`, async () => {
const tab = nextTab++, entered = deferred(), release = deferred(), updates = [];
let requests = 0, nativeReads = 0, formRead = null;
// A model reading the partial result is not a decision of this run.
const agent = setup(Agent, { supportsTools: true, chat: withoutFixedChoiceAnswers(async () => {
requests++;
if (requests === 1) {
entered.resolve(); await release.promise;
return { content: null, toolCalls: [{ id: 'current-form-read', function: { name: 'verify_form', arguments: '{"selector":"#current-form","urlFilter":""}' } }] };
}
return { content: null, toolCalls: [{ id: 'honest-partial', function: { name: 'done', arguments: '{"summary":"The current form was inspected; no save is claimed.","outcome":"partial"}' } }] };
}) });
allowBatchPreparation(agent);
agent.planBeforeAct = false; agent.maxSteps = 3; agent.autoScreenshot = 'off';
agent._maybeRunPlannerGate = async () => ({ proceed: true, requestKind: 'execute', requiresStateChange: true });
agent._maybeReinjectAdapter = async () => {};
agent._ensureProgressSessionForCurrentTask = async () => ({ mode: 'inactive' });
agent._currentTaskLedgerRows = () => [];
const execute = Agent.prototype.executeTool;
agent.executeTool = async function (id, name, ...args) {
if (name === 'get_accessibility_tree') return { success: true, pageContent: 'form "Current form" [ref_1]' };
assert.ok(['verify_form', 'done'].includes(name));
const result = await execute.call(this, id, name, ...args);
if (name === 'verify_form') formRead = result;
return result;
};
const original = { attach: cdpClient.attach, evaluate: cdpClient.evaluate,
sendCommand: cdpClient.sendCommand, executeScript: api.tabs.executeScript,
navigation: api.webNavigation };
const form = { found: true, action: '', method: 'post', fieldCount: 1,
fields: [{ name: 'title', id: 'title', selector: '#title', type: 'text', value: 'Current value', label: 'Title' }] };
cdpClient.attach = async () => {};
cdpClient.evaluate = async (_id, code) => {
assert.match(code, /#current-form/); nativeReads++;
return { result: { value: structuredClone(form) } };
};
cdpClient.sendCommand = async () => { throw new Error('No screenshot transport in this offline fixture'); };
api.tabs.executeScript = async (_id, { code }) => {
assert.match(code, /#current-form/); nativeReads++;
return [structuredClone(form)];
};
api.webNavigation = { getAllFrames: async () => [{ frameId: 0, documentId: 'document-1' }] };
const running = agent.processMessage(tab, 'Inspect the current form without submitting it',
(type, data) => updates.push({ type, data }), 'act');
try {
await entered.promise;
assert.equal(bind(agent, tab).send({ kind: 'activity', source: 'page', target: 'button#page-autofocus' }).accepted, true);
release.resolve();
await running;
assert.equal(nativeReads, 1, 'The proposed current read must execute once through the real verify_form handler');
assert.equal(requests, 2, 'Harmless page focus must not discard the read and require another model decision');
const messages = agent.conversations.get(tab) || [];
const results = messages.filter(message => message.role === 'tool' && message.tool_call_id === 'current-form-read');
assert.equal(results.length, 1); assert.match(results[0].content, /Current value/);
assert.equal(formRead.success, true); assert.equal(formRead.scope, 'top');
assert.equal(formRead.fields[0].value, 'Current value');
assert.equal(formRead.submitted, undefined, 'Inspection does not grant submission evidence');
assert.ok(updates.some(update => update.type === 'page_feedback'));
} finally {
release.resolve(); cdpClient.attach = original.attach; cdpClient.evaluate = original.evaluate;
cdpClient.sendCommand = original.sendCommand;
if (original.executeScript === undefined) delete api.tabs.executeScript; else api.tabs.executeScript = original.executeScript;
api.webNavigation = original.navigation;
if (agent._pageFeedbackRuns.has(tab)) agent._finishPageFeedbackRun(tab);
agent._releaseRunEntry(tab);
}
});
test(`${build}: page-focus read retention preserves human, document and action fences`, async () => {
const apply = await feedbackDecisionTraceMethod(build, []);
for (const change of ['focus', 'pending_focus', 'user_activity', 'user_input', 'page_input', 'selection',
'navigation', 'child', 'frame_focus', 'style', 'activity_style', 'document', 'run', 'steering', 'pending_user',
'click', 'type', 'keys', 'upload', 'chat_preparation', 'calculate', 'success_done', 'partial_done', 'failed_done', 'mixed', 'malformed']) {
const agent = setup(Agent), tab = nextTab++, messages = [{ role: 'system', content: '' }, { role: 'user', content: 'Inspect the current form' }];
agent._applyPendingPageFeedback = apply;
const navigation = api.webNavigation;
await agent._claimRunEntry(tab, 'interactive');
try {
api.webNavigation = { getAllFrames: async () => [{ frameId: 0, documentId: 'document-1' }] };
const binding = bind(agent, tab), child = bind(agent, tab, 2, 'child-document', 'child-token');
await agent._capturePageFeedbackModelState(tab);
if (change === 'document') api.webNavigation = { getAllFrames: async () => [{ frameId: 0, documentId: 'replacement-document' }] };
if (change === 'steering') agent._steeringRuns.set(tab, { messages: [], revision: 0, authorizedRevision: 0, acceptedIds: new Set(['new-task-revision']) });
let refreshed = false;
agent.executeTool = async (_id, name) => {
assert.equal(name, 'get_accessibility_tree');
if (!refreshed && change.startsWith('pending_')) binding.send({ kind: change === 'pending_focus' ? 'activity' : 'input',
source: change === 'pending_focus' ? 'page' : 'user', target: 'input#current-field' });
if (change === 'run') agent._pageFeedbackRuns.set(tab, { ...agent._pageFeedbackRuns.get(tab) });
refreshed = true; return { success: true, pageContent: 'Current form' };
};
const event = { kind: ['page_input', 'user_input'].includes(change) ? 'input'
: ['selection', 'navigation'].includes(change) ? change : change === 'style' ? 'dom' : 'activity',
source: ['user_activity', 'user_input'].includes(change) ? 'user' : 'page',
target: change === 'frame_focus' ? 'iframe#child' : ['style', 'activity_style'].includes(change) ? 'style#changed' : 'input#page-autofocus' };
if (change === 'navigation') agent.observePageNavigation({ tabId: tab, frameId: 0,
url: 'https://example.com/changed', transitionType: 'link' }, 'history');
else assert.equal((change === 'child' ? child : binding).send(event).accepted, true, change);
let name = ({ click: 'click_ax', type: 'type_text', keys: 'press_keys', upload: 'upload_file',
chat_preparation: 'chat_observe', calculate: 'calculate', success_done: 'done', partial_done: 'done', failed_done: 'done' })[change] || 'verify_form';
let args = name === 'done' ? { summary: 'A terminal candidate', outcome: change.split('_')[0] }
: name === 'verify_form' ? { selector: '', urlFilter: '' } : { ref_id: 'ref_1', selector: '#current-field', text: 'new value' };
const calls = [{ function: { name, arguments: change === 'malformed' ? '{' : JSON.stringify(args) } }];
if (change === 'mixed') calls.push({ function: { name: 'type_text', arguments: '{"text":"new value"}' } });
const superseded = await agent._applyPendingPageFeedback(tab, messages, () => {}, { responseToolCalls: calls });
// Page input, child-frame focus and iframe focus are automatic; pure readers,
// independent tools and Act completions stay current while action fences remain.
assert.equal(superseded, !['focus', 'pending_focus', 'page_input', 'child', 'frame_focus', 'calculate',
'success_done', 'partial_done', 'failed_done'].includes(change), change);
} finally { api.webNavigation = navigation; agent._releaseRunEntry(tab); }
}
});
}
// A history update at the identical full URL is state refresh, not a displayed navigation.
for (const build of ['chrome', 'firefox']) {
const { Agent } = await import(`../src/${build}/src/agent/agent.js`);
const { renderPageFeedbackNote } = await import(`../src/${build}/src/ui/page-feedback-ui.js`);
const withNoticeDocument = action => {
const previous = globalThis.document;
globalThis.document = { createElement: () => ({ dataset: {}, setAttribute(name, value) { this[name] = value; } }) };
try { return action(); } finally { globalThis.document = previous; }
};
const assistant = () => ({ children: [], querySelectorAll() { return this.children; },
appendChild(node) { this.children.push(node); } });
const translate = (key, values) => {
assert.equal(key, 'sp.monitor.navigation');
return values.before + ' -> ' + values.after;
};
test(`${build}: equal history URL suppresses only its misleading navigation note`, () => withNoticeDocument(() => {
const url = 'https://example.com/thread?current=1#same';
for (const [navigationType, before, after, visible] of [
['history', url, url, false],
['committed', url, url, true],
['fragment', url, url, true],
[undefined, url, url, true],
['history', url, url.replace('current=1', 'current=2'), true],
['history', url, url.replace('#same', '#other'), true],
['history', '', '', true],
['history', 'https://example.com/' + 'a'.repeat(2000), 'https://example.com/' + 'a'.repeat(2000), true],
]) {
const element = assistant();
assert.equal(renderPageFeedbackNote(element, { id: 'notice', navigation: true,
navigationType, before, after }, translate), visible);
assert.equal(element.children.length, Number(visible));
if (visible) assert.equal(element.children[0].role, 'status');
}
const changed = assistant();
const data = { id: 'changed', navigation: true, navigationType: 'history', before: url, after: url + '2' };
assert.equal(renderPageFeedbackNote(changed, data, translate), true);
assert.equal(changed.children[0].textContent, 'https://example.com/thread -> https://example.com/thread',
'Full route comparison must precede the existing privacy display redaction.');
assert.equal(renderPageFeedbackNote(changed, data, translate), false, 'Existing notice dedup remains intact.');
}));
test(`${build}: equal history metadata reaches UI while unsafe response is still superseded`, async () => {
const agent = setup(Agent), tab = nextTab++, updates = [], messages = [
{ role: 'system', content: '' }, { role: 'user', content: 'Send exactly the requested message to the current recipient' }];
let reads = 0;
agent.executeTool = async (_tab, name) => {
assert.equal(name, 'get_accessibility_tree', 'Only the existing refresh reader may execute.');
reads++; return { success: true, pageContent: 'Current recipient and empty composer' };
};
await agent._claimRunEntry(tab, 'interactive');
try {
bind(agent, tab);
const run = agent._pageFeedbackRuns.get(tab), revision = run.revision;
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/new',
transitionType: 'link' }, 'history');
assert.equal(run.events.size, 1);
assert.ok(run.revision > revision);
assert.equal(await agent._applyPendingPageFeedback(tab, messages, (type, data) => updates.push({ type, data }), {
responseToolCalls: [{ function: { name: 'chat_send', arguments: '{"text":"requested message"}' } }],
}), true, 'Equal history still refreshes and supersedes an unsafe response.');
assert.equal(reads, 1);
const note = updates.find(update => update.data.navigation).data;
assert.equal(note.navigationType, 'history');
assert.equal(note.before, note.after);
withNoticeDocument(() => assert.equal(renderPageFeedbackNote(assistant(), note, translate), false));
assert.equal(agent._activeTaskBinding(messages).text, 'Send exactly the requested message to the current recipient');
assert.equal(run.events.size, 0);
run.onUpdate = (type, data) => updates.push({ type, data });
agent.observePageNavigation({ tabId: tab, frameId: 0, url: 'https://example.com/new',
transitionType: 'link' }, 'history');
agent._finishPageFeedbackRun(tab);
const terminalNote = updates.at(-1).data;
assert.equal(terminalNote.navigationType, 'history', 'The final notice transport keeps the same type.');
withNoticeDocument(() => assert.equal(renderPageFeedbackNote(assistant(), terminalNote, translate), false));
} finally { agent._releaseRunEntry(tab); }
});
}