From 66f6eaf26d7bdee5311b0a2a66c4806e319872a8 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 12:56:42 +0000 Subject: [PATCH 1/3] feat: Expose captcha task and challenge outcomes Stainless-Generated-From: e690865cea8183ed670fdd3f7617e0541adfe810 --- api.md | 2 + src/resources/browsers/browsers.ts | 4 + src/resources/browsers/index.ts | 2 + src/resources/browsers/telemetry.ts | 209 +++++++++++++++++++++++++++- 4 files changed, 210 insertions(+), 7 deletions(-) diff --git a/api.md b/api.md index 86519a7f..3c2115ac 100644 --- a/api.md +++ b/api.md @@ -130,7 +130,9 @@ Types: - BrowserAPICallEvent - BrowserCallStack +- BrowserCaptchaChallengeResultEvent - BrowserCaptchaSolveResultEvent +- BrowserCaptchaSolveStartedEvent - BrowserCdpCommandEvent - BrowserCdpCommandMethod - BrowserCdpConnectEvent diff --git a/src/resources/browsers/browsers.ts b/src/resources/browsers/browsers.ts index a601fe86..0c9b537b 100644 --- a/src/resources/browsers/browsers.ts +++ b/src/resources/browsers/browsers.ts @@ -55,7 +55,9 @@ import * as TelemetryAPI from './telemetry'; import { BrowserAPICallEvent, BrowserCallStack, + BrowserCaptchaChallengeResultEvent, BrowserCaptchaSolveResultEvent, + BrowserCaptchaSolveStartedEvent, BrowserCdpCommandEvent, BrowserCdpCommandMethod, BrowserCdpConnectEvent, @@ -1650,7 +1652,9 @@ export declare namespace Browsers { TelemetryAPITelemetry as Telemetry, type BrowserAPICallEvent as BrowserAPICallEvent, type BrowserCallStack as BrowserCallStack, + type BrowserCaptchaChallengeResultEvent as BrowserCaptchaChallengeResultEvent, type BrowserCaptchaSolveResultEvent as BrowserCaptchaSolveResultEvent, + type BrowserCaptchaSolveStartedEvent as BrowserCaptchaSolveStartedEvent, type BrowserCdpCommandEvent as BrowserCdpCommandEvent, type BrowserCdpCommandMethod as BrowserCdpCommandMethod, type BrowserCdpConnectEvent as BrowserCdpConnectEvent, diff --git a/src/resources/browsers/index.ts b/src/resources/browsers/index.ts index 7bd92100..2b225829 100644 --- a/src/resources/browsers/index.ts +++ b/src/resources/browsers/index.ts @@ -90,7 +90,9 @@ export { Telemetry, type BrowserAPICallEvent, type BrowserCallStack, + type BrowserCaptchaChallengeResultEvent, type BrowserCaptchaSolveResultEvent, + type BrowserCaptchaSolveStartedEvent, type BrowserCdpCommandEvent, type BrowserCdpCommandMethod, type BrowserCdpConnectEvent, diff --git a/src/resources/browsers/telemetry.ts b/src/resources/browsers/telemetry.ts index 609a11dd..c785e171 100644 --- a/src/resources/browsers/telemetry.ts +++ b/src/resources/browsers/telemetry.ts @@ -192,6 +192,99 @@ export namespace BrowserCallStack { } } +/** + * A visible captcha challenge reached a terminal outcome. + */ +export interface BrowserCaptchaChallengeResultEvent { + category: 'captcha'; + + /** + * Per-challenge payload. This event is emitted once per challenge and determines + * its overall outcome; captcha_solve_started and captcha_solve_result describe + * individual tasks and may occur multiple times within the challenge. + */ + data: BrowserCaptchaChallengeResultEvent.Data; + + /** + * Provenance metadata identifying which producer emitted the event. + */ + source: BrowserEventSource; + + /** + * Event timestamp in Unix microseconds. + */ + ts: number; + + type: 'captcha_challenge_result'; + + /** + * True if the data field was truncated due to size limits. + */ + truncated?: boolean; +} + +export namespace BrowserCaptchaChallengeResultEvent { + /** + * Per-challenge payload. This event is emitted once per challenge and determines + * its overall outcome; captcha_solve_started and captcha_solve_result describe + * individual tasks and may occur multiple times within the challenge. + */ + export interface Data { + /** + * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version + * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use + * press_and_hold, and unlisted kinds use other. + */ + captcha_type: + | 'hcaptcha' + | 'recaptcha_v2' + | 'recaptcha_v3' + | 'turnstile' + | 'geetest' + | 'press_and_hold' + | 'other'; + + /** + * Opaque identifier shared by events for one visible challenge. An image-grid + * captcha may create multiple task_id values for one challenge_id. The same value + * may continue across a page reload when the challenge episode continues. It does + * not indicate task ordering or challenge completion. + */ + challenge_id: string; + + /** + * Wall-clock duration from the challenge appearing to its terminal outcome, + * covering every solver attempt in between. + */ + duration_ms: number; + + /** + * Terminal outcome of the visible challenge. solved: the page observed the + * challenge clear after a solver attempt. failure: a terminal solver failure + * occurred, or all attempts ended while the challenge remained. timeout: the + * challenge-level wait budget expired while the challenge remained. abandoned: + * observation ended without an attributable terminal challenge outcome. This + * includes a dismissed widget or page unload without a solved signal or terminal + * solver outcome, and a token appearing while multiple same-provider challenges + * are open, because the producer cannot attribute that token to this visible + * challenge. A captcha_solve_result with the same challenge_id may therefore + * report success while the challenge result reports abandoned. A solved challenge + * does not prove the site accepted the token or that the guarded action succeeded. + */ + status: 'solved' | 'failure' | 'timeout' | 'abandoned'; + + /** + * Host of the page where the challenge appeared. + */ + website_host?: string; + + /** + * Path of the page where the challenge appeared. Query string excluded. + */ + website_path?: string; + } +} + /** * A captcha solve attempt reached a terminal outcome. */ @@ -221,13 +314,23 @@ export interface BrowserCaptchaSolveResultEvent { export namespace BrowserCaptchaSolveResultEvent { export interface Data { /** - * Captcha vendor family. Provider-specific task names are normalized into this - * set; anything not covered is reported as other. - */ - captcha_type: 'hcaptcha' | 'recaptcha_v2' | 'recaptcha_v3' | 'turnstile' | 'geetest' | 'other'; + * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version + * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use + * press_and_hold, and unlisted kinds use other. + */ + captcha_type: + | 'hcaptcha' + | 'recaptcha_v2' + | 'recaptcha_v3' + | 'turnstile' + | 'geetest' + | 'press_and_hold' + | 'other'; /** - * Wall-clock duration from solve start to terminal outcome. + * Wall-clock duration from solve start to terminal outcome. Authoritative solve + * timing; do not derive it from the gap to a captcha_solve_started event, whose + * delivery and ordering are not guaranteed. */ duration_ms: number; @@ -239,6 +342,14 @@ export namespace BrowserCaptchaSolveResultEvent { */ status: 'success' | 'failure' | 'timeout' | 'abandoned'; + /** + * Opaque identifier shared by events for one visible challenge. An image-grid + * captcha may create multiple task_id values for one challenge_id. The same value + * may continue across a page reload when the challenge episode continues. It does + * not indicate task ordering or challenge completion. + */ + challenge_id?: string; + /** * Solver-specific error code on failure (e.g. ERROR_CAPTCHA_UNSOLVABLE). Absent on * success. @@ -246,7 +357,7 @@ export namespace BrowserCaptchaSolveResultEvent { error_code?: string; /** - * Solver-assigned identifier. Opaque, useful for support cross-references. + * Opaque identifier shared with the matching captcha_solve_started. */ task_id?: string; @@ -262,6 +373,86 @@ export namespace BrowserCaptchaSolveResultEvent { } } +/** + * A captcha solver accepted a task. + */ +export interface BrowserCaptchaSolveStartedEvent { + category: 'captcha'; + + /** + * Per-task payload. A visible challenge may create multiple tasks. When present, + * task_id correlates this event with a captcha_solve_result, while challenge_id + * groups tasks from the same challenge. Events may arrive out of order or be + * absent, so their arrival does not indicate current solve state. + */ + data: BrowserCaptchaSolveStartedEvent.Data; + + /** + * Provenance metadata identifying which producer emitted the event. + */ + source: BrowserEventSource; + + /** + * Event timestamp in Unix microseconds. + */ + ts: number; + + type: 'captcha_solve_started'; + + /** + * True if the data field was truncated due to size limits. + */ + truncated?: boolean; +} + +export namespace BrowserCaptchaSolveStartedEvent { + /** + * Per-task payload. A visible challenge may create multiple tasks. When present, + * task_id correlates this event with a captcha_solve_result, while challenge_id + * groups tasks from the same challenge. Events may arrive out of order or be + * absent, so their arrival does not indicate current solve state. + */ + export interface Data { + /** + * Captcha kind. Enterprise reCAPTCHA variants are grouped into their version + * bucket (recaptcha_v2 or recaptcha_v3), press-and-hold challenges use + * press_and_hold, and unlisted kinds use other. + */ + captcha_type: + | 'hcaptcha' + | 'recaptcha_v2' + | 'recaptcha_v3' + | 'turnstile' + | 'geetest' + | 'press_and_hold' + | 'other'; + + /** + * Opaque identifier shared by events for one visible challenge. An image-grid + * captcha may create multiple task_id values for one challenge_id. The same value + * may continue across a page reload when the challenge episode continues. It does + * not indicate task ordering or challenge completion. + */ + challenge_id?: string; + + /** + * Opaque identifier shared with the matching captcha_solve_result. + */ + task_id?: string; + + /** + * Host of the page where the captcha is being solved. May be empty for solver + * tasks that carry no page URL. + */ + website_host?: string; + + /** + * Path of the page where the captcha is being solved. Query string excluded. + */ + website_path?: string; + } +} + /** * A browser-control command a client sent over the CDP WebSocket proxy: input * gestures, navigation, dialog handling, file selection and screenshots. @@ -4346,7 +4537,7 @@ export namespace BrowserSystemOomKillEvent { */ export interface BrowserTelemetryCategoriesConfig { /** - * Captcha solve attempt outcomes. On by default. + * Captcha solver tasks and visible challenge outcomes. On by default. */ captcha?: BrowserTelemetryCategoryConfig; @@ -4516,7 +4707,9 @@ export type BrowserTelemetryEvent = | BrowserCdpDisconnectEvent | BrowserLiveViewConnectEvent | BrowserLiveViewDisconnectEvent + | BrowserCaptchaSolveStartedEvent | BrowserCaptchaSolveResultEvent + | BrowserCaptchaChallengeResultEvent | BrowserSystemOomKillEvent | BrowserServiceCrashedEvent; @@ -4660,7 +4853,9 @@ export declare namespace Telemetry { export { type BrowserAPICallEvent as BrowserAPICallEvent, type BrowserCallStack as BrowserCallStack, + type BrowserCaptchaChallengeResultEvent as BrowserCaptchaChallengeResultEvent, type BrowserCaptchaSolveResultEvent as BrowserCaptchaSolveResultEvent, + type BrowserCaptchaSolveStartedEvent as BrowserCaptchaSolveStartedEvent, type BrowserCdpCommandEvent as BrowserCdpCommandEvent, type BrowserCdpCommandMethod as BrowserCdpCommandMethod, type BrowserCdpConnectEvent as BrowserCdpConnectEvent, From adf976e1e76d6f9ae6a043f91d1da671a944d8d6 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Mon, 31 Aug 2026 00:41:27 +0000 Subject: [PATCH 2/3] feat: Unify managed auth reauth eligibility and blockers Stainless-Generated-From: 2e918c1fb037bbdb765dbd2f4d54eb6a97d29fda --- src/resources/auth/connections.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/resources/auth/connections.ts b/src/resources/auth/connections.ts index e50b5bc6..78f603a5 100644 --- a/src/resources/auth/connections.ts +++ b/src/resources/auth/connections.ts @@ -332,8 +332,10 @@ export interface ManagedAuth { * - `viable_plans_found` — at least one stored login plan can be replayed * - `no_requirements_recorded` — no recorded credential requirements to fail * against - * - `requirements_satisfiable` — recorded requirements can be met by the attached - * credential + * - `totp_reauth_allowed` — TOTP is the only recorded requirement and is safe to + * attempt automatically + * - `requirements_satisfiable` — recorded requirements contain no recognized + * blocker * * Negative values (a human must complete the login flow): * @@ -360,6 +362,7 @@ export interface ManagedAuth { | 'has_credential' | 'viable_plans_found' | 'no_requirements_recorded' + | 'totp_reauth_allowed' | 'requirements_satisfiable' | 'no_prior_successful_login' | 'no_credential' From 1bc65331ba8fa8042f46ce8d935c9a61cc9c7016 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Mon, 31 Aug 2026 00:45:50 +0000 Subject: [PATCH 3/3] release: 0.97.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 6b5b821b..29c16586 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.96.0" + ".": "0.97.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index a505c178..a1dfbe95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [0.97.0](https://github.com/kernel/kernel-node-sdk/compare/v0.96.0...v0.97.0) (2026-08-31) + + +### Features + +* Expose captcha task and challenge outcomes ([66f6eaf](https://github.com/kernel/kernel-node-sdk/commit/66f6eaf26d7bdee5311b0a2a66c4806e319872a8)) +* Unify managed auth reauth eligibility and blockers ([adf976e](https://github.com/kernel/kernel-node-sdk/commit/adf976e1e76d6f9ae6a043f91d1da671a944d8d6)) + ## [0.96.0](https://github.com/kernel/kernel-node-sdk/compare/v0.95.0...v0.96.0) (2026-08-27) diff --git a/package.json b/package.json index 9e7f9a1b..9b0d183b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@onkernel/sdk", - "version": "0.96.0", + "version": "0.97.0", "description": "The official TypeScript library for the Kernel API", "author": "Kernel <>", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index b75d8d52..1b7c9366 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.96.0'; // x-release-please-version +export const VERSION = '0.97.0'; // x-release-please-version