v0.3.0 — Web Reverse Engineering + Multi-Session

Changelog

0.3.0 (2026-05-22)

Major release: web reverse engineering, multi-session, DX improvements, platform compatibility.

Web Reverse Engineering (Phase 7b)

agentcloak now covers ~90% of web reverse engineering scenarios natively, replacing the need for jshookmcp in browser contexts.

• Debugger — breakpoints (URL regex + XHR pattern), single-step (over/into/out), call stack inspection, scope variable reading, paused-frame evaluation, source code search. Anti-debug bypass via skip-pauses
• Source maps — discover .map files from parsed scripts, pure-Python VLQ decode, reverse lookup (compiled line:col → original source:line:col), embedded source tree extraction
• Streaming monitor — WebSocket frame capture (sent/received) + Server-Sent Events monitoring, ring buffer with seq/since paging
• Init script hooks — inject JS before page scripts; 5 presets: fetch, xhr, json_parse, crypto, timing (log intercepted calls to console)
• Network route interception — abort/fulfill/continue with URL glob, resource type, and HTTP method filters
• Header injection — extra HTTP headers on every request (forged auth tokens)
• GraphQL — schema introspection + arbitrary query execution with browser cookies

JS Profiling (Phase 7f)

• Code coverage — precise per-function coverage recording; find which JS ran during an operation
• CPU profiling — execution time distribution; locate hot functions (encryption/signing)
• Heap snapshot — V8 object graph dump; grep for keys/tokens/decrypted data
• Performance metrics — DOM node count, JS heap size, layout/recalc counts

Multi-Session (Phase 7d)

• SessionManager — named sessions with independent browsers, per-session idle timeout (5min default), three-state lifecycle (registered/active/suspended)
• Zero-config isolation — CLAUDE_CODE_SESSION_ID auto-detected; each Claude Code instance gets its own browser without configuration
• MCP session isolation — mcp-{pid} auto-session with atexit cleanup
• Session management — cloak session list / close

DX Improvements (Phase 6f)

• Evaluate presets — --preset vue_inspect|react_inspect|jwt_decode|cookie_parse|storage_dump for common reverse-engineering operations
• Upload auto-find — omit --index to auto-discover hidden input[type=file] elements (drag-drop uploaders); --nth selects which one
• Download wait-click — cloak download wait-click --index N atomic operation (arm waiter → click → await download in one request)
• click --force — skip pointer-event check for covered elements
• Debugger URL search — search across multiple scripts by URL pattern
• Sourcemap 404 — clear HTTP status in error instead of cryptic parse failure
• Auto WS/SSE monitor — navigate auto-starts WebSocket/SSE listeners

Platform Compatibility (Phase 6c)

• Health metrics — /health returns uptime_seconds, request_count, active_connections via ASGI middleware
• CI matrix — unit tests now run on ubuntu × windows × macos × Python 3.12/3.13/3.14
• Platform support docs — docs/{en,zh}/reference/platform-support.md with feature × platform matrix
• Stale chromium detection — cloak doctor warns about old CloakBrowser binaries (~700MB each) with cleanup command

Daemon Reliability

• Auto re-spawn — daemon crash recovery with health probe confirmation
• httpx retry — HTTPTransport(retries=2) + split timeouts (connect=5s / read=90s)
• Version consistency — /health exposes version + route count; doctor warns on CLI/daemon mismatch; CLI 404 suggests daemon restart

Bug Fixes

• _cdp_send_impl / _cdp_enable_domain_impl now wrapped with BackendError
• Console capture fallback via CDP Runtime.consoleAPICalled
• Config get fixed after nested config refactor (6d)
• Clipboard read fast-fail (5s) with clear headless limitation error
• SSRF guard uses explicit blocklist; unblocks 198.18.0.0/15 fake-IP range
• Three dogfood UX fixes (config list keys, console timing, storage get)

Stats

• Routes: 59 → 102 (+43)
• MCP tools: 29 → 38 (+9)
• CLI commands: 27 → 38 (+11)
• Unit tests: 701 → 927 (+226)
• Chrome extension: on-demand CDP domain enable for reverse engineering

0.2.4 (2026-05-20)

Windows compatibility fixes from seed-user testing.

Bug Fixes

• Windows headed mode — skip Xvfb virtual framebuffer on Windows; was triggering misleading xvfb_not_found error when headless=false.
• Session file permissions — wrap os.chmod in contextlib.suppress for cross-platform consistency (no-op on Windows but now guarded).
• Windows spell directory — user spell directory now uses %APPDATA% on Windows instead of Unix .config path.

