working defaults

README.md

@@ -5,11 +5,14 @@
 ## Features
 
 - **Standard OpenAI interface**: Serves `/v1/chat/completions` and `/v1/models` (with `/chat/completions` and `/models` aliases).
-- **Dual-engine architecture**:
+- **Dual-engine architecture (Browser Bridge enabled by default)**:
-  - **Browser bridge (`-auto-capture`)**: Routes upstream requests directly through a private, stealth headless Chromium session over CDP. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks.
+  - **Browser bridge (`-auto-capture`, default: true)**: Routes upstream requests directly through a private, stealth offscreen Chromium session over CDP with automatic virtual X server (`Xvfb`) isolation. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks out of the box.
-  - **Direct HTTP client**: Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly.
+  - **Direct HTTP client (`-direct` / `-no-bridge`)**: Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly.
+- **Real-time per-token streaming**: Streams tokens in real time over CDP via `Runtime.addBinding` and `ReadableStreamDefaultReader`, passing token chunks immediately through stateful thinking and tool call filters without buffering.
+- **Automated hardware fingerprint rotation & 429 auto-recovery**: Dynamically discovers FingerprintJS entropy modules (or generates high-entropy synthetic fallbacks) and auto-rotates visitor identities upon encountering `HTTP 429` / rate limits, retrying immediately (up to 4 attempts) without dropping client connections.
 - **Private & anti-fingerprinting stealth**:
   - **100% isolated session**: Launches in `--incognito` mode with a temporary ephemeral user profile and `--disable-extensions`, completely segregated from any existing Chromium/Chrome windows, history, extensions, or sessions.
+  - **Auto-managed virtual display (`-xvfb`, default: true)**: Spawns an isolated Xvfb display to completely isolate Chromium from tiling window managers (i3, bspwm, sway, dwm).
   - **Zero port collisions**: Binds to a dynamically allocated ephemeral loopback port for CDP commands.
   - **Stealth & anti-detection**:
     - Disables Blink automation features (`--disable-blink-features=AutomationControlled`).
@@ -19,7 +22,6 @@
     - Strips telemetry, domain reliability, crash reporting, and sync.
 - **Dynamic token ingestion API**: Provides `GET /v1/token` and `POST /v1/token` to inspect or hot-reload single-use hCaptcha tokens and cookies on the fly without restarting the server.
 - **Fast fail & clear error propagation**: Non-transient errors (such as `captcha_failed` or `invalid_params`) return immediately (<300ms) without wasting time in exponential backoff retry loops.
-- **Streaming & non-streaming**: Full support for Server-Sent Events (`stream: true`) and standard JSON responses (`stream: false`).
 - **Reasoning content separation**: Parses `<think>...</think>` tags and upstream reasoning chunks into `reasoning_content` deltas / message fields.
 - **Function / tool calling translation**: Injects tool schemas into system instructions, maps multi-turn tool calling history, and parses model tool invocations into standard OpenAI `tool_calls`.
 - **Zero external dependencies**: Implemented using pure Go standard library.
@@ -41,19 +43,24 @@ Binary will be produced at `bin/th3ist`.
 ## Running
 
 ```bash
-# Run with Browser Bridge active (recommended for bypassing Vercel TLS checkpoint)
+# Run with default settings (Browser Bridge and isolated Xvfb active)
-./bin/th3ist -auto-capture
+./bin/th3ist
 
 # Run on a custom port with static defaults
 ./bin/th3ist -port 9000 -default-model gemini-3.5-flash-lite
+
+# Run in direct HTTP client mode (bypasses browser bridge)
+./bin/th3ist -direct
 ```
 
 ### CLI flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-auto-capture` | Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens) | `false` |
+| `-auto-capture` | Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens) | `true` |
-| `-xvfb` | Automatically spawn and manage an isolated virtual X server (`Xvfb`) for complete isolation from tiling window managers | `false` |
+| `-direct` / `-no-bridge` | Disable browser bridge and run in direct HTTP mode | `false` |
+| `-xvfb` / `-Xvfb` | Automatically spawn and manage an isolated virtual X server (`Xvfb`) for complete isolation from tiling window managers | `true` |
+| `-no-xvfb` | Disable automatic virtual X server (uses active `$DISPLAY`) | `false` |
 | `-display` | Custom X11 DISPLAY to attach Chromium to (e.g. `:99` for an existing Xvfb / Xephyr / Xnest session) | *(auto / `$DISPLAY`)* |
 | `-headless` | Force strict headless mode `--headless=new` (defaults to offscreen window when display is present) | `false` |
 | `-browser-bin` | Custom path to Chromium/Google Chrome binary | *(auto-detected)* |
