Skip to content

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

Handle expired CAPTCHA answers without trapping completion

Emre Sokulluedac76ed8cb2
diff --git a/docs/captcha-provider-coverage.md b/docs/captcha-provider-coverage.md
index 26f1818e2..8cd6ac87c 100644
--- a/docs/captcha-provider-coverage.md
+++ b/docs/captcha-provider-coverage.md
@@ -142,7 +142,7 @@ Text instructions and instruction images are compared separately, so a recogniti
FunCaptcha fallbacks compare the Arkose service host even when one provider takes a subdomain and another takes a full `surl` URL. The native dispatch lock is stored before contacting a paid provider. An unexpired answer is stored for worker recovery; if a solve was dispatched but its answer is unavailable after restart, the gate requires manual completion rather than a second paid call.
Clearing the chat on the same page keeps the native dispatch lock and any unapplied paid answer. The pending verification gate directs the next Act/Dev mid or full run to call `get_captcha_capabilities`, which returns `pendingNativeAnswer` with the original provider, method, and structured solution after checking the current document. Apply it with `apply_captcha_solution`; do not buy another solve. The answer expires after three minutes and is discarded when the page document changes. Compact and Ask modes still require manual completion because the CAPTCHA tools are unavailable there.
-Recovered answers receive the same untrusted-content protection as the original solve result. When discovery confirms that the root document changed, including a reload at the same URL, it releases the old verification gate while retaining that document's paid-dispatch history.
+Recovered answers receive the same untrusted-content protection as the original solve result. An expired answer requires manual completion and permits reporting a partial outcome, even if document inspection temporarily fails. When discovery confirms that the root document changed, including a reload at the same URL, it releases the old verification gate while retaining that document's paid-dispatch history. That retirement survives a worker restart and cannot clear a new document's challenge gate.
The native adapter rejects undeclared nested fields in schemas with enumerated children, such as CapMonster `metadata`. Provider-documented free-form option objects, including NopeCHA Enterprise `data`, remain available.
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 8030e22a2..5dff58da0 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -10847,18 +10847,30 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
async _pendingNativeCaptchaAnswer(tabId, api = chrome) {
const record = this._nativeCaptchaSolutions?.get(tabId);
- if (record?.solution === undefined || record.applied === true
- || Date.now() - record.createdAt > 180_000) return null;
+ if (!record || record.applied === true || record.documentRetired === true) return null;
let status;
- try { status = await captchaAnswerDocumentStatus(tabId, record, {}, api); } catch { return null; }
- if (status === 'root_changed' || status === 'frame_changed') {
+ try { status = await captchaAnswerDocumentStatus(tabId, record, {}, api); } catch { /* Expiry is still conclusive when inspection fails. */ }
+ if (status === 'root_changed') {
delete record.solution;
- // A new root document may expose a fresh CAPTCHA. Its predecessor's
- // pending gate must not block solving or partial completion here.
- if (status === 'root_changed') this._captchaGateStates.delete(tabId);
+ // Keep the paid history, but retire this document only once so later
+ // discovery cannot clear a gate belonging to the replacement document.
+ record.documentRetired = true;
+ this._captchaGateStates.delete(tabId);
+ return null;
+ }
+ const expired = record.solution !== undefined && Date.now() - record.createdAt > 180_000;
+ if (expired || status === 'frame_changed') {
+ delete record.solution;
+ const gate = this._captchaGateStates.get(tabId);
+ if (gate && gate.status !== 'cleared') {
+ this._captchaGateStates.set(tabId, { ...gate, status: 'manual_required',
+ ...(gate.captchaToolsPreviousStatus ? { captchaToolsPreviousStatus: 'manual_required' } : {}),
+ publicGate: { ...gate.publicGate, status: 'manual_required', solveAttempted: true,
+ nativeAnswerPending: false, ...(expired ? { nativeAnswerExpired: true } : {}) } });
+ }
return null;
}
- if (status !== 'current') return null;
+ if (status !== 'current' || record.solution === undefined) return null;
return { provider: record.provider || null, method: record.method || null,
family: record.family || null, taskId: record.taskId || null,
solution: record.solution,
@@ -10885,7 +10897,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
resultContent += '\n[TRUSTED CAPTCHA GATE: A supported verification challenge is active. Call solve_captcha once now. Do not dismiss or close the dialog, click Continue/Submit, or use another page-changing tool until solve_captcha returns.]';
onUpdate('warning', { message: 'Supported verification challenge detected; solve_captcha is required.' });
} else if (captchaGateDecision?.status === 'manual_required') {
- resultContent += captchaGateDecision.nativeDispatchInterrupted === true
+ resultContent += captchaGateDecision.nativeAnswerExpired === true
+ ? '\n[TRUSTED CAPTCHA GATE: The previously paid answer has expired. Ask the user to complete verification manually and report blocked work with done({outcome:"partial"}). Do not send another paid request for this document.]'
+ : captchaGateDecision.nativeDispatchInterrupted === true
? '\n[TRUSTED CAPTCHA GATE: A native solve was already dispatched for this document, but its answer is unavailable after restart. Do not send another paid request or submit the page; ask the user to complete the challenge manually.]'
: captchaGateDecision.cloudflareManagedChallenge === true
? '\n[TRUSTED CAPTCHA GATE: A response-backed full-page Cloudflare managed challenge is active. Inspect get_captcha_capabilities for a Cloudflare native method; use one solve_captcha providerTasks dispatch only with all required observed inputs, otherwise ask for manual completion. Do not submit; the network/navigation monitor will clear the gate when Cloudflare resumes the destination.]'
@@ -16570,7 +16584,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
) {
if (!cloudflareSignal) {
const gate = normalizeCaptchaGateState(captchaGateState);
- if (nativeDispatchRestored && !nativeAnswerRestored && !savedDispatch.applied
+ if (nativeDispatchRestored && !nativeAnswerRestored && !savedDispatch.applied && !savedDispatch.documentRetired
&& ['solve_required', 'verification_pending'].includes(gate.status)) {
this._captchaGateStates.set(tabId, { ...gate, status: 'manual_required',
publicGate: { ...gate.publicGate, status: 'manual_required', solveAttempted: true,
@@ -16625,6 +16639,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
&& nativeAnswer.dispatchedTimeOrigins instanceof Set
? { pageUrl: nativeAnswer.pageUrl, createdAt: nativeAnswer.createdAt,
applied: nativeAnswer.applied === true, applicationSucceeded: nativeAnswer.applicationSucceeded === true,
+ documentRetired: nativeAnswer.documentRetired === true,
documents: nativeAnswer.documents,
dispatchedTimeOrigins: [...nativeAnswer.dispatchedTimeOrigins] }
: null;
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 947e6de39..e18f92b62 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -5997,7 +5997,7 @@ export class Agent extends LoopDetector {
) {
if (!cloudflareSignal) {
const gate = normalizeCaptchaGateState(captchaGateState);
- if (nativeDispatchRestored && !nativeAnswerRestored && !savedDispatch.applied
+ if (nativeDispatchRestored && !nativeAnswerRestored && !savedDispatch.applied && !savedDispatch.documentRetired
&& ['solve_required', 'verification_pending'].includes(gate.status)) {
this._captchaGateStates.set(tabId, { ...gate, status: 'manual_required',
publicGate: { ...gate.publicGate, status: 'manual_required', solveAttempted: true,
@@ -6052,6 +6052,7 @@ export class Agent extends LoopDetector {
&& nativeAnswer.dispatchedTimeOrigins instanceof Set
? { pageUrl: nativeAnswer.pageUrl, createdAt: nativeAnswer.createdAt,
applied: nativeAnswer.applied === true, applicationSucceeded: nativeAnswer.applicationSucceeded === true,
+ documentRetired: nativeAnswer.documentRetired === true,
documents: nativeAnswer.documents,
dispatchedTimeOrigins: [...nativeAnswer.dispatchedTimeOrigins] }
: null;
@@ -9520,18 +9521,30 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
async _pendingNativeCaptchaAnswer(tabId, api = browser) {
const record = this._nativeCaptchaSolutions?.get(tabId);
- if (record?.solution === undefined || record.applied === true
- || Date.now() - record.createdAt > 180_000) return null;
+ if (!record || record.applied === true || record.documentRetired === true) return null;
let status;
- try { status = await captchaAnswerDocumentStatus(tabId, record, {}, api); } catch { return null; }
- if (status === 'root_changed' || status === 'frame_changed') {
+ try { status = await captchaAnswerDocumentStatus(tabId, record, {}, api); } catch { /* Expiry is still conclusive when inspection fails. */ }
+ if (status === 'root_changed') {
delete record.solution;
- // A new root document may expose a fresh CAPTCHA. Its predecessor's
- // pending gate must not block solving or partial completion here.
- if (status === 'root_changed') this._captchaGateStates.delete(tabId);
+ // Keep the paid history, but retire this document only once so later
+ // discovery cannot clear a gate belonging to the replacement document.
+ record.documentRetired = true;
+ this._captchaGateStates.delete(tabId);
+ return null;
+ }
+ const expired = record.solution !== undefined && Date.now() - record.createdAt > 180_000;
+ if (expired || status === 'frame_changed') {
+ delete record.solution;
+ const gate = this._captchaGateStates.get(tabId);
+ if (gate && gate.status !== 'cleared') {
+ this._captchaGateStates.set(tabId, { ...gate, status: 'manual_required',
+ ...(gate.captchaToolsPreviousStatus ? { captchaToolsPreviousStatus: 'manual_required' } : {}),
+ publicGate: { ...gate.publicGate, status: 'manual_required', solveAttempted: true,
+ nativeAnswerPending: false, ...(expired ? { nativeAnswerExpired: true } : {}) } });
+ }
return null;
}
- if (status !== 'current') return null;
+ if (status !== 'current' || record.solution === undefined) return null;
return { provider: record.provider || null, method: record.method || null,
family: record.family || null, taskId: record.taskId || null,
solution: record.solution,
@@ -9558,7 +9571,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
resultContent += '\n[TRUSTED CAPTCHA GATE: A supported verification challenge is active. Call solve_captcha once now. Do not dismiss or close the dialog, click Continue/Submit, or use another page-changing tool until solve_captcha returns.]';
onUpdate('warning', { message: 'Supported verification challenge detected; solve_captcha is required.' });
} else if (captchaGateDecision?.status === 'manual_required') {
- resultContent += captchaGateDecision.nativeDispatchInterrupted === true
+ resultContent += captchaGateDecision.nativeAnswerExpired === true
+ ? '\n[TRUSTED CAPTCHA GATE: The previously paid answer has expired. Ask the user to complete verification manually and report blocked work with done({outcome:"partial"}). Do not send another paid request for this document.]'
+ : captchaGateDecision.nativeDispatchInterrupted === true
? '\n[TRUSTED CAPTCHA GATE: A native solve was already dispatched for this document, but its answer is unavailable after restart. Do not send another paid request or submit the page; ask the user to complete the challenge manually.]'
: captchaGateDecision.cloudflareManagedChallenge === true
? '\n[TRUSTED CAPTCHA GATE: A response-backed full-page Cloudflare managed challenge is active. Inspect get_captcha_capabilities for a Cloudflare native method; use one solve_captcha providerTasks dispatch only with all required observed inputs, otherwise ask for manual completion. Do not submit; the network/navigation monitor will clear the gate when Cloudflare resumes the destination.]'
diff --git a/test/captcha-runtime-policy.mjs b/test/captcha-runtime-policy.mjs
index 1e3b4f14c..deb0d3cb1 100644
--- a/test/captcha-runtime-policy.mjs
+++ b/test/captcha-runtime-policy.mjs
@@ -270,6 +270,80 @@ for (const build of ['chrome', 'firefox']) {
assert.deepEqual(agent._conversationStorageEntry(1).nativeCaptchaDispatch.dispatchedTimeOrigins, [1000]);
} finally { globalThis[key] = previous; }
});
+ for (const inspection of ['same document', 'reloaded', 'failed', 'inconclusive']) {
+ test(`${build}: expired answer recovery with ${inspection} inspection exits safely`, async () => {
+ const agent = agentFor('act', 'full');
+ const pageUrl = 'https://example.test/challenge';
+ const record = { pageUrl, createdAt: Date.now() - 180_001, applied: false,
+ solution: { token: 'expired-answer' }, documents: [{ frameId: 0, url: pageUrl, timeOrigin: 1000 }],
+ dispatchedTimeOrigins: new Set([1000]) };
+ agent._nativeCaptchaSolutions = new Map([[1, record]]);
+ agent._captchaGateStates.set(1, { key: `native:${pageUrl}`, status: 'verification_pending',
+ publicGate: { status: 'verification_pending', solveAttempted: true, nativeAnswerPending: true } });
+ const key = build === 'chrome' ? 'chrome' : 'browser';
+ const previous = globalThis[key];
+ let timeOrigin = inspection === 'reloaded' ? 2000 : 1000;
+ let inspectionState = inspection;
+ let reads = 0;
+ let saved;
+ const read = () => {
+ reads++;
+ if (inspectionState === 'failed') throw new Error('Temporary inspection failure');
+ return inspectionState === 'inconclusive' ? [] : [{ frameId: 0, result: { url: pageUrl, timeOrigin } }];
+ };
+ globalThis[key] = {
+ storage: { local: { get: async () => ({}) }, session: { get: async name => ({ [name]: saved }) } },
+ tabs: { get: async () => ({ url: pageUrl }), executeScript: async () => read().map(entry => entry.result) },
+ webNavigation: { getAllFrames: async () => [{ frameId: 0, url: pageUrl }] },
+ ...(build === 'chrome' ? { scripting: { executeScript: async () => read() } } : {}),
+ };
+ try {
+ const result = await agent._executeToolImpl(1, 'get_captcha_capabilities', {});
+ assert.equal(result.pendingNativeAnswer, undefined);
+ assert.ok(reads > 0, 'expiry must not skip checking for a new document');
+ assert.equal(record.solution, undefined);
+ assert.equal(agent._hasUnappliedNativeCaptchaSolution(1), false);
+ assert.equal(record.dispatchedTimeOrigins.has(1000), true);
+ assert.equal(agent._captchaGateBlockResult(1, 'done', { outcome: 'partial' }), null);
+ if (inspection === 'reloaded') {
+ assert.equal(agent._captchaGateStates.has(1), false);
+ } else {
+ const gate = agent._captchaGateStates.get(1);
+ assert.equal(gate.status, 'manual_required');
+ assert.equal(gate.publicGate.nativeAnswerExpired, true);
+ assert.equal(gate.publicGate.nativeAnswerPending, false);
+ assert.equal(agent._captchaGateBlockResult(1, 'solve_captcha', { providerTasks: [{}] }).denied, true);
+ const routing = agent._captchaRoutingMessage(1, gate.publicGate);
+ assert.match(routing, /expired.*manually/);
+ assert.doesNotMatch(routing, solverInstructions);
+ }
+ saved = structuredClone(agent._conversationStorageEntry(1));
+ assert.equal(saved.nativeCaptchaAnswer, null);
+ assert.deepEqual(saved.nativeCaptchaDispatch.dispatchedTimeOrigins, [1000]);
+ const restored = agentFor('act', 'full');
+ await restored._hydrate(1);
+ assert.equal(restored._hasUnappliedNativeCaptchaSolution(1), false);
+ assert.equal(restored._captchaGateBlockResult(1, 'done', { outcome: 'partial' }), null);
+ // A later confirmed reload can release even an already-expired,
+ // restored answer's gate without resetting its paid-dispatch history.
+ inspectionState = 'same document';
+ timeOrigin = 2000;
+ await restored._executeToolImpl(1, 'get_captcha_capabilities', {});
+ assert.equal(restored._captchaGateStates.has(1), false);
+ assert.equal(restored._nativeCaptchaSolutions.get(1).dispatchedTimeOrigins.has(1000), true);
+ const newGate = { key: 'new-document-captcha', status: 'solve_required', publicGate: { status: 'solve_required' } };
+ restored._captchaGateStates.set(1, newGate);
+ await restored._executeToolImpl(1, 'get_captcha_capabilities', {});
+ assert.equal(restored._captchaGateStates.get(1), newGate, 'retiring the old record must not clear a new challenge gate');
+ saved = structuredClone(restored._conversationStorageEntry(1));
+ const fresh = agentFor('act', 'full');
+ await fresh._hydrate(1);
+ assert.equal(fresh._captchaGateStates.get(1).status, 'solve_required');
+ await fresh._executeToolImpl(1, 'get_captcha_capabilities', {});
+ assert.equal(fresh._captchaGateStates.get(1).status, 'solve_required');
+ } finally { globalThis[key] = previous; }
+ });
+ }
test(`${build}: query and fragment navigation retire an answer and release its gate`, () => {
for (const to of ['https://example.test/challenge?step=2', 'https://example.test/challenge?step=1#next']) {
const agent = agentFor('act', 'full');