human-browser 4.5.1 → 4.6.0

package/README.md

@@ -20,7 +20,7 @@ Regular Playwright on a data-center server gets blocked **immediately** by:
 
 Local stealth libraries (patchright, undetected-chromedriver, playwright-stealth) close some of these gaps in JS, but leak others — most notably **WebRTC ICE candidates** that surface the server's real datacenter IP regardless of your proxy.
 
-HumanBrowser's **cloud build** runs our own stealth-tuned Chromium with all those leaks closed at the browser layer — TLS ja3/ja4 matched to real Chrome, GPU vendor/renderer spoofing, WebRTC IP replacement, canvas/WebGL/audio noise — plus residential proxies, plus a live browser viewer. **Drive it via the Agent2Agent protocol — no install, no version pinning, no Linux build of Chromium for you to maintain.**
+Human Browser's **cloud build** runs a custom forked Chromium with **C++-source-level fingerprint patches** (TLS ja3/ja4 matched to real Chrome, GPU vendor/renderer spoofing, WebRTC IP replacement, canvas/WebGL/audio noise) that you cannot get from any npm package. Plus residential proxies. Plus a live browser viewer. **Drive it via the Agent2Agent protocol — no install, no version pinning, no Linux build of Chromium for you to maintain.**
 
 ---
 
@@ -138,7 +138,7 @@ If you don't pass one, the server uses the token's `default_profile` (configurab
 
 If you want to skip the cloud entirely and drive your own Chromium with a residential proxy you supply yourself, the `human-browser` npm package exposes `launchHuman()` — a drop-in Playwright launcher with our humanizer helpers, geo-fingerprint plumbing, and built-in 2captcha integration.
 
-**Note:** the library does NOT include the stealth-tuned Chromium binary we run in the cloud — that one's part of the managed service only. Library mode is patchright + our humanizer helpers; expect a noticeably lower pass-rate on Cloudflare BM / DataDome / Google sign-in / WebRTC-aware bot scoring than the cloud.
+**Note:** the library does NOT include our forked Chromium with C++ stealth patches — that binary is part of the cloud build only. Library mode is patchright-stealth-plus-helpers; expect lower pass-rate on Cloudflare BM / DataDome / Google sign-in / WebRTC-aware bot scoring than the cloud.
 
 ```js
 const { launchHuman } = require('human-browser');

package/SKILL.md

@@ -1000,4 +1000,41 @@ cost: $0.58
 viewer: https://humanbrowser.cloud/a/s_xyz?k=...
 ```
 
+#### Zombie protection (v78+)
+
+Two server-side mechanisms prevent client timeouts from accumulating zombie sessions and exhausting `HB_MAX_SESSIONS_PER_TOKEN` (default 10):
+
+**Profile mutex on /spawn:** if the same `(token, profile)` already has an active session, `/spawn` returns the EXISTING session info with `"reused": true` instead of creating a new one. To force a fresh session anyway, pass `body.force_new: true`. Ephemeral spawns (no profile) bypass the check.
+
+```jsonc
+// Second /spawn with profile=main → reuse existing
+{
+  "sessionId": "s_existing...",
+  "password": "...",
+  "viewerUrl": "...",
+  "profile": "main",
+  "reused": true,
+  "createdAt": 1778529919000,
+  "lastActivityMs": 1778530100000
+}
+```
+
+**Auto-die after done:** once an agent emits `ev:done`, the session-server waits 5 minutes (`HB_DONE_GRACE_MS`, default 300000) for either a new `/run` or a new WS client to attach. If neither arrives → the session-server exits and spawner-router reaps the slot. Failed sessions (state=error) use a shorter 2-min grace (`HB_ERROR_GRACE_MS`). The 3-hour spawner-router idle reaper still exists as a backstop for sessions that never reached done.
+
+#### Admin session control (v78+, master skill token only)
+
+```bash
+# List all active sessions across all tokens
+curl -sX GET https://agent.humanbrowser.cloud/admin/sessions \
+  -H "Authorization: Bearer $HUMANBROWSER_SKILL_TOKEN"
+# → { "sessions": [{ sessionId, tokenHash, tokenOwner, profile, viewerUrl,
+#                    httpPort, cdpPort, wsClients, ready, exited,
+#                    lastActivityMs, ageMs, lastTaskAt, spawnedAt }], total, max }
+
+# Force-stop a specific session
+curl -sX DELETE https://agent.humanbrowser.cloud/admin/sessions/s_xxx \
+  -H "Authorization: Bearer $HUMANBROWSER_SKILL_TOKEN"
+# → { "ok": true, "sessionId": "s_xxx", "reason": "admin-kill" }
+```
+
 > **Note on multi-turn**: the A2A spec describes an `input-required` state for tasks that need follow-up input. The current cloud build runs every task to terminal in one shot — multi-turn resumption is reserved in the protocol but not yet wired up server-side. Use `tasks/cancel` and submit a fresh task if you need to redirect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-browser",
-  "version": "4.5.1",
+  "version": "4.6.0",
   "description": "Stealth browser for AI agents. Bypasses Cloudflare, DataDome, PerimeterX. Residential IPs from 10+ countries. iPhone 15 Pro fingerprint. Drop-in Playwright replacement — launchHuman() just works.",
   "keywords": [
     "browser-automation",