@@ -68,20 +75,14 @@ Binary will be produced at `bin/th3ist`.
 
 ### Tiled window managers & virtual display isolation
 
-On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), any window created on the main `$DISPLAY` may be caught and tiled into the current workspace.
+On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), `th3ist` defaults to managing an isolated virtual X server (`-xvfb`) so that no Chromium windows appear on your desktop workspace:
 
-To prevent any windows from appearing on your desktop:
+1. **Option A: Auto-managed Xvfb (Default)**:
-
-1. **Option A: Auto-managed Xvfb (`-xvfb`)**:
    Install `xorg-server-xvfb` (or `Xfbdev`):
    - **Void Linux**: `sudo xbps-install -S xorg-server-xvfb`
    - **Debian / Ubuntu**: `sudo apt install xvfb`
    - **Arch Linux**: `sudo pacman -S xorg-server-xvfb`
 
-   Then run `th3ist` with `-xvfb`:
-   ```bash
-   ./bin/th3ist -auto-capture -xvfb -port 9000
-   ```
    `th3ist` will automatically allocate an isolated virtual display (e.g. `:99`), launch `Xvfb`, attach Chromium to it, and cleanly terminate `Xvfb` on exit.
 
 2. **Option B: Manual virtual X server (`Xvfb`, `Xephyr`, or `Xnest`)**:
@@ -90,7 +91,7 @@ To prevent any windows from appearing on your desktop:
    Xvfb :99 -screen 0 1280x800x24 -ac &
 
    # Run th3ist attached to display :99
-   ./bin/th3ist -auto-capture -display :99 -port 9000
+   ./bin/th3ist -display :99 -port 9000
    ```
 
 3. **Option C: Tiling window manager rules (`--class=th3ist_hidden`)**:

architecture.md

@@ -90,8 +90,8 @@ args := []string{
 
 - **Offscreen positioning (`-3000, -3000`)**: Keeps the browser window completely off the visible desktop area without taking focus, stealing cursor input, or disrupting user workflow.
 - **Tiled window manager isolation (`-xvfb` / `-display`)**:
-  - Tiling window managers (i3, bspwm, sway, dwm) can capture offscreen windows on the main display. `th3ist` provides `-xvfb` to automatically launch and attach to a virtual X server (`Xvfb :<free_display> -screen 0 1280x800x24`), ensuring 100% isolation from the desktop environment.
+  - Tiling window managers (i3, bspwm, sway, dwm, awesome, hyprland, xmonad) can capture offscreen windows on the main display. `th3ist` defaults to managing an isolated virtual X server (`-xvfb`, default: true) via `Xvfb :<free_display> -screen 0 1280x800x24`, ensuring 100% isolation from the desktop environment out of the box.
-  - Users can also supply a custom `-display :99` (for existing `Xvfb`, `Xephyr`, or `Xnest` sessions).
+  - Users can also supply a custom `-display :99` (for existing `Xvfb`, `Xephyr`, or `Xnest` sessions) or pass `-no-xvfb` to attach to `$DISPLAY`.
   - Sets window class `--class=th3ist_hidden` and `--app=https://t3.chat` for easy floating/scratchpad filtering.
 - **Headless detection evasion**: Running in an active display context (real or virtual Xvfb) prevents hCaptcha Enterprise's client heuristics from detecting headless browser environments, ensuring automated invisible token generation succeeds.
 - **Strict headless fallback (`-headless`)**: When the `-headless` flag is passed or when `DISPLAY` is unset (e.g. Docker or server environments), it automatically uses `--headless=new`.