0.2.3 (2026-05-17)

Seed-user review round 2: bug fixes, security, snapshot optimization, network config.

Bug Fixes

• wait --url / frame focus --url — three-way URL matching: substring (default), glob (when * in middle), explicit glob: prefix. ? treated as literal (URL query param), not glob wildcard.
• frame focus snapshot — snapshot now correctly switches to the focused iframe's content (was always returning main page due to CDP session targeting bug).
• batch JSON array — accepts both JSONL and JSON array format; gives friendly error on parse failure instead of raw traceback.

Security & DX

• cookies export — output now includes domain column (domain | name=value); --url filter exposed in CLI.
• RemoteBridge privacy — docs now warn that tab list exposes all browser tabs in agent context.
• humanize/fill behavior — documented that fill under humanize=true is ~33x slower (CloakBrowser intercepts); guidance to use type for anti-detection, fill for speed.

Snapshot Optimization

• Indent compression — tree indent step reduced from 2 to 1 space (~50% indent token savings on deep pages).
• Token estimate — snapshot header now includes ~NK tok estimate (chars/4, no tokenizer dependency).
• Content dedup — content mode deduplicates adjacent identical lines (fixes Wikipedia/HN repetition from parent-child a11y node overlap).

Network Config

• browser.proxy — SOCKS5/HTTP upstream proxy for the browser (AGENTCLOAK_PROXY env var).
• browser.dns_over_https — defaults to false, disabling Chrome's built-in DoH to respect system DNS / split-horizon proxies.
• browser.extra_args — arbitrary Chromium launch args passthrough (AGENTCLOAK_EXTRA_ARGS env var, comma-separated).

Config CLI Upgrade

Five-verb declarative config management:

cloak config set <key> <value...>    # set scalar or replace list
cloak config get <key>               # read value
cloak config unset <key>             # reset to default
cloak config add <key> <value...>    # append to list
cloak config remove <key> <value>    # remove from list
cloak config keys                    # list all settable keys

Batch set, type-aware schema, write-after-validate with rollback, restart hints for browser/daemon keys.

---

0.2.2 (2026-05-17)

Rapid fix for 24 issues from seed-user review (16/17 fixed, 94% rate).

Fixed

• click --snap snapshot loss in headless mode (navigation timing race)
• resume tab count incorrect (only reported first tab)
• doctor daemon check changed from [fail] to [info]
• daemon auto-start log level downgraded from warning to silent
• daemon status command added (was health)
• config command now shows full merged config with sources
• content mode text concatenation (Chromium a11y tree limitation, documented)
• spell User-Agent unified to Chrome UA
• default snapshot limit set to 80 nodes
• navigate --snap includes header separator line
• cloak version subcommand added
• recipes.md --target parameter fixed to positional syntax
• SKILL.md --target reference corrected
• --snap / --include-snapshot naming unified
• SKILL.md headless/headed configuration documented
• troubleshooting.md rewritten from text-first perspective
• getting-started.md installation updated to uv/pipx first

---

0.2.1 (2026-05-16)

• Updated project description and metadata
• CI: PyPI trusted publisher workflow
• CI: added Python 3.14 to test matrix
• CI: migrated to uv for consistent dependency resolution
• Simplified skill install (removed claude-global alias)

---

0.2.0 (2026-05-16)

Major architecture upgrade: RemoteBridge production-ready, CLI output redesign, dynamic tier switching.

Highlights

• Text-first CLI output — stdout is the answer itself, no jq needed. --json flag for backward compat.
• Dynamic tier switching — cloak launch --tier remote_bridge hot-switches to user's Chrome without restarting daemon.
• RemoteBridge fully functional — evaluate, snapshot, tabs, capture all work through Chrome Extension.
• cloak skill install — one-command skill installation with platform auto-detection.
• Bridge token persistence — configure once, reconnects across daemon restarts.

CLI

• Text-first output: 5 output primitives (success/value/info/error/json_out), errors to stderr
• --snap combo flag on all actions (action + observe in one step)
• --limit replaces --max-nodes, default snapshot mode is compact
• cloak skill install/update/uninstall — manage skill files across agent platforms
• cloak launch --tier X — hot-switch browser context (cloak/playwright/remote_bridge)
• cloak bridge token [--reset] — view or rotate persistent bridge auth token
• 20 CLI command groups, 41 daemon routes

RemoteBridge (Chrome Extension) — experimental

Remote Bridge is experimental. Core functionality works but has limited real-world testing. Report issues on GitHub.

