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
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.jsindex 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 dif (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 dif (!['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 ddebts = 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.jsindex 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 dif (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 dif (!['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 ddebts = 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.jsindex 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 dispatconst 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', asynconst 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', asyncconst 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', asyncassert.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' },);