captchakraken 2.3.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/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Hosted-API refusals, carried across the Python subprocess boundary.
+ *
+ * The TypeScript driver does not talk to the model; it shells out to the Python
+ * CLI, which does. So every hosted-API error arrives here as text on stderr and
+ * would, without this, be flattened into
+ * `Failed to execute captcha solver CLI: Command failed with exit code 3` —
+ * a sentence that tells a camoufox user nothing about the fact that their
+ * account is out of credits.
+ *
+ * The CLI exits 3 and prints `{"error": "...", "ck_error": {...}}`, so the
+ * wording is decided once, in Python (`captchakraken/errors.py`), and merely
+ * relayed here. Deliberately NOT re-worded on this side: two copies of the same
+ * message drift, and the Python one is also what a direct CLI user sees.
+ */
+/** The machine-readable half. Mirrors the gateway's `GatewayErrorCode`. */
+export type CaptchaKrakenErrorCode = 'missing_api_key' | 'invalid_api_key' | 'account_suspended' | 'insufficient_credits' | 'rate_limited' | 'solve_abandoned' | 'unrecognized_prompt' | 'invalid_request' | 'request_too_large' | 'upstream_unavailable' | (string & {});
+export declare class CaptchaKrakenAPIError extends Error {
+    readonly status: number | undefined;
+    readonly code: CaptchaKrakenErrorCode | undefined;
+    /** Where to send the user to fix it, when the server named somewhere. */
+    readonly resolutionUrl: string | undefined;
+    /** Seconds to wait, on `rate_limited`. */
+    readonly retryAfterSeconds: number | undefined;
+    /** Lets `catch` blocks branch without `instanceof` across module copies. */
+    readonly isCaptchaKrakenAPIError = true;
+    constructor(message: string, fields?: {
+        status?: number;
+        code?: string;
+        resolutionUrl?: string;
+        retryAfterSeconds?: number;
+    });
+}
+/**
+ * Pull a hosted-API error out of the CLI's stderr, or return null.
+ *
+ * Scans line by line rather than parsing the whole buffer: stderr also carries
+ * timing records and any warning the Python side emitted, so the JSON payload
+ * is one line among several and `JSON.parse(stderr)` would simply fail.
+ *
+ * Returns null for anything that is not recognisably ours, which leaves the
+ * caller's existing generic handling in place — an unparseable stderr must not
+ * become a confident but wrong billing message.
+ */
+export declare function parseApiError(stderr: string): CaptchaKrakenAPIError | null;

package/dist/errors.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Hosted-API refusals, carried across the Python subprocess boundary.
+ *
+ * The TypeScript driver does not talk to the model; it shells out to the Python
+ * CLI, which does. So every hosted-API error arrives here as text on stderr and
+ * would, without this, be flattened into
+ * `Failed to execute captcha solver CLI: Command failed with exit code 3` —
+ * a sentence that tells a camoufox user nothing about the fact that their
+ * account is out of credits.
+ *
+ * The CLI exits 3 and prints `{"error": "...", "ck_error": {...}}`, so the
+ * wording is decided once, in Python (`captchakraken/errors.py`), and merely
+ * relayed here. Deliberately NOT re-worded on this side: two copies of the same
+ * message drift, and the Python one is also what a direct CLI user sees.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptchaKrakenAPIError = void 0;
+exports.parseApiError = parseApiError;
+class CaptchaKrakenAPIError extends Error {
+    constructor(message, fields = {}) {
+        super(message);
+        /** Lets `catch` blocks branch without `instanceof` across module copies. */
+        this.isCaptchaKrakenAPIError = true;
+        this.name = 'CaptchaKrakenAPIError';
+        this.status = fields.status;
+        this.code = fields.code;
+        this.resolutionUrl = fields.resolutionUrl;
+        this.retryAfterSeconds = fields.retryAfterSeconds;
+    }
+}
+exports.CaptchaKrakenAPIError = CaptchaKrakenAPIError;
+/**
+ * Pull a hosted-API error out of the CLI's stderr, or return null.
+ *
+ * Scans line by line rather than parsing the whole buffer: stderr also carries
+ * timing records and any warning the Python side emitted, so the JSON payload
+ * is one line among several and `JSON.parse(stderr)` would simply fail.
+ *
+ * Returns null for anything that is not recognisably ours, which leaves the
+ * caller's existing generic handling in place — an unparseable stderr must not
+ * become a confident but wrong billing message.
+ */
+function parseApiError(stderr) {
+    if (!stderr || !stderr.includes('ck_error'))
+        return null;
+    for (const line of stderr.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{') || !trimmed.includes('ck_error'))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const details = parsed?.ck_error;
+        if (!details || typeof details !== 'object')
+            continue;
+        const message = typeof parsed.error === 'string' && parsed.error.trim()
+            ? parsed.error
+            : 'CaptchaKraken refused this solve.';
+        return new CaptchaKrakenAPIError(message, {
+            status: typeof details.status === 'number' ? details.status : undefined,
+            code: typeof details.code === 'string' ? details.code : undefined,
+            resolutionUrl: typeof details.resolution_url === 'string' ? details.resolution_url : undefined,
+            retryAfterSeconds: typeof details.retry_after_seconds === 'number'
+                ? details.retry_after_seconds
+                : undefined,
+        });
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -1,5 +1,38 @@
 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.
+ *
+ * `message` is already a complete sentence naming the product and, where one
+ * exists, the URL that fixes it, so printing it is enough. `code` is the stable
+ * contract to branch on; the prose is not.
+ *
+ * @example
+ * ```typescript
+ * import { CaptchaKrakenSolver, CaptchaKrakenAPIError } from 'captchakraken';
+ *
+ * try {
+ *   await solver.solve(page);
+ * } catch (e) {
+ *   if (e instanceof CaptchaKrakenAPIError && e.code === 'insufficient_credits') {
+ *     console.error(`Top up: ${e.resolutionUrl}`);
+ *   } else throw e;
+ * }
+ * ```
+ */
+export { CaptchaKrakenAPIError } from './errors';
+export type { CaptchaKrakenErrorCode } from './errors';
 /**
  * Adapter for driving the solver with **Puppeteer** instead of a Playwright
  * launcher. Puppeteer's `Page` is API-compatible with Playwright's except for a
@@ -54,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,44 @@ 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.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.
+ *
+ * `message` is already a complete sentence naming the product and, where one
+ * exists, the URL that fixes it, so printing it is enough. `code` is the stable
+ * contract to branch on; the prose is not.
+ *
+ * @example
+ * ```typescript
+ * import { CaptchaKrakenSolver, CaptchaKrakenAPIError } from 'captchakraken';
+ *
+ * try {
+ *   await solver.solve(page);
+ * } catch (e) {
+ *   if (e instanceof CaptchaKrakenAPIError && e.code === 'insufficient_credits') {
+ *     console.error(`Top up: ${e.resolutionUrl}`);
+ *   } else throw e;
+ * }
+ * ```
+ */
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "CaptchaKrakenAPIError", { enumerable: true, get: function () { return errors_1.CaptchaKrakenAPIError; } });
 /**
  * Adapter for driving the solver with **Puppeteer** instead of a Playwright
  * launcher. Puppeteer's `Page` is API-compatible with Playwright's except for a
@@ -41,3 +75,20 @@ Object.defineProperty(exports, "CaptchaKrakenSolver", { enumerable: true, get: f
  */
 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;