Skip to content

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

Canonicalize tool-arg loop keys so key order cannot dodge the limit

release-verificationfe86ee6b9c08
diff --git a/src/chrome/src/agent/loop-bucket.js b/src/chrome/src/agent/loop-bucket.js
index ba382c928..3230b4ba5 100644
--- a/src/chrome/src/agent/loop-bucket.js
+++ b/src/chrome/src/agent/loop-bucket.js
@@ -157,9 +157,54 @@ function _ghResourceBucket(host, path) {
return null; // not a GitHub host
}
+/**
+ * Deterministic JSON with object keys in sorted order.
+ *
+ * `JSON.stringify` preserves insertion order, so `{selector:"#a",text:"x"}`
+ * and `{text:"x",selector:"#a"}` β€” the same rejected call β€” hash to two
+ * different loop keys. A model that keeps re-emitting the same invalid
+ * argument object can then permute key order on every attempt and never
+ * reach the rejection limit. Sorting keys collapses those variants into one
+ * identity. Array order is preserved because element order is meaningful.
+ *
+ * `undefined`/function/symbol values are dropped from objects and become
+ * `null` inside arrays, exactly as `JSON.stringify` does, so an absent
+ * argument and an explicitly undefined one stay one identity.
+ */
+function canonicalJson(value, seen = new Set()) {
+ if (value === null) return 'null';
+ if (typeof value !== 'object') return _canonicalScalar(value);
+ if (seen.has(value)) return '"[circular]"';
+ seen.add(value);
+ let encoded;
+ if (Array.isArray(value)) {
+ encoded = `[${value.map(entry => canonicalJson(entry, seen)).join(',')}]`;
+ } else {
+ const members = [];
+ for (const key of Object.keys(value).sort()) {
+ if (_isOmittable(value[key])) continue;
+ members.push(`${JSON.stringify(key)}:${canonicalJson(value[key], seen)}`);
+ }
+ encoded = `{${members.join(',')}}`;
+ }
+ seen.delete(value);
+ return encoded;
+}
+
+function _isOmittable(value) {
+ return value === undefined || typeof value === 'function' || typeof value === 'symbol';
+}
+
+function _canonicalScalar(value) {
+ if (typeof value === 'bigint') return JSON.stringify(value.toString());
+ if (typeof value === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+ return JSON.stringify(value) ?? 'null';
+}
+
/**
* Build the loop-detector key for a tool call. URL-family tools bucket
- * by resource + method; other tools fall back to exact JSON args.
+ * by resource + method; other tools fall back to key-order-independent
+ * JSON args.
*
* Returns the args-portion of the loop key. Caller appends `|name|errored`.
*/
@@ -171,7 +216,7 @@ export function bucketArgsKey(name, args) {
const fetchTextWindow = name === 'fetch_url' ? _fetchTextWindowKey(args) : '';
return `url:${bucket}|${method}${pageSourceRange}${fetchTextWindow}`;
}
- return JSON.stringify(args || {});
+ return canonicalJson(args || {});
}
function _pageSourceRangeKey(args) {
diff --git a/src/chrome/src/agent/loop-detector.js b/src/chrome/src/agent/loop-detector.js
index 6ea1a8963..fd8353062 100644
--- a/src/chrome/src/agent/loop-detector.js
+++ b/src/chrome/src/agent/loop-detector.js
@@ -34,7 +34,7 @@ export class LoopDetector {
// interleaving reads cannot evade the generic loop detector.
this.noProgressScrolls = new Map(); // tabId -> { key, count }
// Separate buffer for coordinate-based click attempts. The general loop
- // detector keys on JSON.stringify(args), so when the model interleaves
+ // detector keys on the exact argument bucket, so when the model interleaves
// execute_js with different code strings between clicks, the same
// (x,y) click never accumulates to the threshold inside its window.
// This buffer tracks ONLY coord clicks and survives any amount of
diff --git a/src/firefox/src/agent/loop-bucket.js b/src/firefox/src/agent/loop-bucket.js
index ba382c928..3230b4ba5 100644
--- a/src/firefox/src/agent/loop-bucket.js
+++ b/src/firefox/src/agent/loop-bucket.js
@@ -157,9 +157,54 @@ function _ghResourceBucket(host, path) {
return null; // not a GitHub host
}
+/**
+ * Deterministic JSON with object keys in sorted order.
+ *
+ * `JSON.stringify` preserves insertion order, so `{selector:"#a",text:"x"}`
+ * and `{text:"x",selector:"#a"}` β€” the same rejected call β€” hash to two
+ * different loop keys. A model that keeps re-emitting the same invalid
+ * argument object can then permute key order on every attempt and never
+ * reach the rejection limit. Sorting keys collapses those variants into one
+ * identity. Array order is preserved because element order is meaningful.
+ *
+ * `undefined`/function/symbol values are dropped from objects and become
+ * `null` inside arrays, exactly as `JSON.stringify` does, so an absent
+ * argument and an explicitly undefined one stay one identity.
+ */
+function canonicalJson(value, seen = new Set()) {
+ if (value === null) return 'null';
+ if (typeof value !== 'object') return _canonicalScalar(value);
+ if (seen.has(value)) return '"[circular]"';
+ seen.add(value);
+ let encoded;
+ if (Array.isArray(value)) {
+ encoded = `[${value.map(entry => canonicalJson(entry, seen)).join(',')}]`;
+ } else {
+ const members = [];
+ for (const key of Object.keys(value).sort()) {
+ if (_isOmittable(value[key])) continue;
+ members.push(`${JSON.stringify(key)}:${canonicalJson(value[key], seen)}`);
+ }
+ encoded = `{${members.join(',')}}`;
+ }
+ seen.delete(value);
+ return encoded;
+}
+
+function _isOmittable(value) {
+ return value === undefined || typeof value === 'function' || typeof value === 'symbol';
+}
+
+function _canonicalScalar(value) {
+ if (typeof value === 'bigint') return JSON.stringify(value.toString());
+ if (typeof value === 'number') return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+ return JSON.stringify(value) ?? 'null';
+}
+
/**
* Build the loop-detector key for a tool call. URL-family tools bucket
- * by resource + method; other tools fall back to exact JSON args.
+ * by resource + method; other tools fall back to key-order-independent
+ * JSON args.
*
* Returns the args-portion of the loop key. Caller appends `|name|errored`.
*/
@@ -171,7 +216,7 @@ export function bucketArgsKey(name, args) {
const fetchTextWindow = name === 'fetch_url' ? _fetchTextWindowKey(args) : '';
return `url:${bucket}|${method}${pageSourceRange}${fetchTextWindow}`;
}
- return JSON.stringify(args || {});
+ return canonicalJson(args || {});
}
function _pageSourceRangeKey(args) {
diff --git a/src/firefox/src/agent/loop-detector.js b/src/firefox/src/agent/loop-detector.js
index 6ea1a8963..fd8353062 100644
--- a/src/firefox/src/agent/loop-detector.js
+++ b/src/firefox/src/agent/loop-detector.js
@@ -34,7 +34,7 @@ export class LoopDetector {
// interleaving reads cannot evade the generic loop detector.
this.noProgressScrolls = new Map(); // tabId -> { key, count }
// Separate buffer for coordinate-based click attempts. The general loop
- // detector keys on JSON.stringify(args), so when the model interleaves
+ // detector keys on the exact argument bucket, so when the model interleaves
// execute_js with different code strings between clicks, the same
// (x,y) click never accumulates to the threshold inside its window.
// This buffer tracks ONLY coord clicks and survives any amount of
diff --git a/test/agent-lifecycle.mjs b/test/agent-lifecycle.mjs
index 9ff433714..15885a4ab 100644
--- a/test/agent-lifecycle.mjs
+++ b/test/agent-lifecycle.mjs
@@ -52,14 +52,21 @@ for (const [browser, Agent] of variants) {
imageWidth: 1102, imageHeight: 746, cssWidth: 1102, cssHeight: 746,
});
// Capture churn and JSON property order must not disguise one failure.
+ // Coordinate failures carry a constant failureScope, so only the
+ // invalid-schema case can be hidden by reordering β€” it has to build
+ // its own key-ordered args to exercise the default scope.
const entries = [
['x', 800], ['y', failure === 'out-of-bounds' ? 780 : 400],
['coordinate_space', 'screenshot'],
...(failure === 'missing capture' ? [] : [['capture_id', failure === 'stale capture' ? `old-${attempt}` : capture.captureId]]),
];
- if (attempt % 2 === 0) entries.reverse();
+ const schemaEntries = [['text', '02'], ['selector', '#jj']];
+ if (attempt % 2 === 0) {
+ entries.reverse();
+ schemaEntries.reverse();
+ }
const args = failure === 'malformed JSON' ? '{"x":'
- : failure === 'invalid schema' ? '{"text":"02","selector":"#jj"}'
+ : failure === 'invalid schema' ? JSON.stringify(Object.fromEntries(schemaEntries))
: JSON.stringify(Object.fromEntries(entries));
const name = failure === 'invalid schema' ? 'set_field' : 'click';
results.push(await agent._executeToolBatch(
diff --git a/test/run.js b/test/run.js
index 8b518d1fe..5abc95376 100644
--- a/test/run.js
+++ b/test/run.js
@@ -818,6 +818,11 @@ class ConfiguredLoopDetector extends LoopDetectorCh {
return MUTATION_TOOLS_CH.has(toolName);
}
}
+class ConfiguredLoopDetectorFx extends LoopDetectorFx {
+ _isBrowserMutationTool(toolName) {
+ return MUTATION_TOOLS_FX.has(toolName);
+ }
+}
const {
detectProgressAction,
isValidLedgerStatus,
@@ -23028,7 +23033,7 @@ test('fetch_url loop buckets allow semantic pages/searches but collapse guessed
assert.equal(rangeA, bucketArgsKeyFx('fetch_url', { url, headers: { Range: 'bytes=0-9999' } }), 'firefox Range bucket drift');
});
-test('bucketArgsKey: non-URL tools fall back to exact JSON args', () => {
+test('bucketArgsKey: non-URL tools fall back to key-order-independent JSON args', () => {
// click_ax with the same ref_id should match itself
assert.equal(
bucketArgsKey('click_ax', { ref_id: 'ref_42' }),
@@ -23041,6 +23046,58 @@ test('bucketArgsKey: non-URL tools fall back to exact JSON args', () => {
);
});
+test('bucketArgsKey: reordered object keys cannot disguise one rejected call', () => {
+ // JSON.stringify keeps insertion order, so a model that re-emits the same
+ // invalid argument object with its keys permuted would hash to a fresh key
+ // every attempt and never hit the rejection limit.
+ for (const key of [bucketArgsKey, bucketArgsKeyFx]) {
+ assert.equal(
+ key('set_field', { text: '02', selector: '#jj' }),
+ key('set_field', { selector: '#jj', text: '02' }),
+ 'top-level key order must not change the loop identity',
+ );
+ assert.equal(
+ key('click', { x: 10, y: 20, meta: { a: 1, b: 2 } }),
+ key('click', { meta: { b: 2, a: 1 }, y: 20, x: 10 }),
+ 'nested key order must not change the loop identity',
+ );
+ assert.notEqual(
+ key('click', { steps: [1, 2] }),
+ key('click', { steps: [2, 1] }),
+ 'array order is semantic and must stay distinct',
+ );
+ assert.notEqual(
+ key('set_field', { text: '02', selector: '#jj' }),
+ key('set_field', { text: '03', selector: '#jj' }),
+ 'different values are different calls',
+ );
+ }
+ // Degenerate values must not throw or collapse into one identity.
+ const cyclic = { text: '02' };
+ cyclic.self = cyclic;
+ assert.equal(bucketArgsKey('set_field', cyclic), bucketArgsKey('set_field', cyclic));
+ assert.equal(bucketArgsKey('set_field'), bucketArgsKey('set_field', null));
+ assert.equal(
+ bucketArgsKey('set_field', { text: undefined, extra: 1 }),
+ bucketArgsKey('set_field', { extra: 1 }),
+ 'undefined values must not split an identity',
+ );
+});
+
+test('rejected invalid-schema calls share one failure scope across key orders', () => {
+ for (const [label, Detector] of [['chrome', ConfiguredLoopDetector], ['firefox', ConfiguredLoopDetectorFx]]) {
+ const detector = new Detector();
+ const tabId = 1;
+ const rejection = { success: false, invalidArguments: true, noDispatch: true, dispatched: false };
+ const outcomes = [
+ { text: '02', selector: '#jj' },
+ { selector: '#jj', text: '02' },
+ { selector: '#jj', text: '02' },
+ ].map(args => detector._checkLoop(tabId, 'set_field', args, rejection).kind);
+ assert.deepEqual(outcomes, ['none', 'nudge', 'stop'], `${label}: key order must not dodge the limit`);
+ }
+});
+
test('URL_FAMILY_TOOLS contains the expected tool names', () => {
// Lock the membership so a future contributor doesn't accidentally
// remove fetch_url and silently regress the loop detector.
@@ -23079,6 +23136,8 @@ test('firefox loop-bucket matches chrome', () => {
['fetch_url', { url: 'https://api.github.com/repos/o/r/contents/foo.json', method: 'POST' }],
['click_ax', { ref_id: 'ref_42' }],
['fetch_url', { url: 'not a url' }],
+ ['set_field', { selector: '#jj', nested: { b: 2, a: [1, 2] }, text: '02' }],
+ ['set_field', { text: undefined, extra: 1 }],
];
for (const [name, args] of samples) {
assert.equal(bucketArgsKeyFx(name, args), bucketArgsKey(name, args), `mismatch on ${name} ${JSON.stringify(args)}`);