captchakraken 2.3.0 → 2.4.0

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,28 @@
 export * from './types';
 export { CaptchaKrakenSolver } from './solver';
+/**
+ * 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

package/dist/index.js

@@ -14,10 +14,33 @@ 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.fromPuppeteer = exports.CaptchaKrakenAPIError = 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; } });
+/**
+ * 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

package/dist/solver.js

@@ -42,6 +42,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const crypto_1 = require("crypto");
 const token_usage_1 = require("./token-usage");
+const errors_1 = require("./errors");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 function getBundledCliRoot() {
@@ -1865,6 +1866,17 @@ class CaptchaKrakenSolver {
                 e.unsupported = true;
                 throw e;
             }
+            // The hosted API refused the solve and said why (out of credits, rate
+            // limited, attempt abandoned…). The CLI exits 3 with the already-worded
+            // sentence plus the machine-readable fields; both are rethrown as-is.
+            //
+            // Wrapping this in "Failed to execute captcha solver CLI: Command failed
+            // …" — which is what happens to every other non-zero exit — would bury a
+            // billing problem under a sentence about a subprocess. camoufox surfaces
+            // whatever we throw, so this is the message its users actually read.
+            const apiError = (0, errors_1.parseApiError)(stderr);
+            if (apiError)
+                throw apiError;
             console.error('Error executing CaptchaKraken CLI:', error);
             if (error.stdout)
                 console.log('CLI stdout on error:', error.stdout);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "captchakraken",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Browser-agnostic Playwright/Puppeteer captcha solver. Detects the captcha, reads the grid with a fine-tuned Qwen3.5-9B vision model on vLLM, and clicks through to a token.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "2.3.0"
+version = "2.4.0"
 description = "Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM."
 readme = "README.md"
 requires-python = ">=3.10"

package/python/src/captchakraken/cli.py

@@ -56,6 +56,7 @@ import os
 import subprocess
 import sys
 
+from .errors import CaptchaKrakenAPIError
 from .solver import CaptchaSolver, UnsupportedCaptchaError
 from .timing import timed
 
@@ -707,6 +708,17 @@ def main():
         # checkboxes. Emit a clean error with no traceback.
         print(json.dumps({"error": str(e), "unsupported": True}), file=sys.stderr)
         sys.exit(2)
+    except CaptchaKrakenAPIError as e:
+        # The hosted API refused us and told us why. That is an answer, not a
+        # crash, so no traceback: a stack trace here buries the one line the
+        # user needs ("out of credits, top up at …") under frames from a module
+        # they have never opened.
+        #
+        # Exit 3, distinct from 1 (genuine failure) and 2 (unsupported puzzle),
+        # and the payload carries the machine-readable fields so the JS driver
+        # can rebuild the error rather than regex it out of prose.
+        print(json.dumps(e.to_payload()), file=sys.stderr)
+        sys.exit(3)
     except Exception as e:
         import traceback
 

package/python/src/captchakraken/config.py

@@ -47,8 +47,31 @@ def pinned() -> Dict[str, Any]:
 
 # ── Inference endpoint ──────────────────────────────────────────────────────
 def base_url() -> str:
-    """OpenAI-compatible endpoint, e.g. http://localhost:8000/v1."""
-    return os.getenv("VLLM_BASE_URL", f"http://localhost:{port()}/v1")
+    """OpenAI-compatible endpoint, e.g. http://localhost:8000/v1.
+
+    Precedence mirrors `api_key()` exactly — env, then the credentials file,
+    then the local default — because the two values are set together and a
+    reader who has learned one ordering should not have to learn a second.
+
+      1. VLLM_BASE_URL. An explicit override always wins; self-hosters and the
+         dev environment depend on this and must not be silently redirected.
+      2. The credentials file. Written by the MCP signup flow alongside the key,
+         so onboarding configures the endpoint in the same step and a hosted
+         user needs no env plumbing at all.
+      3. localhost. Unchanged, and still correct: someone with no credentials
+         file is by definition not a hosted user, so the self-hosted default is
+         the right guess for them.
+
+    The bug this closes: a camoufox user who signed up through the MCP had a
+    valid key and no endpoint, so every solve dialled a local port with nothing
+    behind it and failed with connection-refused — a message that says nothing
+    about the fact that their requests were meant to go to api.captchakraken.com.
+    """
+    return (
+        os.getenv("VLLM_BASE_URL")
+        or _base_url_from_credentials_file()
+        or f"http://localhost:{port()}/v1"
+    )
 
 
 def state_dir() -> Path:
@@ -60,38 +83,83 @@ def credentials_path() -> Path:
     return state_dir() / "credentials"
 
 
-def _key_from_credentials_file() -> str:
-    """Key written by the MCP server's signup flow (or a future `login` command).
+# Names the credentials file may use for each value. Two spellings each, because
+# the file doubles as something a user can `source` — the VLLM_* names are the
+# env vars this module already honours, and the CAPTCHA_KRAKEN_* names are what
+# the product calls them. Accepting both costs nothing and spares anyone the
+# discovery that they picked the wrong one.
+_KEY_NAMES = ("CAPTCHA_KRAKEN_API_KEY", "VLLM_API_KEY")
+_BASE_URL_NAMES = ("CAPTCHA_KRAKEN_BASE_URL", "VLLM_BASE_URL")
+
+
+def _read_credentials_file() -> Dict[str, str]:
+    """Parse the file the MCP server's signup flow writes.
 
     Hosted-API onboarding writes the key to a 0600 file rather than returning it
     through the agent transcript, so it never lands in an LLM context window.
     Reading it here is what lets a solve authenticate with NO env vars set.
 
-    Deliberately tolerant of a bare token, an env-file line, or surrounding
-    quotes: the file is written by a *separate* tool, and a format mismatch here
-    would surface as a baffling 401 rather than an obvious parse error.
-    Returns "" whenever the file is missing, unreadable, or has no usable line.
+    Returns a mapping of recognised name -> value. The special key ``""`` holds a
+    BARE TOKEN — a file containing nothing but `ck_live_…`, which is what the
+    original single-value format was and what a user hand-writing this file is
+    most likely to produce. Dropping that would silently break every existing
+    credentials file, so it is still accepted and still means "the API key".
+
+    Deliberately tolerant of quoting and comments: the file is written by a
+    *separate* tool, and a format mismatch here surfaces as a baffling 401
+    rather than an obvious parse error. Returns {} whenever the file is missing
+    or unreadable — the self-hosted case, which must stay silent.
     """
     try:
         text = credentials_path().read_text(encoding="utf-8")
     except OSError:
-        return ""
+        return {}
 
+    found: Dict[str, str] = {}
     for line in text.splitlines():
         line = line.strip()
         if not line or line.startswith("#"):
             continue
         if "=" in line:
             name, _, value = line.partition("=")
+            name = name.strip()
             # An env-file with unrelated keys must not yield a bogus token.
-            if name.strip() not in {"CAPTCHA_KRAKEN_API_KEY", "VLLM_API_KEY"}:
+            if name not in _KEY_NAMES and name not in _BASE_URL_NAMES:
                 continue
-            line = value.strip()
-        return line.strip("'\"")
+            found.setdefault(name, value.strip().strip("'\""))
+        elif "" not in found:
+            # A bare token. Only the first such line counts; later prose in a
+            # hand-edited file must not overwrite the credential.
+            found[""] = line.strip("'\"")
+
+    return found
 
+
+def _first_present(values: Dict[str, str], names) -> str:
+    """First non-empty value among `names`, in the order given."""
+    for name in names:
+        value = values.get(name, "").strip()
+        if value:
+            return value
     return ""
 
 
+def _key_from_credentials_file() -> str:
+    """The API key from the credentials file, or "" if there isn't one."""
+    values = _read_credentials_file()
+    return _first_present(values, _KEY_NAMES) or values.get("", "").strip()
+
+
+def _base_url_from_credentials_file() -> str:
+    """The endpoint from the credentials file, or "" if it names none.
+
+    A bare-token file deliberately yields nothing here: it carries no endpoint,
+    and inventing the hosted one for it would silently redirect a self-hoster
+    who wrote a token into that file by hand.
+    """
+    return _first_present(_read_credentials_file(), _BASE_URL_NAMES)
+
+
 def api_key() -> str:
     """Bearer token, in precedence order.
 

package/python/src/captchakraken/errors.py

@@ -0,0 +1,195 @@
+"""What the hosted API's refusals mean, in words a user can act on.
+
+The solver talks to an OpenAI-compatible endpoint that may be a local vLLM the
+user started themselves or the hosted CaptchaKraken gateway. Those two fail very
+differently, and until this module existed both were reported the same way:
+`vLLM 402 Payment Required at https://api.captchakraken.com/v1/chat/completions`.
+A camoufox user who has never heard of vLLM, run vLLM, or intended to run vLLM
+would hit that on the day their credits ran out.
+
+Two rules, both inherited from the gateway's own `src/errors.ts`:
+
+ 1. BRANCH ON `error.code`, NEVER ON PROSE. The messages get reworded; the codes
+    are the contract. A client that pattern-matches "Out of credits" breaks the
+    day someone improves the wording.
+
+ 2. AN UNRECOGNISED CODE MUST STILL PRODUCE A USEFUL MESSAGE. There are ten
+    codes today and there will be more. Enumerating them exhaustively here means
+    the eleventh is reported worse than the ten — so the fallback carries the
+    server's own `message` and `resolution_url` through, and only the phrasing
+    is lost.
+
+The self-hosted path is deliberately untouched: a local vLLM does not send this
+envelope, so `from_response` returns a message shaped like the old one and the
+401/403 hint about the bearer token survives. Nobody self-hosting sees a word
+about credits.
+"""
+
+from typing import Any, Dict, Optional
+
+# Where a user with no `resolution_url` in hand should be sent. Only used as a
+# fallback — the server almost always supplies a deep link that is better than
+# this, and when it does we prefer it.
+_DASHBOARD = "https://captchakraken.com/dashboard"
+_SUPPORT = "https://captchakraken.com/support"
+
+
+class CaptchaKrakenAPIError(RuntimeError):
+    """A refusal from the hosted API, already translated.
+
+    Carries the machine-readable parts alongside the message so a caller that
+    wants to react programmatically (retry on `rate_limited`, stop on
+    `insufficient_credits`) can do so without re-parsing anything. `str(e)` is
+    the human sentence and is what reaches a console.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        resolution_url: Optional[str] = None,
+        retry_after_seconds: Optional[float] = None,
+    ):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.resolution_url = resolution_url
+        self.retry_after_seconds = retry_after_seconds
+
+    def to_payload(self) -> Dict[str, Any]:
+        """The shape the CLI puts on stderr for the JS driver to pick up.
+
+        The JS half shells out to this CLI and can only see stdout/stderr, so
+        the structured fields would otherwise be flattened to a string at the
+        process boundary and have to be re-parsed out of prose — exactly the
+        thing rule 1 forbids.
+        """
+        return {
+            "error": str(self),
+            "ck_error": {
+                "status": self.status,
+                "code": self.code,
+                "resolution_url": self.resolution_url,
+                "retry_after_seconds": self.retry_after_seconds,
+            },
+        }
+
+
+def _retry_after(headers: Any) -> Optional[float]:
+    """Seconds from the `Retry-After` header, if it is the numeric form.
+
+    HTTP also permits an HTTP-date here. The gateway only ever sends deltas, and
+    guessing wrong about a date would produce a confidently incorrect "wait 3
+    seconds", so anything unparseable is dropped rather than approximated.
+    """
+    try:
+        raw = headers.get("Retry-After")
+    except Exception:  # noqa: BLE001 — a mapping-ish object is all we assume
+        return None
+    if raw is None:
+        return None
+    try:
+        return float(str(raw).strip())
+    except ValueError:
+        return None
+
+
+def _sentence(code: str, message: str, url: Optional[str], retry: Optional[float]) -> str:
+    """The user-facing line for a known code.
+
+    Every branch names CaptchaKraken. That is the entire point of this module:
+    the person reading it needs to know which product is refusing them before
+    anything else in the sentence can help.
+    """
+    if code == "insufficient_credits":
+        return (
+            "CaptchaKraken: your account is out of credits, so this solve was refused. "
+            f"Top up at {url or _DASHBOARD} and retry."
+        )
+
+    if code == "solve_abandoned":
+        return (
+            "CaptchaKraken: this captcha attempt was served too many times without "
+            "settling and has been abandoned. That usually means the IP reputation or "
+            "the browser fingerprint is being rejected — not that the answers were "
+            "wrong. Start a fresh attempt with a new x-ck-session (the driver mints "
+            "one per solve() call, so a new solve is enough)."
+        )
+
+    if code == "rate_limited":
+        wait = f" Retry in about {retry:g}s." if retry else " Back off and retry."
+        return f"CaptchaKraken: too many requests.{wait}"
+
+    if code == "account_suspended":
+        return (
+            "CaptchaKraken: this account is suspended, so solving is disabled. "
+            f"Contact support at {url or _SUPPORT}."
+        )
+
+    if code == "request_too_large":
+        return (
+            "CaptchaKraken: the screenshot sent for this solve exceeded the request "
+            f"size limit. ({message}) Capture the captcha element rather than the "
+            "whole page if you are not already."
+        )
+
+    if code in ("missing_api_key", "invalid_api_key"):
+        return (
+            "CaptchaKraken: the API key was missing or not accepted. Set "
+            "CAPTCHA_KRAKEN_API_KEY, or run the CaptchaKraken MCP server's "
+            "`create_api_key` tool to write one to ~/.captchakraken/credentials. "
+            f"Manage keys at {url or _DASHBOARD}."
+        )
+
+    if code == "upstream_unavailable":
+        return (
+            "CaptchaKraken: the solver fleet is temporarily unreachable. This is on "
+            "our side, not yours — retry shortly."
+        )
+
+    # `unrecognized_prompt`, `invalid_request`, and anything added after this was
+    # written. The server's own message is the best thing available, so it is
+    # carried through verbatim rather than replaced with a guess.
+    tail = f" See {url}." if url else ""
+    return f"CaptchaKraken: {message}{tail}"
+
+
+def from_response(resp: Any, url: str) -> Exception:
+    """Build the exception for a non-OK response, hosted or self-hosted.
+
+    Returns rather than raises so the caller's `raise` keeps the traceback
+    anchored at the request site, where it is useful.
+    """
+    body_text = (getattr(resp, "text", "") or "")[:300]
+    status = getattr(resp, "status_code", None)
+
+    error: Dict[str, Any] = {}
+    try:
+        parsed = resp.json()
+        if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
+            error = parsed["error"]
+    except Exception:  # noqa: BLE001 — a non-JSON body is the self-hosted case
+        error = {}
+
+    code = error.get("code")
+    if isinstance(code, str) and code:
+        retry = _retry_after(getattr(resp, "headers", {}) or {})
+        resolution = error.get("resolution_url") or None
+        message = str(error.get("message") or "").strip() or "the request was refused"
+        return CaptchaKrakenAPIError(
+            _sentence(code, message, resolution, retry),
+            status=status,
+            code=code,
+            resolution_url=resolution,
+            retry_after_seconds=retry,
+        )
+
+    # No gateway envelope: a local vLLM, a proxy in between, or an HTML error
+    # page. Keep the pre-existing message so self-hosted debugging is unchanged.
+    hint = ""
+    if status in (401, 403):
+        hint = " — check CAPTCHA_KRAKEN_API_KEY is set and forwarded to the CLI"
+    reason = getattr(resp, "reason", "") or ""
+    return RuntimeError(f"vLLM {status} {reason} at {url}{hint}. Body: {body_text}")

package/python/src/captchakraken/planner.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List, Optional
 
 import requests
 
-from . import config
+from . import config, errors
 from .server_manager import ensure_server
 from .timing import timed
 
@@ -55,17 +55,79 @@ _CLIENT_ENV = "CAPTCHA_KRAKEN_CLIENT"
 _SESSION_HEADER = "X-CK-Session"
 _SESSION_ENV = "CAPTCHA_KRAKEN_SESSION"
 
+# Arbitrary extra headers, as "Name: value" pairs separated by newlines or
+# commas. Empty and absent by default.
+#
+# WHY THIS EXISTS. Some endpoints sit behind a gate that is not the API key —
+# our own dev gateway (api.dev.captchakraken.com) wants X-CK-Dev-Auth, and a
+# corporate egress proxy may want its own token. Without this the published
+# client simply cannot reach such an endpoint, which meant the dev environment
+# could not exercise the real client path at all: the thing dev exists to
+# rehearse was the one thing it could not do.
+#
+# IT CANNOT OVERWRITE Authorization, Content-Type, OR THE X-CK-* HEADERS. Those
+# carry the credential and the billing attribution. Allowing an env var to
+# rewrite Authorization would turn a stray export into "your key is not the key
+# being charged", and allowing it to rewrite X-CK-Session would let a caller
+# escape the per-attempt billing cap by pinning one session id forever.
+_EXTRA_HEADERS_ENV = "CAPTCHA_KRAKEN_EXTRA_HEADERS"
+_PROTECTED_HEADERS = frozenset(
+    {"authorization", "content-type", _CLIENT_HEADER.lower(), _SESSION_HEADER.lower()}
+)
+
 # These values reach the wire verbatim from the environment, so they are
 # sanitized rather than trusted: a CR/LF would otherwise splice arbitrary
 # headers into the upstream request.
 _HEADER_VALUE_MAX = 128
 
 
+# RFC 7230 token characters. Anything else is not a header name.
+_VALID_HEADER_NAME = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
+
+
 def _clean_header_value(raw: str) -> str:
     """Printable-ASCII, length-capped header value ("" when nothing survives)."""
     return "".join(c for c in raw.strip() if 0x20 <= ord(c) < 0x7F)[:_HEADER_VALUE_MAX]
 
 
+def _extra_headers(raw: str) -> Dict[str, str]:
+    """Parse CAPTCHA_KRAKEN_EXTRA_HEADERS into a header dict.
+
+    Accepts "Name: value" pairs separated by newlines or commas:
+
+        CAPTCHA_KRAKEN_EXTRA_HEADERS='X-CK-Dev-Auth: hunter2'
+        CAPTCHA_KRAKEN_EXTRA_HEADERS=$'X-One: a\nX-Two: b'
+
+    Malformed entries are DROPPED, never guessed at. A pair with no colon is
+    not a header, and inventing one from it would put an attacker-shaped string
+    on the wire. Names are restricted to the RFC 7230 token characters for the
+    same reason the values are sanitized: a CR/LF in either would splice extra
+    headers into the request.
+
+    Protected headers are refused, so this cannot be used to replace the
+    credential or the billing attribution.
+    """
+    out: Dict[str, str] = {}
+    if not raw.strip():
+        return out
+
+    for entry in raw.replace(",", "\n").splitlines():
+        entry = entry.strip()
+        if not entry or ":" not in entry:
+            continue
+        name, _, value = entry.partition(":")
+        name = name.strip()
+        value = _clean_header_value(value)
+        if not name or not value:
+            continue
+        if not _VALID_HEADER_NAME.match(name):
+            continue
+        if name.lower() in _PROTECTED_HEADERS:
+            continue
+        out[name] = value
+    return out
+
+
 def routing_headers(env=None) -> Dict[str, str]:
     """Fleet-routing + hosted-API headers derived from the environment.
 
@@ -93,6 +155,8 @@ def routing_headers(env=None) -> Dict[str, str]:
         if value:
             headers[header] = value
 
+    headers.update(_extra_headers(env.get(_EXTRA_HEADERS_ENV) or ""))
+
     return headers
 
 
@@ -224,21 +288,18 @@ class ActionPlanner:
         with timed("planner.chat"):
             resp = requests.post(url, headers=headers, json=payload, timeout=120)
 
-        # Surface auth / server errors with the actual body instead of letting
-        # resp.json() blow up with a cryptic "Expecting value: line 1 column 1"
-        # on a non-JSON response (e.g. a 401 {"error":"Unauthorized"} or an
-        # HTML error page). 401/403 almost always means the bearer token
-        # (CAPTCHA_KRAKEN_API_KEY) didn't reach this process.
+        # Surface auth / billing / server errors as something the reader can act
+        # on, instead of letting resp.json() blow up with a cryptic "Expecting
+        # value: line 1 column 1" on a non-JSON response.
+        #
+        # `errors.from_response` decides which of the two worlds we are in by
+        # looking for the gateway's `error.code`: present means the hosted API
+        # refused us and there is a real explanation to give (out of credits,
+        # rate limited, attempt abandoned); absent means a local vLLM or a proxy,
+        # and the old message — including the bearer-token hint on 401/403 — is
+        # reproduced unchanged.
         if not resp.ok:
-            body = (resp.text or "")[:300]
-            hint = ""
-            if resp.status_code in (401, 403):
-                hint = (
-                    " — check CAPTCHA_KRAKEN_API_KEY is set and forwarded to the CLI"
-                )
-            raise RuntimeError(
-                f"vLLM {resp.status_code} {resp.reason} at {url}{hint}. Body: {body}"
-            )
+            raise errors.from_response(resp, url)
 
         try:
             data = resp.json()