• evaluate rewritten with CDP Runtime.evaluate (async support, no CSP issues)
• activeTabId state — navigate creates new tab instead of hijacking user's active tab
• Tab group lifecycle: blue "agentcloak" (activ...

v0.2.4

Windows Compatibility Fixes

Seed-user testing revealed Windows edge cases. All three are minor but improve the out-of-box experience.

Bug Fixes

• Windows headed mode — skip Xvfb virtual framebuffer on Windows; was triggering misleading xvfb_not_found error when headless=false
• Session file permissions — wrap os.chmod in contextlib.suppress for cross-platform consistency
• Windows spell directory — user spell directory now uses %APPDATA% on Windows instead of Unix .config path

Full Changelog: v0.2.3...v0.2.4

v0.2.3

Seed-user review round 2: bug fixes, security, snapshot optimization, network config.

Bug Fixes

• wait --url / frame focus --url — three-way URL matching (substring/glob/explicit)
• frame focus snapshot now switches to iframe content (cross-origin + same-origin)
• batch accepts JSON array format with friendly errors

Security & DX

• cookies export — domain column + --url filter
• RemoteBridge privacy docs
• humanize/fill behavior documented

Snapshot Optimization

• Indent step 2→1 space (~50% indent token savings)
• Title line token estimate (~NK tok)
• Content mode adjacent line dedup

Network Config

• browser.proxy — SOCKS5/HTTP upstream proxy
• browser.dns_over_https — defaults to false (respects system DNS)
• browser.extra_args — arbitrary Chromium launch args

Config CLI Upgrade

• Five-verb declarative config: set, get, unset, add, remove, keys
• Batch set, type-aware schema, write-after-validate with rollback

Full changelog: https://github.com/shayuc137/agentcloak/blob/main/CHANGELOG.md

v0.2.2

Seed-user review fixes

Addresses all 24 issues from the first seed-user test report.

P0 Bug Fixes

• click --snap navigation snapshot: wait for domcontentloaded after navigation before taking snapshot
• resume tab count: tab new/close/switch now update resume snapshot

CLI Improvements

• daemon health renamed to daemon status (HTTP /health route preserved)
• cloak config shows merged values with source annotations ([default] / [config.toml] / [env:VAR])
• content snapshot mode unified to a11y tree (fixes inline element word fusion like "Hacker Newsnew")
• Spell pipeline fetch inherits browser UA + cookies; Chrome UA fallback for PUBLIC spells
• cloak version subcommand
• Compact snapshot defaults to 80 nodes (--limit 0 to disable)
• navigate/action --snap now includes # Title | url | N nodes header line

First-Run UX

• doctor: daemon-down shows [info] instead of [fail]
• Daemon auto-start log level: warning → info
• Install docs: recommend uv tool install / pipx, pip as fallback (PEP 668)
• Cloudflare stealth wording: objective description, no "bypass" claims
• cloak --help shows shortcuts in epilog

Skill Documentation

• All --target references replaced with correct positional syntax
• Unified --snap naming (removed --include-snapshot from docs)
• Added headless/headed mode and daemon lifecycle documentation
• Troubleshooting rewritten for text-mode perspective
• Fixed --backend bridge → cloak launch --tier remote_bridge

Infrastructure

• generate_skill.py --write auto-syncs skill data mirror
• dump_config source tracking fix for section-prefixed fields

v0.2.1

Fixes

• Documentation accuracy: fixed 14 factual inconsistencies across en/zh docs (version numbers, C++ patch count, CLI output model, MCP install instructions)
• CI stability: migrated to uv for reproducible builds, fixed ANSI test failures, added Python 3.14 to test matrix
• Skill install: simplified --platform claude to user-global (removed claude-global alias)

Housekeeping

• Updated project description
• Integration tests now have timeout + continue-on-error
• Added PyPI trusted publisher workflow (auto-publish on release)

v0.2.0

agentcloak v0.2.0

Major architecture upgrade: RemoteBridge production-ready, CLI output redesign, dynamic tier switching.

Highlights

• Text-first CLI output — stdout is the answer itself, no jq needed
• Dynamic tier switching — hot-switch between local CloakBrowser and user's Chrome
• RemoteBridge fully functional (experimental) — evaluate, snapshot, tabs, capture all work
• cloak skill install — one-command skill installation with platform auto-detection
• Bridge token persistence — configure extension once, reconnects across restarts

Install / Upgrade

pip install --upgrade agentcloak
cloak skill install
cloak doctor --fix

Chrome Extension (experimental)

Download agentcloak-chrome-extension-v0.2.0.tar.gz below, extract, then load as unpacked extension in chrome://extensions (Developer Mode).

See CHANGELOG.md for full details.