From d27a19f6b713d687073ea9d9e1b0384e50d0a606 Mon Sep 17 00:00:00 2001 From: archandatta <35818003+archandatta@users.noreply.github.com> Date: Tue, 22 Sep 2026 17:14:48 +0000 Subject: [PATCH] Document per-type captcha telemetry coverage Add a per-captcha_type table of which events and identifiers are emitted, state the challenge statuses each observed type reports, and add GeeTest and hCaptcha limits to the pausing-for-captcha-solves cookbook. Co-Authored-By: Claude Fable 5.1 --- browsers/telemetry/categories.mdx | 14 ++++++++++++++ browsers/telemetry/pausing-for-captcha-solves.mdx | 2 ++ 2 files changed, 16 insertions(+) diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index ffa6b711..fede1c6a 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -86,6 +86,20 @@ A visible captcha challenge can require multiple solver tasks. When the identifi Challenge results are currently emitted for visible reCAPTCHA v2, hCaptcha, and press-and-hold challenges. Other captcha types can emit task events without a challenge result. Telemetry delivery is best-effort and isn't ordered: a start can arrive after its result, and any event can be absent. When you need a challenge-level outcome, wait for a bounded interval and fall back to available task results and the current page state. +What each `captcha_type` emits today: + +| `captcha_type` | Task events | `captcha_challenge_result` | `challenge_id` on task events | +| --- | --- | --- | --- | +| `hcaptcha` | Yes | Yes | Yes | +| `press_and_hold` | Yes | Yes | Yes | +| `recaptcha_v2` | Yes | Yes | Can be absent | +| `turnstile` | Yes | No | Can be absent | +| `geetest` | Yes | No | Can be absent | +| `recaptcha_v3` | Yes | No | Can be absent | +| `other` | Yes | No | Can be absent | + +Challenge results for `recaptcha_v2` and `hcaptcha` report `solved` or `abandoned`. `failure` and `timeout` are reported for `press_and_hold`, whose solver has an explicit attempt budget. + Task events carry a `task_id`, but not all of them carry a `challenge_id`. Kernel sets `challenge_id` from tracking the challenge widget in the page - the same tracking that produces `captcha_challenge_result` - so a task the automatic solver runs without it reports a `task_id` only. Those task events can't be joined to a challenge result for the same page, even when one is emitted. Pair a start with its result on `task_id`, and use `challenge_id` for grouping only when it's there. Use each result event's `duration_ms` as the authoritative duration rather than calculating it from event timestamps. Challenge duration covers every solver attempt from when the challenge appeared until its terminal outcome. diff --git a/browsers/telemetry/pausing-for-captcha-solves.mdx b/browsers/telemetry/pausing-for-captcha-solves.mdx index 19ff0f85..5f21af34 100644 --- a/browsers/telemetry/pausing-for-captcha-solves.mdx +++ b/browsers/telemetry/pausing-for-captcha-solves.mdx @@ -582,6 +582,8 @@ Durations come straight from each event's `duration_ms`, which is authoritative; - **Challenge results aren't emitted for every widget type.** Turnstile, for instance, reports task events only, so the task-plus-page path is the one that runs there. - **One episode at a time.** The gate resets after each verdict; overlapping visible challenges from the same provider aren't split apart, and the telemetry docs note Kernel's own event model can't always attribute a result in that case either. - **The page probe is best-effort.** It reads the DOM for known widget markers and a response token. A site that renders its challenge somewhere those selectors miss won't be held past the logged message alone. +- **GeeTest has no selector either.** The solver reports `geetest` task events, but `PROBE`'s `groups` has no GeeTest entry and `tokenPresent` checks no GeeTest field, so `widgets` never reports one and the agent proceeds as soon as the task settles, even while the challenge is still open. Add a selector for your target's GeeTest integration if you need it to hold. +- **hCaptcha coverage depends on your organization's configuration.** When the hCaptcha solver isn't enabled for your org, hCaptcha pages produce no captcha events and the gate falls through to the page probe. - **Press-and-hold has no selector at all.** It emits `captcha_challenge_result` telemetry like reCAPTCHA and hCaptcha, but `PROBE`'s `groups` has no entry for it, so `widgets` never reports one -- the tool-call handler treats that as clear and lets the agent proceed even while the challenge is still open. Add a selector for your target's specific implementation if you need it to actually hold. - **A reload within `TASK_SETTLE_MS` of the last verdict can still be missed.** `settledAt` treats an ID as fresh again once that window passes, so a genuinely new outcome for a reused `challenge_id` eventually gets through -- but if the reload happens sooner than that, its result is indistinguishable from a stale duplicate and gets dropped.