@@ -173,7 +173,7 @@ Chromium ReadableStream (window.th3istStreamChunk)
         ├─► Emits structured OpenAI delta.tool_calls
         └─► Emits clean assistant text to delta.content in real time
 ```
-1. `Runtime.addBinding`: Exposes `window.th3istStreamChunk` to the browser context, relaying `ReadableStream` chunks over CDP in real time without buffering.
+1. `Runtime.addBinding`: Exposes `window.th3istStreamChunk` to the browser context upon bridge startup, relaying in-page `ReadableStream` chunks over CDP in real time without buffering.
 2. `StreamLineBuffer`: Reassembles partial TCP packets into complete protocol lines across chunk boundaries.
 3. `StreamThinkingFilter`: Stateful filter intercepting `<think>...</think>` tags and routing to `reasoning_content`.
 4. `StreamToolCallFilter`: Stateful filter intercepting `<tool_call>...</tool_call>` tags, preventing raw XML leaks in `content` and emitting OpenAI `delta.tool_calls`.
@@ -214,7 +214,7 @@ To allow external token management or custom API keys:
 
 ### 3.6. Error handling & fast-fail semantics
 
-- **Client errors (`400`, `401`, `403`)**: Non-transient errors (such as `captcha_failed` or `invalid_params`) bypass retry loops and return immediately in `<300ms` with original error bodies and HTTP status codes.
+- **Client errors (`400`, `401`, `403`)**: Non-transient errors (such as `invalid_params`) bypass retry loops and return immediately in `<300ms` with original error bodies and HTTP status codes.
 - **Server errors (`5xx`)**: Direct HTTP fallback requests utilize `DoWithFibonacciRetry` with bounded Fibonacci delays (1s, 1s, 2s, 3s, 5s) before failing.
 
 ---
@@ -234,18 +234,13 @@ Empirical testing confirmed that rate limiting on `t3.chat` is **tracked strictl
 
 #### 2. Automated hardware fingerprint mutation engine (`RotateIdentity`)
 Because `th3ist` controls Chromium via CDP, `BrowserBridge.RotateIdentity()` mutates client hardware entropy on demand:
-- **Canvas entropy**: Injects pseudo-random variations into 2D canvas geometry hashing.
+- **Dynamic module discovery & synthetic fallback**: Searches `document.scripts` and `performance.getEntriesByType('resource')` for active FingerprintJS modules before falling back to asset paths. If unavailable, synthesizes a complete set of high-entropy components.
+- **Canvas entropy**: Injects pseudo-random variations into 2D canvas geometry & text hashing.
 - **Audio entropy**: Adds subtle jitter to `AudioContext` frequency responses.
-- **Hardware concurrency & resolution**: Mutates CPU core counts (4, 6, 8, 12, 16) and screen resolutions.
+- **Hardware concurrency, resolution & memory**: Mutates CPU core counts (4, 6, 8, 12, 16, 24, 32), screen resolutions, and device memory values (4, 8, 16, 32 GB).
-- Submits the modified components to `/api/identity`, which returns:
+- **Storage reset**: Clears cached visitor markers from `localStorage` and `sessionStorage`.
-  ```json
+- Submits the modified components to `/api/identity`, which returns a fresh signed `visitor_<hash>` and updates the browser cookie jar.
-  {
+- **Zero-downtime multi-attempt auto-recovery**: When `ExecuteFetch()` or `ExecuteStreamFetch()` receives an `HTTP 429` or rate limit response, it immediately invokes `RotateIdentity()`, mints a fresh hCaptcha token, resets session IDs, and retries the request transparently (up to 4 attempts) without returning 429 errors to the client right away.
-    "visitorId": "visitor_<fresh_hash>",
-    "requiresSignIn": false,
-    "confidence": 1
-  }
-  ```
-- **Zero-downtime auto-recovery**: If `ExecuteFetch()` receives an `HTTP 429` or rate limit error, it immediately invokes `RotateIdentity()`, mints a fresh hCaptcha token, resets session IDs, and retries the completion request transparently (up to 4 attempts) without returning 429 errors to the client right away.
 
 #### 3. Bypassing guest limits via BYOK (bring your own key)
 `th3ist` also supports passing custom provider API keys directly in standard OpenAI format:
@@ -262,11 +257,11 @@ curl http://localhost:8080/v1/chat/completions \
 
 | File | Purpose |
 |------|---------|
-| [`th3ist.go`](file:///home/lux/ditch/th3ist/th3ist.go) | Main server, BrowserBridge implementation, CDP protocol handler, stream parsers, tool calling converter, and HTTP handlers. |
+| [`th3ist.go`](file:///home/lux/proj/th3ist/th3ist.go) | Main server, BrowserBridge implementation, CDP protocol handler, stream parsers, tool calling converter, and HTTP handlers. |
-| [`th3ist_test.go`](file:///home/lux/ditch/th3ist/th3ist_test.go) | Unit test suite covering message transforms, thinking tag filters, tool calling detection, mock upstream completions, and live bridge tests. |
+| [`th3ist_test.go`](file:///home/lux/proj/th3ist/th3ist_test.go) | Unit test suite covering message transforms, thinking tag filters, tool calling detection, mock upstream completions, and live bridge tests. |
-| [`Makefile`](file:///home/lux/ditch/th3ist/Makefile) | Build, test, run, and cleanup targets. |
+| [`Makefile`](file:///home/lux/proj/th3ist/Makefile) | Build, test, run, and cleanup targets. |
-| [`README.md`](file:///home/lux/ditch/th3ist/README.md) | User documentation, quickstart guide, CLI flags, and API examples. |
+| [`README.md`](file:///home/lux/proj/th3ist/README.md) | User documentation, quickstart guide, CLI flags, and API examples. |
-| [`architecture.md`](file:///home/lux/ditch/th3ist/architecture.md) | In-depth architectural design, reverse engineering findings, and security mechanisms. |
+| [`architecture.md`](file:///home/lux/proj/th3ist/architecture.md) | In-depth architectural design, reverse engineering findings, and security mechanisms. |
 
 ---
 

th3ist.go

@@ -2940,10 +2940,15 @@ func main() {
   deploymentFlag := flag.String("deployment-id", DefaultDeploymentID, "x-deployment-id header value")
   clientContextFlag := flag.String("client-context", DefaultClientContext, "x-client-context header value")
   browserBinFlag := flag.String("browser-bin", "", "Custom path to Chromium/Chrome binary for auto-capture")
-  autoCaptureFlag := flag.Bool("auto-capture", false, "Automatically bridge requests and auto-generate fresh hCaptcha tokens via Chromium")
+  autoCaptureFlag := flag.Bool("auto-capture", true, "Automatically bridge requests and auto-generate fresh hCaptcha tokens via Chromium (default true)")
+  directFlag := flag.Bool("direct", false, "Disable browser bridge and run in direct HTTP client mode")
+  noBridgeFlag := flag.Bool("no-bridge", false, "Disable browser bridge (alias for -direct)")
+  noAutoCaptureFlag := flag.Bool("no-auto-capture", false, "Disable browser bridge (alias for -direct)")
   headlessFlag := flag.Bool("headless", false, "Force strict headless mode (defaults to offscreen window if display is available)")
   displayFlag := flag.String("display", "", "Custom X11 DISPLAY to run browser on (e.g. :99 for Xvfb / Xephyr / Xnest)")
-  xvfbFlag := flag.Bool("xvfb", false, "Automatically spawn and manage an isolated virtual X server (Xvfb) for headless tiling WM environments")
+  xvfbFlag := flag.Bool("xvfb", true, "Automatically spawn and manage an isolated virtual X server (Xvfb) for headless tiling WM environments (default true)")
+  xvfbUpperFlag := flag.Bool("Xvfb", false, "Alias for -xvfb")
+  noXvfbFlag := flag.Bool("no-xvfb", false, "Disable automatic virtual X server (use active DISPLAY)")
   uaFlag := flag.String("user-agent", DefaultUserAgent, "User-Agent header to send upstream")
   uaShortFlag := flag.String("ua", "", "Alias for -user-agent")
   flag.Parse()
@@ -2954,6 +2959,19 @@ func main() {
     ConfiguredUserAgent = *uaFlag
   }
 
+  effectiveAutoCapture := *autoCaptureFlag
+  if *directFlag || *noBridgeFlag || *noAutoCaptureFlag {
+    effectiveAutoCapture = false
+  }
+
+  effectiveXvfb := *xvfbFlag
+  if *xvfbUpperFlag {
+    effectiveXvfb = true
+  }
+  if *noXvfbFlag {
+    effectiveXvfb = false
+  }
+
   gateway := NewT3Gateway(
     *targetURLFlag,
     *clientContextFlag,
@@ -2962,13 +2980,13 @@ func main() {
     *hcaptchaFlag,
     *defaultModelFlag,
     *browserBinFlag,
-    *autoCaptureFlag,
+    effectiveAutoCapture,
     *headlessFlag,
     *displayFlag,
-    *xvfbFlag,
+    effectiveXvfb,
   )
 
-  if *autoCaptureFlag {
+  if effectiveAutoCapture {
     fmt.Println("Initializing private browser bridge (TLS & dynamic hCaptcha generator)...")
     if err := gateway.bridge.Start(); err != nil {
       fmt.Fprintf(os.Stderr, "warning: browser bridge init failed: %v (falling back to direct client)\n", err)
@@ -3008,7 +3026,8 @@ func main() {
   fmt.Printf("th3ist gateway starting on port %s...\n", *portFlag)
   fmt.Printf("Default Model: %s\n", *defaultModelFlag)
   fmt.Printf("Upstream: %s\n", *targetURLFlag)
-  fmt.Printf("Auto-Capture / Bridge: %t\n", *autoCaptureFlag)
+  fmt.Printf("Auto-Capture / Bridge: %t\n", effectiveAutoCapture)
+  fmt.Printf("Virtual X Display (Xvfb): %t\n", effectiveXvfb)
   fmt.Printf("Endpoints:\n")
   fmt.Printf("  GET   http://localhost:%s/v1/models\n", *portFlag)
   fmt.Printf("  POST  http://localhost:%s/v1/chat/completions\n", *portFlag)