captchakraken 2.4.0 → 2.6.0

package/LICENSE

@@ -1,5 +1,5 @@
-CaptchaKraken Source-Available License v1.0
-Copyright (c) 2026 JobHarvest / JWriter20. All rights reserved.
+CaptchaKraken Source-Available License v1.1
+Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
 
 This license governs use of the CaptchaKraken software in this repository and of
 the associated machine-learning model weights and LoRA adapters published by the
@@ -26,12 +26,17 @@ You MAY use the Software for:
 
   Illustrative (non-exhaustive) examples of PERMITTED commercial use:
       - Web scrapers and data-collection pipelines.
-      - Stealth / anti-detection browsers and browser automation frameworks
-        that use the Software as one internal capability.
+      - Browser automation you build and operate for your own purposes.
       - QA, testing, and accessibility tooling.
       - Any application where the captcha solve is a means to an end the user
         is actually paying for.
 
+  (c) RUNNING the Software alongside a stealth, anti-detection, or antidetect
+      browser — Camoufox, Puppeteer, Playwright, or any similar tool — to
+      automate your own work, commercially or otherwise. Section 3(d) restricts
+      SHIPPING the Software as a feature of such a browser to other people. It
+      does not restrict USING it with one.
+
 ================================================================================
 3. PROHIBITED USES
 ================================================================================
@@ -51,7 +56,23 @@ holder:
       models (e.g. bounding boxes, tile selections, click plans) through a paid
       or public API as a captcha-solving service.
 
-  In short: you may BUILD WITH this Software, but you may not SELL THE SOLVE.
+  (d) Embed, bundle, preinstall, or otherwise ship the Software — or a client,
+      wrapper, plugin, or extension for it — as a captcha-solving capability of
+      any stealth browser, anti-detection or antidetect browser, browser
+      profile or identity manager, or browser-automation product or platform
+      that you distribute, host, or otherwise offer to third parties. This
+      applies whether the Software ships inside your distribution, is fetched
+      on demand, or is merely wired up and advertised as a supported
+      integration, and it applies whether or not you charge for it.
+
+      This restriction is about DISTRIBUTION, not use. Nothing in it limits
+      Section 2(c): a person who uses such a browser may install and run the
+      Software with it freely.
+
+  In short: you may BUILD WITH this Software, and you may USE it with whatever
+  browser you like — but you may not SELL THE SOLVE, and you may not SHIP THE
+  SOLVE as a feature of a stealth browser or automation product you hand to
+  other people.
 
 ================================================================================
 4. MODEL OUTPUTS
@@ -65,6 +86,7 @@ outputs as a captcha-solving service is prohibited under Section 3(c).
 ================================================================================
 If you redistribute the Software (modified or not), you must retain this license
 and this notice, and you must not remove or alter the restrictions in Section 3.
+The right to redistribute granted by Section 1 is subject to Section 3(d).
 
 ================================================================================
 6. TRADEMARKS
@@ -95,11 +117,29 @@ not endorse using the Software to violate any third party's terms or rights.
 9. COMMERCIAL LICENSING
 ================================================================================
 For uses prohibited under Section 3 — including selling captcha-solving as a
-service — contact the copyright holder to discuss a separate commercial license.
+service, and shipping the Software as a built-in capability of a stealth browser
+or automation product — contact the copyright holder to discuss a separate
+commercial license. These uses are licensable; they are not categorically
+refused.
+
+================================================================================
+10. VERSION HISTORY
+================================================================================
+v1.1 — Section 3(d) added: shipping the Software as a captcha-solving feature of
+       a stealth/anti-detection browser or automation product distributed to
+       third parties now requires a commercial license. Section 2(c) added to
+       make clear that USING the Software with such a browser remains permitted.
+       The v1.0 text listed "stealth / anti-detection browsers" as an
+       illustrative PERMITTED commercial use; that example is removed.
+v1.0 — Initial release.
+
+Each version applies to the releases distributed under it. Copies obtained under
+v1.0 remain governed by v1.0.
 
 --------------------------------------------------------------------------------
 This text is a license, not legal advice. If the boundary between a permitted
