luxferre/th3ist
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

working defaults

Browse Source
This commit is contained in:
Luxferre
2026-08-26 08:24:40 +03:00
parent 5f23e9b61c
commit fa9f15b374
3 changed files with 58 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
architecture.md
+15 -20
View File
@@ -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.
- Users can also supply a custom `-display :99` (for existing `Xvfb`, `Xephyr`, or `Xnest` sessions).
- 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) 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.
- Submits the modified components to `/api/identity`, which returns:
```json
{
"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.
- **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).
- **Storage reset**: Clears cached visitor markers from `localStorage` and `sessionStorage`.
- 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.
#### 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_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. |
| [`Makefile`](file:///home/lux/ditch/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. |
| [`architecture.md`](file:///home/lux/ditch/th3ist/architecture.md) | In-depth architectural design, reverse engineering findings, and security mechanisms. |
| [`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/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/proj/th3ist/Makefile) | Build, test, run, and cleanup targets. |
| [`README.md`](file:///home/lux/proj/th3ist/README.md) | User documentation, quickstart guide, CLI flags, and API examples. |
| [`architecture.md`](file:///home/lux/proj/th3ist/architecture.md) | In-depth architectural design, reverse engineering findings, and security mechanisms. |
---