Skip to content

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

fix(agent): live scope before mutation debt, first-token bootstrap

Emre Sokullu87e53969831f
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index e22fe49b7..abb375622 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -20607,7 +20607,25 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (liveScope
&& liveScope.documentToken
&& liveScope.documentToken !== String(cachedScope.documentToken || '')) {
+ const bootstrappingFirstToken = !cachedScope.documentToken;
this._rememberAxScope(tabId, liveScope.documentToken, liveScope.pageUrl || cachedScope.pageUrl || '');
+ // First-token bootstrap: debts recorded before any document was
+ // observed carry no token. A tokenless debt whose recorded URL differs
+ // from the live URL provably predates this document (full navigation),
+ // so drop it instead of blocking the unrelated destination. Same-URL
+ // or URL-less debts stay blocked fail-closed β€” a same-document route
+ // change keeps its readback-only guard.
+ if (bootstrappingFirstToken) {
+ for (const [key, candidate] of debts) {
+ if (!candidate.documentToken
+ && candidate.pageUrl
+ && liveScope.pageUrl
+ && this._normalizeUrl(candidate.pageUrl) !== this._normalizeUrl(liveScope.pageUrl)) {
+ debts.delete(key);
+ }
+ }
+ if (debts.size === 0) this._uncertainTextMutations.delete(tabId);
+ }
if (!(this._uncertainTextMutations.get(tabId) instanceof Map)
|| this._uncertainTextMutations.get(tabId).size === 0) {
return null;
@@ -20633,7 +20651,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (!['set_field', 'type_ax', 'type_text'].includes(name) || !result || typeof result !== 'object') {
return result;
}
- const target = this._textMutationTarget(tabId, name, args);
+ let target = this._textMutationTarget(tabId, name, args);
const replacesValue = this._textMutationReplacesValue(name, args);
const text = typeof args.text === 'string' ? args.text : '';
const expectedSha256 = await this._sha256Text(text);
@@ -20650,6 +20668,28 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
|| (result.success === false && result.verified === false && result.noDispatch !== true)
|| (result.recoveryRequired === 'fresh_tree' && result.noDispatch !== true);
if (uncertain) {
+ // Navigation-first ordering: a full navigation with no AX read leaves
+ // the cached scope on the old document, so a debt recorded now would
+ // carry a stale token that the next append's live check deletes as
+ // old-document debt β€” dispatching a possible duplicate of landed text.
+ // Refresh to the live scope before recording (adopting clears
+ // old-document debts/proofs through the document-change path when both
+ // tokens exist), then re-derive the target below.
+ try {
+ const liveScope = await this._liveTextMutationScope(tabId, name, args);
+ if (liveScope && (liveScope.documentToken || liveScope.pageUrl)) {
+ const cachedScope = this._lastAxScopes.get(tabId) || {};
+ if (String(liveScope.documentToken || '') !== String(cachedScope.documentToken || '')
+ || this._normalizeUrl(liveScope.pageUrl || '') !== this._normalizeUrl(cachedScope.pageUrl || '')) {
+ this._rememberAxScope(
+ tabId,
+ liveScope.documentToken || cachedScope.documentToken || '',
+ liveScope.pageUrl || cachedScope.pageUrl || '',
+ );
+ target = this._textMutationTarget(tabId, name, args);
+ }
+ }
+ } catch { /* an unreachable page keeps the cached scope below */ }
const verifiedReplacements = this._verifiedTextReplacements.get(tabId);
if (verifiedReplacements instanceof Map) {
if (target.ambiguous) verifiedReplacements.clear();
@@ -20667,8 +20707,17 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
debts = new Map();
this._uncertainTextMutations.set(tabId, debts);
}
+ // Bootstrap URL: when no scope was ever observed (no token and no URL
+ // even after the live refresh above), keep a best-effort live URL on
+ // the debt so the block-time first-token bootstrap can tell a later
+ // full navigation apart from the same page. Empty when unreachable.
+ let debtPageUrl = target.pageUrl;
+ if (!target.documentToken && !debtPageUrl) {
+ try { debtPageUrl = String(await this._currentUrl(tabId) || ''); } catch { debtPageUrl = ''; }
+ }
debts.set(target.key, {
...target,
+ pageUrl: debtPageUrl,
tool: name,
replacesValue,
expectedLength: text.length,
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 9500f8dcd..df3a162b0 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -18183,7 +18183,25 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (liveScope
&& liveScope.documentToken
&& liveScope.documentToken !== String(cachedScope.documentToken || '')) {
+ const bootstrappingFirstToken = !cachedScope.documentToken;
this._rememberAxScope(tabId, liveScope.documentToken, liveScope.pageUrl || cachedScope.pageUrl || '');
+ // First-token bootstrap: debts recorded before any document was
+ // observed carry no token. A tokenless debt whose recorded URL differs
+ // from the live URL provably predates this document (full navigation),
+ // so drop it instead of blocking the unrelated destination. Same-URL
+ // or URL-less debts stay blocked fail-closed β€” a same-document route
+ // change keeps its readback-only guard.
+ if (bootstrappingFirstToken) {
+ for (const [key, candidate] of debts) {
+ if (!candidate.documentToken
+ && candidate.pageUrl
+ && liveScope.pageUrl
+ && this._normalizeUrl(candidate.pageUrl) !== this._normalizeUrl(liveScope.pageUrl)) {
+ debts.delete(key);
+ }
+ }
+ if (debts.size === 0) this._uncertainTextMutations.delete(tabId);
+ }
if (!(this._uncertainTextMutations.get(tabId) instanceof Map)
|| this._uncertainTextMutations.get(tabId).size === 0) {
return null;
@@ -18209,7 +18227,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (!['set_field', 'type_ax', 'type_text'].includes(name) || !result || typeof result !== 'object') {
return result;
}
- const target = this._textMutationTarget(tabId, name, args);
+ let target = this._textMutationTarget(tabId, name, args);
const replacesValue = this._textMutationReplacesValue(name, args);
const text = typeof args.text === 'string' ? args.text : '';
const expectedSha256 = await this._sha256Text(text);
@@ -18226,6 +18244,28 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
|| (result.success === false && result.verified === false && result.noDispatch !== true)
|| (result.recoveryRequired === 'fresh_tree' && result.noDispatch !== true);
if (uncertain) {
+ // Navigation-first ordering: a full navigation with no AX read leaves
+ // the cached scope on the old document, so a debt recorded now would
+ // carry a stale token that the next append's live check deletes as
+ // old-document debt β€” dispatching a possible duplicate of landed text.
+ // Refresh to the live scope before recording (adopting clears
+ // old-document debts/proofs through the document-change path when both
+ // tokens exist), then re-derive the target below.
+ try {
+ const liveScope = await this._liveTextMutationScope(tabId, name, args);
+ if (liveScope && (liveScope.documentToken || liveScope.pageUrl)) {
+ const cachedScope = this._lastAxScopes.get(tabId) || {};
+ if (String(liveScope.documentToken || '') !== String(cachedScope.documentToken || '')
+ || this._normalizeUrl(liveScope.pageUrl || '') !== this._normalizeUrl(cachedScope.pageUrl || '')) {
+ this._rememberAxScope(
+ tabId,
+ liveScope.documentToken || cachedScope.documentToken || '',
+ liveScope.pageUrl || cachedScope.pageUrl || '',
+ );
+ target = this._textMutationTarget(tabId, name, args);
+ }
+ }
+ } catch { /* an unreachable page keeps the cached scope below */ }
const verifiedReplacements = this._verifiedTextReplacements.get(tabId);
if (verifiedReplacements instanceof Map) {
if (target.ambiguous) verifiedReplacements.clear();
@@ -18243,8 +18283,17 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
debts = new Map();
this._uncertainTextMutations.set(tabId, debts);
}
+ // Bootstrap URL: when no scope was ever observed (no token and no URL
+ // even after the live refresh above), keep a best-effort live URL on
+ // the debt so the block-time first-token bootstrap can tell a later
+ // full navigation apart from the same page. Empty when unreachable.
+ let debtPageUrl = target.pageUrl;
+ if (!target.documentToken && !debtPageUrl) {
+ try { debtPageUrl = String(await this._currentUrl(tabId) || ''); } catch { debtPageUrl = ''; }
+ }
debts.set(target.key, {
...target,
+ pageUrl: debtPageUrl,
tool: name,
replacesValue,
expectedLength: text.length,
diff --git a/test/run.js b/test/run.js
index fb2d44e85..b8f3b9151 100644
--- a/test/run.js
+++ b/test/run.js
@@ -74289,6 +74289,15 @@ test('an exact same-field readback resolves uncertain replacement without dispat
const tabs = {
async sendMessage(_tabId, message) {
readbacks += 1;
+ // The finalize path refreshes to the live scope before recording
+ // debt; here the live document is unchanged, so no adoption happens.
+ if (message.action === 'field_value_digest') {
+ return {
+ success: false,
+ documentToken: 'doc-readback',
+ refScopeUrl: 'https://github.com/example/repo/edit/main/docs/plan.md',
+ };
+ }
assert.equal(message.action, 'ax_verify_field_value');
assert.equal(message.params.expected, 'complete body');
return { success: true, verified: true };
@@ -74324,7 +74333,9 @@ test('an exact same-field readback resolves uncertain replacement without dispat
'complete body'.length,
);
}
- assert.equal(readbacks, 2);
+ // One live-scope digest at record time plus one AX readback at recovery,
+ // per build.
+ assert.equal(readbacks, 4);
} finally {
if (originalChrome === undefined) delete globalThis.chrome;
else globalThis.chrome = originalChrome;
@@ -75398,10 +75409,24 @@ test('focused field_value_digest and live scope cover selectorless writes', asyn
const originalChrome = globalThis.chrome;
const originalBrowser = globalThis.browser;
try {
+ // Phase-aware probe: the uncertain write lands while the live page is
+ // still the old document; the retry happens after a full navigation no
+ // AX read ever observed.
+ const liveDoc = { documentToken: 'doc-old', refScopeUrl: 'https://example.test/form' };
+ const tabs = {
+ async sendMessage(_tabId, message) {
+ assert.equal(message.action, 'field_value_digest');
+ return { success: false, documentToken: liveDoc.documentToken, refScopeUrl: liveDoc.refScopeUrl };
+ },
+ };
+ globalThis.chrome = { tabs };
+ globalThis.browser = { tabs };
for (const [label, AgentClass, tabId] of [
['chrome', AgentCh, 9484],
['firefox', AgentFx, 9485],
]) {
+ liveDoc.documentToken = 'doc-old';
+ liveDoc.refScopeUrl = 'https://example.test/form';
const agent = new AgentClass({});
agent._lastAxScopes.set(tabId, { documentToken: 'doc-old', pageUrl: 'https://example.test/form' });
await agent._finalizeTextMutationResult(
@@ -75410,7 +75435,35 @@ test('focused field_value_digest and live scope cover selectorless writes', asyn
);
assert.equal(agent._uncertainTextMutations.get(tabId)?.size, 1, `${label}: debt was not recorded`);
// Full navigation with no AX read: the cached scope still points at the
- // old document, but the live probe (empty params for focused) proves it.
+ // old document, but the live probe proves the move.
+ liveDoc.documentToken = 'doc-new';
+ liveDoc.refScopeUrl = 'https://other.test/page';
+ const live = await agent._liveTextMutationScope(tabId, 'type_text', { text: 'fresh' });
+ assert.equal(live?.documentToken, 'doc-new', `${label}: focused live scope returned no token`);
+ const allowed = await agent._uncertainTextMutationBlock(tabId, 'type_text', { text: 'fresh' });
+ assert.equal(allowed, null, `${label}: stale debt blocked a focused write on a new document`);
+ assert.equal(agent._uncertainTextMutations.has(tabId), false, `${label}: stale debt survived navigation`);
+ }
+ } finally {
+ if (originalChrome === undefined) delete globalThis.chrome;
+ else globalThis.chrome = originalChrome;
+ if (originalBrowser === undefined) delete globalThis.browser;
+ else globalThis.browser = originalBrowser;
+ }
+});
+
+test('uncertain write after navigation records live scoped debt', async () => {
+ const originalChrome = globalThis.chrome;
+ const originalBrowser = globalThis.browser;
+ try {
+ for (const [label, AgentClass, tabId] of [
+ ['chrome', AgentCh, 9490],
+ ['firefox', AgentFx, 9491],
+ ]) {
+ const agent = new AgentClass({});
+ // Cached scope predates a full navigation no AX read ever observed;
+ // the live page is already the new document.
+ agent._lastAxScopes.set(tabId, { documentToken: 'doc-old', pageUrl: 'https://example.test/form' });
const tabs = {
async sendMessage(_tabId, message) {
assert.equal(message.action, 'field_value_digest');
@@ -75419,11 +75472,92 @@ test('focused field_value_digest and live scope cover selectorless writes', asyn
};
globalThis.chrome = { tabs };
globalThis.browser = { tabs };
- const live = await agent._liveTextMutationScope(tabId, 'type_text', { text: 'fresh' });
- assert.equal(live?.documentToken, 'doc-new', `${label}: focused live scope returned no token`);
- const allowed = await agent._uncertainTextMutationBlock(tabId, 'type_text', { text: 'fresh' });
- assert.equal(allowed, null, `${label}: stale debt blocked a focused write on a new document`);
- assert.equal(agent._uncertainTextMutations.has(tabId), false, `${label}: stale debt survived navigation`);
+ await agent._finalizeTextMutationResult(
+ tabId, 'type_text', { selector: '#field', text: 'hello', clear: true },
+ { success: false, dispatched: true, verified: false },
+ );
+ const keys = [...(agent._uncertainTextMutations.get(tabId)?.keys() || [])];
+ assert.ok(keys.some(key => String(key).includes('doc-new')),
+ `${label}: navigation-first debt kept the stale document token (keys: ${keys})`);
+ assert.ok(!keys.some(key => String(key).includes('doc-old')),
+ `${label}: stale-token debt survived the live refresh`);
+ assert.equal(agent._lastAxScopes.get(tabId)?.documentToken, 'doc-new',
+ `${label}: live scope was not adopted before recording`);
+ // The very next append belongs to the current document, so the live
+ // check must keep the guard instead of clearing it as stale debt.
+ const blocked = await agent._uncertainTextMutationBlock(
+ tabId, 'type_text', { selector: '#field', text: 'hello appended' },
+ );
+ assert.equal(blocked?.repeatBlocked, true,
+ `${label}: append escaped the guard after a navigation-first debt`);
+ }
+ } finally {
+ if (originalChrome === undefined) delete globalThis.chrome;
+ else globalThis.chrome = originalChrome;
+ if (originalBrowser === undefined) delete globalThis.browser;
+ else globalThis.browser = originalBrowser;
+ }
+});
+
+test('first live token bootstraps tokenless debt by URL', async () => {
+ const originalChrome = globalThis.chrome;
+ const originalBrowser = globalThis.browser;
+ try {
+ const oldUrl = 'https://example.test/form';
+ const newUrl = 'https://other.test/page';
+ for (const [label, AgentClass, tabId, controlTabId] of [
+ ['chrome', AgentCh, 9492, 9494],
+ ['firefox', AgentFx, 9493, 9495],
+ ]) {
+ // No scope ever cached. Record-phase probe unreachable; the tabs URL
+ // channel still reports the old page for the debt bootstrap URL.
+ globalThis.chrome = { tabs: { async sendMessage() { return { success: false }; } } };
+ globalThis.browser = globalThis.chrome;
+ const agent = new AgentClass({});
+ agent._currentUrl = async () => oldUrl;
+ await agent._finalizeTextMutationResult(
+ tabId, 'type_text', { selector: '#field', text: 'draft', clear: true },
+ { success: false, dispatched: true, verified: false },
+ );
+ const debt = [...(agent._uncertainTextMutations.get(tabId)?.values() || [])][0];
+ assert.equal(debt?.documentToken, '', `${label}: debt unexpectedly carries a token`);
+ assert.equal(debt?.pageUrl, oldUrl, `${label}: tokenless debt kept no bootstrap URL`);
+ // Full navigation: the first live token plus a new URL drops the
+ // predated debt instead of blocking the unrelated destination.
+ const navTabs = { async sendMessage() {
+ return { success: false, documentToken: 'doc-first', refScopeUrl: newUrl };
+ } };
+ globalThis.chrome = { tabs: navTabs };
+ globalThis.browser = { tabs: navTabs };
+ const allowed = await agent._uncertainTextMutationBlock(
+ tabId, 'type_text', { selector: '#other', text: 'fresh' },
+ );
+ assert.equal(allowed, null, `${label}: predated tokenless debt blocked the new document`);
+ assert.equal(agent._uncertainTextMutations.has(tabId), false,
+ `${label}: predated tokenless debt survived the bootstrap`);
+ assert.equal(agent._lastAxScopes.get(tabId)?.documentToken, 'doc-first',
+ `${label}: first live token was not adopted`);
+ // Same-URL control: the first token on the SAME page keeps the guard.
+ globalThis.chrome = { tabs: { async sendMessage() { return { success: false }; } } };
+ globalThis.browser = globalThis.chrome;
+ const samePage = new AgentClass({});
+ samePage._currentUrl = async () => oldUrl;
+ await samePage._finalizeTextMutationResult(
+ controlTabId, 'type_text', { selector: '#field', text: 'draft', clear: true },
+ { success: false, dispatched: true, verified: false },
+ );
+ const sameTabs = { async sendMessage() {
+ return { success: false, documentToken: 'doc-first', refScopeUrl: oldUrl };
+ } };
+ globalThis.chrome = { tabs: sameTabs };
+ globalThis.browser = { tabs: sameTabs };
+ const blocked = await samePage._uncertainTextMutationBlock(
+ controlTabId, 'type_text', { selector: '#field', text: 'draft appended' },
+ );
+ assert.equal(blocked?.repeatBlocked, true,
+ `${label}: same-page tokenless debt was dropped by the bootstrap`);
+ assert.equal(samePage._uncertainTextMutations.get(controlTabId)?.size, 1,
+ `${label}: same-page tokenless debt was not retained`);
}
} finally {
if (originalChrome === undefined) delete globalThis.chrome;
@@ -75678,11 +75812,15 @@ test('navigation clears stale text-mutation debt via live document check', async
const originalChrome = globalThis.chrome;
const originalBrowser = globalThis.browser;
try {
+ // Phase-aware probe: the debt is recorded while the live page is still
+ // the old document; the retry runs after a full navigation no AX read
+ // ever observed.
+ const liveDoc = { documentToken: 'doc-old', refScopeUrl: 'https://example.test/form' };
const tabs = {
async sendMessage(_tabId, message) {
assert.equal(message.action, 'field_value_digest');
// Live page is a new document the cached scope never observed.
- return { success: false, documentToken: 'doc-new', refScopeUrl: 'https://other.test/page' };
+ return { success: false, documentToken: liveDoc.documentToken, refScopeUrl: liveDoc.refScopeUrl };
},
};
globalThis.chrome = { tabs };
@@ -75691,6 +75829,8 @@ test('navigation clears stale text-mutation debt via live document check', async
['chrome', AgentCh, 9474],
['firefox', AgentFx, 9475],
]) {
+ liveDoc.documentToken = 'doc-old';
+ liveDoc.refScopeUrl = 'https://example.test/form';
const agent = new AgentClass({});
agent._lastAxScopes.set(tabId, {
documentToken: 'doc-old',
@@ -75705,6 +75845,8 @@ test('navigation clears stale text-mutation debt via live document check', async
assert.equal(agent._uncertainTextMutations.get(tabId)?.size, 1, `${label}: debt was not recorded`);
// No AX read happened after the navigation: the cached scope still
// points at the old document, but the live check proves the move.
+ liveDoc.documentToken = 'doc-new';
+ liveDoc.refScopeUrl = 'https://other.test/page';
const allowed = await agent._uncertainTextMutationBlock(
tabId, 'type_text', { selector: '#other', text: 'fresh' },
);