-"value-add" product and a prohibited "thin wrapper" is unclear for your use
+"value-add" product and a prohibited "thin wrapper", or between using the
+Software with a browser and shipping it as part of one, is unclear for your use
 case, ask by opening an issue or messaging the maintainer on GitHub:
 https://github.com/JWriter20/CaptchaKraken
 --------------------------------------------------------------------------------

package/README.md

@@ -23,6 +23,20 @@ Playwright-compatible launcher.
 - To **self-host** the model, run the repo's `setup.sh` (installs vLLM + weights).
   Otherwise point `VLLM_BASE_URL` at a server you already run.
 
+## No GPU? Use the hosted API
+
+Point the client at `https://api.captchakraken.com/v1` and run no model at all.
+Sign in at [captchakraken.com/signin](https://captchakraken.com/signin) for a
+`ck_live_…` key, or let the MCP server write one for you:
+
+```bash
+claude mcp add captchakraken -- npx -y captchakraken-mcp
+# then call sign_in, then create_api_key
+```
+
+`create_api_key` writes the key and the endpoint to `~/.captchakraken/credentials`,
+which the client reads on its own — **no environment variables needed**.
+
 ## Usage
 
 ```typescript
@@ -46,11 +60,17 @@ Puppeteer users wrap the page once with `fromPuppeteer(page)`.
 
 | Variable | Meaning |
 |---|---|
-| `VLLM_BASE_URL` | Inference endpoint (local vLLM, or a server you run) |
+| `VLLM_BASE_URL` | Inference endpoint (local vLLM, a server you run, or `https://api.captchakraken.com/v1`) |
 | `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) |
 
+Both fall back to `~/.captchakraken/credentials` when unset, so the hosted API
+needs no environment variables at all.
+
 ## License
 
-**CaptchaKraken Source-Available License v1.0** — see [LICENSE](./LICENSE).
-Build *with* it (scrapers, stealth browsers, QA tooling); you may **not sell the
-solve itself** or ship a thin wrapper (browser extension, hosted solving API).
+**CaptchaKraken Source-Available License v1.1** — see [LICENSE](./LICENSE).
+Build *with* it (scrapers, QA tooling) and run it against **any** browser you
+like, stealth or not. You may **not sell the solve itself**, ship a thin wrapper
+(browser extension, hosted solving API), or **bundle it as a built-in feature of
+a stealth/antidetect browser you distribute** — using it with one is fine. Those
+three are licensable, not categorically refused: open an issue to ask.

package/dist/cli-invocation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * How the JS client hands a solve request to the bundled Python CLI.
+ *
+ * The API key used to travel as a POSITIONAL ARGUMENT, and the whole command
+ * line was then echoed:
+ *
+ *   console.log(`Executing CaptchaKraken CLI: ${command}`);
+ *   // Executing CaptchaKraken CLI: python -m captchakraken.cli "shot.png" \
+ *   //   captcha-v12 captchaKrakenApi b8978fa3392...  --puzzle-source=hcaptcha
+ *
+ * Two leaks from one mistake. Argv is world-readable on Linux — any local user
+ * can read `/proc/<pid>/cmdline` while the solve runs, and `ps` shows it — and
+ * the key was additionally written to stdout, so it landed in CI logs, terminal
+ * scrollback, and anything scraping driver output.
+ *
+ * Secrets go through the environment instead, which is per-process and not
+ * world-readable, and the command is built as an ARGV ARRAY for `execFile`
+ * rather than a joined string for a shell, so a path with a space or a quote
+ * cannot reshape the command.
+ */
+/** Env var the CLI reads the bearer token from. */
+export declare const API_KEY_ENV = "CAPTCHA_KRAKEN_API_KEY";
+/** Historical positional placeholder. The CLI still accepts the slot. */
+export declare const API_PROVIDER = "captchaKrakenApi";
+export interface SolveInvocation {
+    imagePath: string;
+    model: string;
+    puzzleSource: string;
+    retryMode?: string | null;
+    textMode?: boolean;
+}
+/**
+ * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
+ * supplied by `solveEnv` instead.
+ */
+export declare function buildSolveArgs(invocation: SolveInvocation): string[];
+/** Base env plus the credential, when there is one. */
+export declare function solveEnv(base: NodeJS.ProcessEnv, apiKey?: string): NodeJS.ProcessEnv;
+/**
+ * A log line for a solve invocation, with any credential removed.
+ *
+ * Belt and braces: `buildSolveArgs` no longer carries the key, but this is the
+ * function that prints to stdout, so it redacts anything key-shaped regardless
+ * of how it got into the array.
+ */
+export declare function redactCommand(command: string, apiKey?: string): string;

package/dist/cli-invocation.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * How the JS client hands a solve request to the bundled Python CLI.
+ *
+ * The API key used to travel as a POSITIONAL ARGUMENT, and the whole command
+ * line was then echoed:
+ *
+ *   console.log(`Executing CaptchaKraken CLI: ${command}`);
+ *   // Executing CaptchaKraken CLI: python -m captchakraken.cli "shot.png" \
+ *   //   captcha-v12 captchaKrakenApi b8978fa3392...  --puzzle-source=hcaptcha
+ *
+ * Two leaks from one mistake. Argv is world-readable on Linux — any local user
+ * can read `/proc/<pid>/cmdline` while the solve runs, and `ps` shows it — and
+ * the key was additionally written to stdout, so it landed in CI logs, terminal
+ * scrollback, and anything scraping driver output.
+ *
+ * Secrets go through the environment instead, which is per-process and not
+ * world-readable, and the command is built as an ARGV ARRAY for `execFile`
+ * rather than a joined string for a shell, so a path with a space or a quote
+ * cannot reshape the command.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_PROVIDER = exports.API_KEY_ENV = void 0;
+exports.buildSolveArgs = buildSolveArgs;
+exports.solveEnv = solveEnv;
+exports.redactCommand = redactCommand;
+/** Env var the CLI reads the bearer token from. */
+exports.API_KEY_ENV = 'CAPTCHA_KRAKEN_API_KEY';
+/** Historical positional placeholder. The CLI still accepts the slot. */
+exports.API_PROVIDER = 'captchaKrakenApi';
+/**
+ * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
+ * supplied by `solveEnv` instead.
+ */
+function buildSolveArgs(invocation) {
+    const { imagePath, model, puzzleSource, retryMode, textMode } = invocation;
+    const args = [
+        '-m',
+        'captchakraken.cli',
+        imagePath,
+        model,
+        exports.API_PROVIDER,
+        `--puzzle-source=${puzzleSource}`,
+    ];
+    if (retryMode)
+        args.push(`--retry-mode=${retryMode}`);
+    if (textMode)
+        args.push('--text-mode');
+    return args;
+}
+/** Base env plus the credential, when there is one. */
+function solveEnv(base, apiKey) {
+    if (!apiKey)
+        return base;
+    return { ...base, [exports.API_KEY_ENV]: apiKey };
+}
+/**
+ * A log line for a solve invocation, with any credential removed.
+ *
+ * Belt and braces: `buildSolveArgs` no longer carries the key, but this is the
+ * function that prints to stdout, so it redacts anything key-shaped regardless
+ * of how it got into the array.
+ */
+function redactCommand(command, apiKey) {
+    if (!apiKey)
+        return command;
+    return command.split(apiKey).join('***');
+}

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 export * from './types';
 export { CaptchaKrakenSolver } from './solver';
+/**
+ * The served LoRA name this client will ask for when `model` is left unset —
+ * `CAPTCHA_LORA_NAME`, else `models.json`'s `latest`, else the shipped pin.
+ *
+ * Exported so anything that REPORTS which adapter was driven can ask the client
+ * instead of re-deriving the answer. That distinction is not cosmetic: the name
+ * selects the prompt generation, so a reporter that guesses it can disagree with
+ * the solver and describe a run that never happened.
+ */
+export { resolveLoraName } from './model-name';
 /**
  * Errors raised when the **hosted** CaptchaKraken API refuses a solve — out of
  * credits, rate limited, key rejected, attempt abandoned.
@@ -77,3 +87,20 @@ export { fromPuppeteer } from './puppeteer-adapter';
  * ```
  */
 export type { Page, PlaywrightPage, PlaywrightFrame, PlaywrightElementHandle } from './playwright-types';
+/**
+ * Auto-solve watcher: `solver.watch(page)` installs a background poller that
+ * solves captchas as they appear, and returns a handle with `stop()`.
+ *
+ * Injects nothing into the page, on any platform — see watcher.ts. On Camoufox
+ * its DOM reads run in the isolated Juggler world by default.
+ *
+ * @example
+ * ```typescript
+ * const solver = new CaptchaKrakenSolver();
+ * const watcher = solver.watch(page, { onSolved: r => console.log(r.isSolved) });
+ * // ... your automation ...
+ * await watcher.stop();
+ * ```
+ */
+export { watchPage } from './watcher';
+export type { CaptchaWatcher, WatchOptions, WatchableSolver } from './watcher';

package/dist/index.js

@@ -14,10 +14,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromPuppeteer = exports.CaptchaKrakenAPIError = exports.CaptchaKrakenSolver = void 0;
+exports.watchPage = exports.fromPuppeteer = exports.CaptchaKrakenAPIError = exports.resolveLoraName = exports.CaptchaKrakenSolver = void 0;
 __exportStar(require("./types"), exports);
 var solver_1 = require("./solver");
 Object.defineProperty(exports, "CaptchaKrakenSolver", { enumerable: true, get: function () { return solver_1.CaptchaKrakenSolver; } });
+/**
+ * The served LoRA name this client will ask for when `model` is left unset —
+ * `CAPTCHA_LORA_NAME`, else `models.json`'s `latest`, else the shipped pin.
+ *
+ * Exported so anything that REPORTS which adapter was driven can ask the client
+ * instead of re-deriving the answer. That distinction is not cosmetic: the name
+ * selects the prompt generation, so a reporter that guesses it can disagree with
+ * the solver and describe a run that never happened.
+ */
+var model_name_1 = require("./model-name");
+Object.defineProperty(exports, "resolveLoraName", { enumerable: true, get: function () { return model_name_1.resolveLoraName; } });
 /**
  * Errors raised when the **hosted** CaptchaKraken API refuses a solve — out of
  * credits, rate limited, key rejected, attempt abandoned.
@@ -64,3 +75,20 @@ Object.defineProperty(exports, "CaptchaKrakenAPIError", { enumerable: true, get:
  */
 var puppeteer_adapter_1 = require("./puppeteer-adapter");
 Object.defineProperty(exports, "fromPuppeteer", { enumerable: true, get: function () { return puppeteer_adapter_1.fromPuppeteer; } });
+/**
+ * Auto-solve watcher: `solver.watch(page)` installs a background poller that
+ * solves captchas as they appear, and returns a handle with `stop()`.
+ *
+ * Injects nothing into the page, on any platform — see watcher.ts. On Camoufox
+ * its DOM reads run in the isolated Juggler world by default.
+ *
+ * @example
+ * ```typescript
+ * const solver = new CaptchaKrakenSolver();
+ * const watcher = solver.watch(page, { onSolved: r => console.log(r.isSolved) });
+ * // ... your automation ...
+ * await watcher.stop();
+ * ```
+ */
+var watcher_1 = require("./watcher");
+Object.defineProperty(exports, "watchPage", { enumerable: true, get: function () { return watcher_1.watchPage; } });

package/dist/limits.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Numbers that must agree with the hosted gateway, stated once.
+ *
+ * These are not arbitrary defaults. They sit inside an ordering the server
+ * enforces, and the ordering — not any individual value — is the property worth
+ * protecting. `limits.test.ts` pins it.
+ */
+/**
+ * The server bills at most this many responses per captcha attempt.
+ *
+ * Mirrors `MAX_BILLABLE_ROUNDS_PER_SESSION` in captchakraken-gateway's
+ * `src/pricing.ts`. Declared here so the ordering below can be asserted; the
+ * gateway is what actually enforces it.
+ */
+export declare const SERVER_MAX_BILLABLE_ROUNDS = 5;
+/**
+ * The server answers at most this many responses per attempt, then refuses the
+ * eleventh with 409 `solve_abandoned`.
+ *
+ * Mirrors `MAX_ROUNDS_PER_SESSION` in the gateway.
+ */
+export declare const SERVER_MAX_SERVED_ROUNDS = 10;
+/**
+ * How many click → refresh → re-solve rounds the client will attempt on one
+ * reCAPTCHA 3x3 dynamic puzzle.
+ *
+ * ── WHY 8, AND WHY IT MUST STAY STRICTLY BETWEEN 5 AND 10 ───────────────────
+ *
+ * The three numbers describe one attempt in three stages:
+ *
+ *     rounds 1–5     billed
+ *     rounds 6–10    served, and comped
+ *     round 11       refused — 409, the attempt is over
+ *
+ * 8 sits strictly inside that, with room on both sides, and both margins do a
+ * job:
+ *
+ *   Above 5 — rounds 6, 7 and 8 are free. A puzzle that needs a couple of extra
+ *   passes still gets them, and the customer is not charged for our model
+ *   needing another look. Dropping to 5 would abandon winnable puzzles at
+ *   exactly the point where continuing costs the customer nothing.
+ *
+ *   Below 10 — a well-behaved client gives up BEFORE the server refuses it.
+ *   Raising this to 10 or beyond means the normal end of a hard puzzle is a
+ *   409 rather than a clean local stop, which turns an ordinary outcome into an
+ *   error the caller has to interpret.
+ *
+ * So: if the billable cap moves, re-derive this and move the test in the same
+ * commit. Changing one number alone silently breaks one of the two margins.
+ */
+export declare const DEFAULT_RECAPTCHA_MAX_DYNAMIC_ROUNDS = 8;

package/dist/limits.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Numbers that must agree with the hosted gateway, stated once.
+ *
+ * These are not arbitrary defaults. They sit inside an ordering the server
+ * enforces, and the ordering — not any individual value — is the property worth
+ * protecting. `limits.test.ts` pins it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RECAPTCHA_MAX_DYNAMIC_ROUNDS = exports.SERVER_MAX_SERVED_ROUNDS = exports.SERVER_MAX_BILLABLE_ROUNDS = void 0;
+/**
+ * The server bills at most this many responses per captcha attempt.
+ *
+ * Mirrors `MAX_BILLABLE_ROUNDS_PER_SESSION` in captchakraken-gateway's
+ * `src/pricing.ts`. Declared here so the ordering below can be asserted; the
+ * gateway is what actually enforces it.
+ */
+exports.SERVER_MAX_BILLABLE_ROUNDS = 5;
+/**
+ * The server answers at most this many responses per attempt, then refuses the
+ * eleventh with 409 `solve_abandoned`.
+ *
+ * Mirrors `MAX_ROUNDS_PER_SESSION` in the gateway.
+ */
+exports.SERVER_MAX_SERVED_ROUNDS = 10;
+/**
+ * How many click → refresh → re-solve rounds the client will attempt on one
+ * reCAPTCHA 3x3 dynamic puzzle.
+ *
+ * ── WHY 8, AND WHY IT MUST STAY STRICTLY BETWEEN 5 AND 10 ───────────────────
+ *
+ * The three numbers describe one attempt in three stages:
+ *
+ *     rounds 1–5     billed
+ *     rounds 6–10    served, and comped
+ *     round 11       refused — 409, the attempt is over
+ *
+ * 8 sits strictly inside that, with room on both sides, and both margins do a
+ * job:
+ *
+ *   Above 5 — rounds 6, 7 and 8 are free. A puzzle that needs a couple of extra
+ *   passes still gets them, and the customer is not charged for our model
+ *   needing another look. Dropping to 5 would abandon winnable puzzles at
+ *   exactly the point where continuing costs the customer nothing.
+ *
+ *   Below 10 — a well-behaved client gives up BEFORE the server refuses it.
+ *   Raising this to 10 or beyond means the normal end of a hard puzzle is a
+ *   409 rather than a clean local stop, which turns an ordinary outcome into an
+ *   error the caller has to interpret.
+ *
+ * So: if the billable cap moves, re-derive this and move the test in the same
+ * commit. Changing one number alone silently breaks one of the two margins.
+ */
+exports.DEFAULT_RECAPTCHA_MAX_DYNAMIC_ROUNDS = 8;

package/dist/model-name.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where the bundled Python engine lives — the copy of `models.json` this client
+ * actually answers from.
+ *
+ * Lives HERE rather than in solver.ts because the registry lookup below is its
+ * only remaining caller-visible use, and a second copy of this path logic is
+ * how the two ports drifted apart in the first place. solver.ts imports it.
+ *
+ * When installed from npm this file is in `<pkgRoot>/dist` (compiled) or
+ * `<pkgRoot>/src` (dev), and published packages bundle the engine at
+ * `<pkgRoot>/python` (copied in by scripts/copy-python.mjs at build time). In
+ * the source monorepo it instead lives at the sibling `../python`.
+ */
+export declare function getBundledCliRoot(): string;
+/**
+ * `cliRoot` is optional so a caller that only wants to REPORT the name — a test
+ * harness recording which adapter it drove — can ask without reconstructing the
+ * engine's layout. Re-deriving it is the same mistake one level down.
+ */
+export declare function resolveLoraName({ cliRoot, env }?: {
+    cliRoot?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;

package/dist/model-name.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBundledCliRoot = getBundledCliRoot;
+exports.resolveLoraName = resolveLoraName;
+/**
+ * Which served LoRA name this client asks for — the SAME answer the Python
+ * client's `config.lora_name()` gives, and for the same reasons.
+ *
+ * This has to be shared, not re-decided per port. The name is not just routing:
+ * the Python CLI feeds it to `prompts.resolve()`, which maps it through
+ * models.json to a PROMPT GENERATION. A port that picks a different name sends
+ * a different generation of prompts to the same weights, and nothing errors for
+ * any family both generations have a prompt for — it just answers worse. That
+ * is the failure models.json exists to prevent, and the JS port shipped it:
+ * a hardcoded `'captcha'` (CaptchaKraken_v1.1, generation 1) against the
+ * generation-2 adapter `latest` has named since v1.2.
+ *
+ * Precedence mirrors config.py exactly:
+ *   1. CAPTCHA_LORA_NAME — an explicit pin always wins, and pinning is opt-in.
+ *   2. models.json's `latest` entry, so the default model and the default
+ *      prompt generation move forward together and cannot get out of step.
+ *   3. pinned_model.json, so a hand-edited or older manifest still resolves.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Where the bundled Python engine lives — the copy of `models.json` this client
+ * actually answers from.
+ *
+ * Lives HERE rather than in solver.ts because the registry lookup below is its
+ * only remaining caller-visible use, and a second copy of this path logic is
+ * how the two ports drifted apart in the first place. solver.ts imports it.
+ *
+ * When installed from npm this file is in `<pkgRoot>/dist` (compiled) or
+ * `<pkgRoot>/src` (dev), and published packages bundle the engine at
+ * `<pkgRoot>/python` (copied in by scripts/copy-python.mjs at build time). In
+ * the source monorepo it instead lives at the sibling `../python`.
+ */
+function getBundledCliRoot() {
+    const bundled = node_path_1.default.resolve(__dirname, '..', 'python');
+    if (node_fs_1.default.existsSync(bundled))
+        return bundled;
+    return node_path_1.default.resolve(__dirname, '..', '..', 'python');
+}
+function readJson(cliRoot, name) {
+    return JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(cliRoot, 'src', 'captchakraken', name), 'utf-8'));
+}
+/**
+ * `cliRoot` is optional so a caller that only wants to REPORT the name — a test
+ * harness recording which adapter it drove — can ask without reconstructing the
+ * engine's layout. Re-deriving it is the same mistake one level down.
+ */
+function resolveLoraName({ cliRoot = getBundledCliRoot(), env = process.env } = {}) {
+    if (env.CAPTCHA_LORA_NAME)
+        return env.CAPTCHA_LORA_NAME;
+    try {
+        const reg = readJson(cliRoot, 'models.json');
+        const name = reg?.models?.[reg?.latest]?.lora_name;
+        if (typeof name === 'string' && name)
+            return name;
+    }
+    catch {
+        // A missing or broken registry falls through to the pin, never throws —
+        // same contract as config.py's `_registry_default`.
+    }
+    return readJson(cliRoot, 'pinned_model.json').lora_name;
+}

package/dist/playwright-types.d.ts

@@ -59,6 +59,13 @@ export interface PlaywrightElementHandle {
     isVisible(): Promise<boolean>;
     /** The element's text content, or null. */
     textContent(): Promise<string | null>;
+    /**
+     * First matching element WITHIN this element's subtree, or null. The vendors
+     * that render into the host page rather than an iframe (GeeTest, Yidun,
+     * BotDetect, …) have no Frame to scope against, so the widget element is the
+     * boundary that keeps a generic selector off the rest of the document.
+     */
+    $(selector: string): Promise<PlaywrightElementHandle | null>;
 }
 /**
  * Structural subset of Playwright's `Frame` (an iframe's content document).
@@ -96,6 +103,19 @@ export interface PlaywrightPage {
             clickCount?: number;
         }): Promise<void>;
     };
+    /**
+     * Key input. Used to type a distorted-text captcha's answer character by
+     * character — `fill()` would set the value with no keystrokes at all, and
+     * these are the vendors that score typing cadence.
+     */
+    keyboard: {
+        type(text: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+        press(key: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+    };
     /** Sleep `timeout` ms (Playwright's own timer). */
     waitForTimeout(timeout: number): Promise<void>;
     /** Wait for a selector to reach the given state; resolves to the handle (or null). */
@@ -109,6 +129,14 @@ export interface PlaywrightPage {
     $(selector: string): Promise<PlaywrightElementHandle | null>;
     /** All matching element handles. */
     $$(selector: string): Promise<PlaywrightElementHandle[]>;
+    /**
+     * Whether the page has been closed. OPTIONAL because it is the one member
+     * here the solver itself never needs — the auto-solve watcher uses it to end
+     * its loop when the caller closes the browser out from under it, and falls
+     * back to treating the page as open when a launcher does not expose it.
+     * Playwright and Puppeteer both do.
+     */
+    isClosed?(): boolean;
     /** Run `pageFunction` against the first matching element, in the page context. */
     $eval<R>(selector: string, pageFunction: (element: Element) => R, arg?: any): Promise<R>;
 }

package/dist/puppeteer-adapter.d.ts

@@ -14,6 +14,7 @@
  *   - `handle.getAttribute(name)`      → `handle.evaluate((el,n)=>el.getAttribute(n), name)`
  *   - `handle.textContent()`           → `handle.evaluate(el=>el.textContent)`
  *   - `handle.scrollIntoViewIfNeeded()`→ `handle.scrollIntoView()`
+ *   - `page.isClosed()`                → same, but must be forwarded explicitly
  * Everything else (`$`, `$$`, `$eval`, `waitForFunction`, `mouse.*`,
  * `screenshot({path})`, `boundingBox`, `contentFrame`, `isVisible`) is
  * call-compatible and passed straight through.
@@ -42,6 +43,7 @@ interface PuppeteerElementHandle {
     scrollIntoView(): Promise<void>;
     isVisible(): Promise<boolean>;
     evaluate(pageFunction: (el: any, ...args: any[]) => any, ...args: any[]): Promise<any>;
+    $(selector: string): Promise<PuppeteerElementHandle | null>;
 }
 interface PuppeteerFrame {
     $(selector: string): Promise<PuppeteerElementHandle | null>;
@@ -56,11 +58,20 @@ interface PuppeteerPage {
         down(options?: any): Promise<void>;
         up(options?: any): Promise<void>;
     };
+    keyboard: {
+        type(text: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+        press(key: string, options?: any): Promise<void>;
+        down(key: string, options?: any): Promise<void>;
+        up(key: string): Promise<void>;
+    };
     waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
     viewport(): ViewportSize | null;
     $(selector: string): Promise<PuppeteerElementHandle | null>;
     $$(selector: string): Promise<PuppeteerElementHandle[]>;
     $eval(selector: string, pageFunction: (element: Element) => any, ...args: any[]): Promise<any>;
+    isClosed(): boolean;
 }
 /**
  * Wrap a Puppeteer `Page` so it satisfies the solver's structural Playwright