Skip to content

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

fix(agent): cross-locator distinctness, exact-scope file verification

Emre Sokullu5d0597be3752
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index fede759a7..37a3bd531 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -2474,9 +2474,13 @@ export class Agent extends LoopDetector {
const naiveAttempt = attempt.branch === expected.branch && attempt.path === expected.path;
// Alternate cuts are only meaningful against the observed changed
// file list: accepting one on content alone would bless bytes that
- // pre-exist at an untouched path. The naive cut keeps its
- // content-match fallback so ordinary commits verify without forcing
- // every flow through the commit page.
+ // pre-exist at an untouched path. An explicitly requested scope
+ // names its path exactly, so the naive cut verifies on content
+ // alone β€” the 200-link harvest cap may have cut its blob link, and
+ // there is no scope ambiguity to resolve. Ambiguous cuts keep the
+ // listing requirement (and the content-match fallback when no file
+ // list was observed, so ordinary commits verify without forcing
+ // every flow through the commit page).
if (!naiveAttempt && commitBlobPaths.size === 0) {
alternatesSkippedForEvidence = true;
continue;
@@ -2507,7 +2511,7 @@ export class Agent extends LoopDetector {
&& text.length === expected.expectedLength
&& actualSha256 === expected.expectedSha256;
if (contentMatches
- && (commitBlobPaths.size === 0 || commitBlobPaths.has(attempt.path))) {
+ && ((naiveAttempt && !scopeAmbiguous) || commitBlobPaths.size === 0 || commitBlobPaths.has(attempt.path))) {
if (attempt.branch !== expected.branch || attempt.path !== expected.path) {
binding.githubFileCommit = { ...expected, branch: attempt.branch, path: attempt.path };
}
@@ -21095,6 +21099,41 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
} catch { /* an unavailable probe cannot prove that this is a different field */ }
return selectorReadback;
};
+ let focusedTargetMeta = null;
+ let focusedTargetMetaAttempted = false;
+ const readFocusedTargetMeta = async () => {
+ if (focusedTargetMetaAttempted) return focusedTargetMeta;
+ focusedTargetMetaAttempted = true;
+ if (!(name === 'type_text' && !args.selector && args.index == null
+ && target.locatorType === 'focused')) return null;
+ try {
+ const readback = await this._textMutationValueDigest(tabId, { locatorType: 'focused', ambiguous: false });
+ focusedTargetMeta = readback?.fieldMeta || null;
+ } catch { /* an unavailable probe cannot prove that this is a different field */ }
+ return focusedTargetMeta;
+ };
+ // Live metadata of the current target for the distinctness check below,
+ // probed once per call no matter how many debts are retained. Any
+ // locator type qualifies: ambiguity is about the stored debt's locator,
+ // not about reading the live target.
+ let targetMeta = null;
+ let targetMetaAttempted = false;
+ const readTargetMeta = async () => {
+ if (targetMetaAttempted) return targetMeta;
+ targetMetaAttempted = true;
+ try {
+ if ((name === 'set_field' || name === 'type_ax') && typeof args.ref_id === 'string') {
+ const readback = await readAxTarget();
+ if (readback?.success === true) targetMeta = readback.fieldMeta || null;
+ } else if (name === 'type_text' && typeof args.selector === 'string' && args.selector.trim()) {
+ const readback = await readSelectorTarget();
+ if (readback) targetMeta = readback.fieldMeta || null;
+ } else {
+ targetMeta = await readFocusedTargetMeta();
+ }
+ } catch { targetMeta = null; }
+ return targetMeta;
+ };
let debt = null;
// Shared with the post-adoption re-scope below: out-of-scope debts are
// skipped (retained for a back-forward return), never deleted here.
@@ -21102,28 +21141,17 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
for (const candidate of debts.values()) {
if (candidate.documentToken && target.documentToken
&& candidate.documentToken !== target.documentToken) continue;
- if (candidate.ambiguous || target.ambiguous || candidate.key === target.key) return candidate;
- const distinctAxRefs = candidate.key.startsWith('ax:')
- && target.key.startsWith('ax:')
- && candidate.key !== target.key;
- if (distinctAxRefs) {
- const readback = await readAxTarget();
- if (readback?.success === true
- && this._textMutationFieldsProvenDistinct(candidate.fieldMeta, readback.fieldMeta)) continue;
- }
- // Mirror the AX escape hatch for selector pairs: the digest probe can
- // read the target's live metadata, so a demonstrably different field
- // (two or more differing identity fields, no shared one) must not be
- // blocked by another field's debt. The debt is kept β€” only this
- // dispatch is allowed β€” and an unprovable target stays blocked.
- const distinctSelectors = candidate.locatorType === 'selector'
- && target.locatorType === 'selector'
- && typeof candidate.selector === 'string'
- && typeof target.selector === 'string'
- && candidate.selector !== target.selector;
- if (distinctSelectors) {
- const readback = await readSelectorTarget();
- if (readback && this._textMutationFieldsProvenDistinct(candidate.fieldMeta, readback.fieldMeta)) continue;
+ // Same locator instance: the recovery path below decides (with
+ // positive same-field identity for focused pairs).
+ if (candidate.key === target.key) return candidate;
+ // Positive distinctness across ALL locator types: a demonstrably
+ // different field (two or more differing identity fields, no shared
+ // one) is never blocked by another field's debt β€” focused and
+ // mixed-locator pairs included. The debt is kept; only this dispatch
+ // is allowed. Anything unprovable stays blocked.
+ if (candidate.fieldMeta) {
+ const liveMeta = await readTargetMeta();
+ if (liveMeta && this._textMutationFieldsProvenDistinct(candidate.fieldMeta, liveMeta)) continue;
}
return candidate;
}
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 237333a02..894059d7d 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -2188,9 +2188,13 @@ export class Agent extends LoopDetector {
const naiveAttempt = attempt.branch === expected.branch && attempt.path === expected.path;
// Alternate cuts are only meaningful against the observed changed
// file list: accepting one on content alone would bless bytes that
- // pre-exist at an untouched path. The naive cut keeps its
- // content-match fallback so ordinary commits verify without forcing
- // every flow through the commit page.
+ // pre-exist at an untouched path. An explicitly requested scope
+ // names its path exactly, so the naive cut verifies on content
+ // alone β€” the 200-link harvest cap may have cut its blob link, and
+ // there is no scope ambiguity to resolve. Ambiguous cuts keep the
+ // listing requirement (and the content-match fallback when no file
+ // list was observed, so ordinary commits verify without forcing
+ // every flow through the commit page).
if (!naiveAttempt && commitBlobPaths.size === 0) {
alternatesSkippedForEvidence = true;
continue;
@@ -2221,7 +2225,7 @@ export class Agent extends LoopDetector {
&& text.length === expected.expectedLength
&& actualSha256 === expected.expectedSha256;
if (contentMatches
- && (commitBlobPaths.size === 0 || commitBlobPaths.has(attempt.path))) {
+ && ((naiveAttempt && !scopeAmbiguous) || commitBlobPaths.size === 0 || commitBlobPaths.has(attempt.path))) {
if (attempt.branch !== expected.branch || attempt.path !== expected.path) {
binding.githubFileCommit = { ...expected, branch: attempt.branch, path: attempt.path };
}
@@ -18658,6 +18662,41 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
} catch { /* an unavailable probe cannot prove that this is a different field */ }
return selectorReadback;
};
+ let focusedTargetMeta = null;
+ let focusedTargetMetaAttempted = false;
+ const readFocusedTargetMeta = async () => {
+ if (focusedTargetMetaAttempted) return focusedTargetMeta;
+ focusedTargetMetaAttempted = true;
+ if (!(name === 'type_text' && !args.selector && args.index == null
+ && target.locatorType === 'focused')) return null;
+ try {
+ const readback = await this._textMutationValueDigest(tabId, { locatorType: 'focused', ambiguous: false });
+ focusedTargetMeta = readback?.fieldMeta || null;
+ } catch { /* an unavailable probe cannot prove that this is a different field */ }
+ return focusedTargetMeta;
+ };
+ // Live metadata of the current target for the distinctness check below,
+ // probed once per call no matter how many debts are retained. Any
+ // locator type qualifies: ambiguity is about the stored debt's locator,
+ // not about reading the live target.
+ let targetMeta = null;
+ let targetMetaAttempted = false;
+ const readTargetMeta = async () => {
+ if (targetMetaAttempted) return targetMeta;
+ targetMetaAttempted = true;
+ try {
+ if ((name === 'set_field' || name === 'type_ax') && typeof args.ref_id === 'string') {
+ const readback = await readAxTarget();
+ if (readback?.success === true) targetMeta = readback.fieldMeta || null;
+ } else if (name === 'type_text' && typeof args.selector === 'string' && args.selector.trim()) {
+ const readback = await readSelectorTarget();
+ if (readback) targetMeta = readback.fieldMeta || null;
+ } else {
+ targetMeta = await readFocusedTargetMeta();
+ }
+ } catch { targetMeta = null; }
+ return targetMeta;
+ };
let debt = null;
// Shared with the post-adoption re-scope below: out-of-scope debts are
// skipped (retained for a back-forward return), never deleted here.
@@ -18665,28 +18704,17 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
for (const candidate of debts.values()) {
if (candidate.documentToken && target.documentToken
&& candidate.documentToken !== target.documentToken) continue;
- if (candidate.ambiguous || target.ambiguous || candidate.key === target.key) return candidate;
- const distinctAxRefs = candidate.key.startsWith('ax:')
- && target.key.startsWith('ax:')
- && candidate.key !== target.key;
- if (distinctAxRefs) {
- const readback = await readAxTarget();
- if (readback?.success === true
- && this._textMutationFieldsProvenDistinct(candidate.fieldMeta, readback.fieldMeta)) continue;
- }
- // Mirror the AX escape hatch for selector pairs: the digest probe can
- // read the target's live metadata, so a demonstrably different field
- // (two or more differing identity fields, no shared one) must not be
- // blocked by another field's debt. The debt is kept β€” only this
- // dispatch is allowed β€” and an unprovable target stays blocked.
- const distinctSelectors = candidate.locatorType === 'selector'
- && target.locatorType === 'selector'
- && typeof candidate.selector === 'string'
- && typeof target.selector === 'string'
- && candidate.selector !== target.selector;
- if (distinctSelectors) {
- const readback = await readSelectorTarget();
- if (readback && this._textMutationFieldsProvenDistinct(candidate.fieldMeta, readback.fieldMeta)) continue;
+ // Same locator instance: the recovery path below decides (with
+ // positive same-field identity for focused pairs).
+ if (candidate.key === target.key) return candidate;
+ // Positive distinctness across ALL locator types: a demonstrably
+ // different field (two or more differing identity fields, no shared
+ // one) is never blocked by another field's debt β€” focused and
+ // mixed-locator pairs included. The debt is kept; only this dispatch
+ // is allowed. Anything unprovable stays blocked.
+ if (candidate.fieldMeta) {
+ const liveMeta = await readTargetMeta();
+ if (liveMeta && this._textMutationFieldsProvenDistinct(candidate.fieldMeta, liveMeta)) continue;
}
return candidate;
}
diff --git a/test/run.js b/test/run.js
index b0ec7bd12..4f399b375 100644
--- a/test/run.js
+++ b/test/run.js
@@ -77296,6 +77296,88 @@ test('selector writes to proven-distinct fields bypass unrelated debt', async ()
}
});
+test('distinctness escape covers focused and mixed-locator debts', async () => {
+ const originalChrome = globalThis.chrome;
+ const originalBrowser = globalThis.browser;
+ try {
+ const pageUrl = 'https://example.test/form';
+ const editorMeta = { tag: 'div', contentEditable: true, id: 'editor-1', ariaLabelledByText: 'Editing file contents' };
+ const fieldMetaB = { tag: 'input', id: 'field-b', name: 'field-b', labelText: 'Second', contentEditable: false };
+ for (const [label, AgentClass, tabId, controlTabId] of [
+ ['chrome', AgentCh, 9530, 9532],
+ ['firefox', AgentFx, 9531, 9533],
+ ]) {
+ const agent = new AgentClass({});
+ agent._lastAxScopes.set(tabId, { documentToken: 'doc-cross', pageUrl });
+ const tabs = {
+ async sendMessage(_tabId, message) {
+ assert.equal(message.action, 'field_value_digest');
+ if (message.params?.focused === true) {
+ return { success: true,
+ valueLength: 5, valueSha256: await agent._sha256Text('alpha'),
+ fieldMeta: { ...editorMeta },
+ documentToken: 'doc-cross', refScopeUrl: pageUrl };
+ }
+ if (message.params?.selector === '#b') {
+ return { success: true, valueLength: 4, valueSha256: await agent._sha256Text('beta'),
+ fieldMeta: { ...fieldMetaB } };
+ }
+ return { success: false, documentToken: 'doc-cross', refScopeUrl: pageUrl };
+ },
+ };
+ globalThis.chrome = { tabs };
+ globalThis.browser = { tabs };
+ // Uncertain selectorless write to the editor; identity captured live.
+ await agent._finalizeTextMutationResult(
+ tabId, 'type_text', { text: 'alpha', clear: true },
+ { success: false, dispatched: true, verified: false },
+ );
+ assert.equal(agent._uncertainTextMutations.get(tabId)?.size, 1, `${label}: focused debt was not recorded`);
+ // A demonstrably different selector field must not be blocked by it.
+ const allowed = await agent._uncertainTextMutationBlock(
+ tabId, 'type_text', { selector: '#b', text: 'beta' },
+ );
+ assert.equal(allowed, null, `${label}: distinct field stayed blocked by a focused debt`);
+ assert.equal(agent._uncertainTextMutations.get(tabId)?.size, 1,
+ `${label}: distinct-field dispatch dropped the focused debt`);
+ // Reverse direction: selector debt, focused retry on a distinct field.
+ const control = new AgentClass({});
+ control._lastAxScopes.set(controlTabId, { documentToken: 'doc-cross', pageUrl });
+ const controlTabs = {
+ async sendMessage(_tabId, message) {
+ assert.equal(message.action, 'field_value_digest');
+ if (message.params?.selector === '#a') {
+ return { success: true, valueLength: 5, valueSha256: await control._sha256Text('alpha'),
+ fieldMeta: { tag: 'input', id: 'field-a', name: 'field-a', labelText: 'First', contentEditable: false } };
+ }
+ if (message.params?.focused === true) {
+ return { success: true,
+ valueLength: 5, valueSha256: await control._sha256Text('delta'),
+ fieldMeta: { ...fieldMetaB },
+ documentToken: 'doc-cross', refScopeUrl: pageUrl };
+ }
+ return { success: false, documentToken: 'doc-cross', refScopeUrl: pageUrl };
+ },
+ };
+ globalThis.chrome = { tabs: controlTabs };
+ globalThis.browser = { tabs: controlTabs };
+ await control._finalizeTextMutationResult(
+ controlTabId, 'type_text', { selector: '#a', text: 'alpha', clear: true },
+ { success: false, dispatched: true, verified: false },
+ );
+ const reverseAllowed = await control._uncertainTextMutationBlock(
+ controlTabId, 'type_text', { text: 'delta' },
+ );
+ assert.equal(reverseAllowed, null, `${label}: distinct focused retry stayed blocked by a selector debt`);
+ }
+ } finally {
+ if (originalChrome === undefined) delete globalThis.chrome;
+ else globalThis.chrome = originalChrome;
+ if (originalBrowser === undefined) delete globalThis.browser;
+ else globalThis.browser = originalBrowser;
+ }
+});
+
test('focused field_value_digest and live scope cover selectorless writes', async () => {
for (const rel of [
'src/chrome/src/content/content.js',
@@ -77844,6 +77926,64 @@ test('slash-branch verification derives candidates from changed-file evidence',
}
});
+test('explicit scope verifies without file-listing the path', async () => {
+ const originalFetch = globalThis.fetch;
+ const body = '# Explicit scope document\n\nOne complete copy.\n';
+ const commitSha = '0123456789abcdef0123456789abcdef01234567';
+ const commitUrl = `https://github.com/Example/Repo/commit/${commitSha}`;
+ const naiveUrl = `https://github.com/example/repo/raw/${commitSha}/docs/plan.md`;
+ try {
+ const seen = [];
+ globalThis.fetch = async (url) => {
+ seen.push(url);
+ if (url === naiveUrl) {
+ return { ok: true, status: 200, headers: { get: () => String(body.length) }, text: async () => body };
+ }
+ return { ok: false, status: 404, headers: { get: () => '0' }, text: async () => 'Not Found' };
+ };
+ for (const [label, AgentClass, tabId] of [
+ ['chrome', AgentCh, 9534],
+ ['firefox', AgentFx, 9535],
+ ]) {
+ seen.length = 0;
+ const agent = new AgentClass({});
+ agent._planExecutionGuards.set(tabId, {
+ enabled: true,
+ siteWorkflow: { adapterName: 'github', job: { id: 'edit-file-and-commit' } },
+ });
+ // Explicitly requested scope: the naive cut IS the requested file, so
+ // its content match verifies even though a 200-link truncation cut its
+ // blob link from the observed file list (201 unrelated entries here).
+ const unrelatedBlobs = Array.from({ length: 201 }, (_, index) =>
+ `https://github.com/Example/Repo/blob/${commitSha}/other${index}.md`);
+ const binding = {
+ githubFileCommit: {
+ repository: 'example/repo',
+ branch: 'main',
+ path: 'docs/plan.md',
+ expectedLength: body.length,
+ expectedSha256: await agent._sha256Text(body),
+ commitMessageVerified: true,
+ },
+ metadataRequirements: [
+ { field: 'path', value: 'docs/plan.md' },
+ { field: 'branch', value: 'main' },
+ ],
+ preDispatchPublishedResourceIdentities: [],
+ };
+ const pageState = { workflowResourceUrls: [commitUrl, ...unrelatedBlobs] };
+ const proof = await agent._githubCommittedFileVerification(
+ tabId, pageState, commitUrl, { verifiedFinalSubmit: true, submit: { workflowBinding: binding } },
+ );
+ assert.equal(proof.verified, true, `${label}: exact explicit scope was not verified without listing`);
+ assert.equal(proof.path, 'docs/plan.md');
+ assert.ok(seen.includes(naiveUrl), `${label}: exact path was not fetched`);
+ }
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
test('Firefox selector debt recovers on exact digest readback', async () => {
const originalChrome = globalThis.chrome;
const originalBrowser = globalThis.browser;