Daemon now automatically downloads and launches Chrome headless-shell
when started. No need to install Chrome separately.
- Downloads from Pinix COS (unified source for all platforms)
- Supports mac-arm64, mac-x64, linux64, linux-arm64
- Stores at ~/.bb-browser/browser/chrome-headless-shell-<platform>/
- Manages Chrome lifecycle: start on daemon start, kill on shutdown
- --no-chrome flag to skip (use external Chrome)
- Tested on macOS ARM64, Docker linux/amd64, Docker linux/arm64
Site adapters like twitter/search.js reference shared functions defined
in _helper.js (e.g. findTransactionIdGenerator). The runtime was not
loading this helper file, causing ReferenceError at runtime.
Now checks for _helper.js in the same directory as the adapter and
prepends it into the evaluation scope.
* feat(view): heartbeat ping + idle timeout + visibility-based disconnect
- Send OpPing (0x08) heartbeat every 5s (active) / 10s (idle)
- Visibility change: hidden starts 30s idle countdown, visible cancels
- cleanup(reason): distinct overlay messages for user/idle/network disconnect
- Start heartbeat on DataChannel open, stop on cleanup
* fix(view): use polling instead of setTimeout for idle timeout in hidden tabs
Browsers throttle setTimeout in hidden tabs to >=1 minute (Chrome).
The 30s idle timeout was never firing because the timer was delayed.
Fix: record hiddenSince timestamp on visibilitychange, check elapsed
time on each heartbeat interval tick instead of relying on setTimeout.
* fix(view): fire-and-forget stream.close to prevent disconnect from hanging
disconnect() was awaiting invoke('stream.close') which could hang if
the server is slow or the connection is degraded. This blocked cleanup()
from running, so the UI stayed in 'connected' state and heartbeat
continued indefinitely.
Fix: fire stream.close without awaiting, then immediately cleanup.
Streamer returns {result: {...}} but hub-bridge was passing the
entire envelope to Hub invoke. Frontend received
{result: {offer_sdp: ...}} instead of {offer_sdp: ...}, causing
offer_sdp to be undefined and video blackscreen.
Unwrap resp.result for stream.start/answer/close/switch.
Single source of truth for all command metadata:
- ParamDef with type, required, position, description
- CommandDef with method, group, description, requiresTab, params
- commandToJsonSchema() for Hub registration
- getCommand() / getCommandsByGroup() helpers
Hub registration now uses COMMANDS directly instead of
hardcoded arrays. Removed zod dependency from shared package.
CLI and daemon dispatch unchanged — they can consume COMMANDS
in a future refactor.
Daemon --hub mode replaces the standalone provider. All Hub
connection, clip registration, and invoke handling is now in
packages/daemon/src/hub-bridge.ts.
Also remove provider entry from tsup release build.
- New: packages/daemon/src/site-adapter.ts — site adapter scanning,
@meta parsing, domain-based tab matching, and JS evaluation via CDP
- Daemon: add site_run, site_list, site_info, site_search actions
- CLI: site commands now send HTTP to daemon instead of executing locally
- Provider: executeSiteCommand uses daemon site_run instead of shelling
out to CLI subprocess (removes execFile dependency)
- Protocol: add siteName, siteArgs, query fields to Request type
Site adapter execution is now a single path: CLI/Provider → daemon
→ CDP evaluate. No more three-layer process nesting.
Fix left-click being sent as middle-click: mapButton was converting
Web API button 0 (left) to 1, but bb-viewer uses 0-indexed buttons
(0=left, 1=middle, 2=right). Middle-click on links opens new tabs
in Chrome, which was the root cause of the 'links open in new tab'
bug.
Also remove unused URL bar composition tracking variables and
debug-only url_keydown logging.
Three fixes for modifier keys getting stuck:
- URL input capture-phase keyup no longer stops propagation for
modifier keys (Shift/Ctrl/Alt/Meta), allowing them to reach the
document-level onKeyUp handler
- Clicking the video overlay sends keyUp for all modifiers to clear
any stuck state from URL bar interactions
- Window focus event resets all modifiers to handle Cmd+Tab scenarios
Also add version indicator (v9) for debugging cache issues.
Route tab_list, tab_switch, tab_new, tab_close, navigate, back,
forward, reload through bb-viewer API instead of daemon. This ensures
tab operations and video stream operate on the same Chrome instance
and CDP session.
Also fix URL bar: skip polling overwrite when input is focused,
and simplify Enter key handling to avoid IME false suppression.
When CDP_PORT is set, forward it as --cdp-port to the daemon process
so both daemon (tab operations) and bb-viewer (screencast) connect
to the same Chrome instance. Without this, daemon defaults to 19825
(GUI Chrome) while bb-viewer uses the CDP_PORT value, causing tab
list and video stream to reference different Chrome instances.
- Green connect button, red disconnect state
- Video overlay with centered status text when disconnected
- Input overlay with crosshair cursor for mouse capture
- Tab/URL bar dimmed when not connected
- Slimmer toolbar (32px), webkit scrollbar styling
- Status resolution aligned right
* feat(daemon): expose CDP host/port in daemon.json and /status
- Add cdpHost, cdpPort to DaemonInfo (optional in shared, required in daemon)
- Write cdpHost/cdpPort from discovered cdpEndpoint to daemon.json
- Return cdpHost/cdpPort in GET /status response
- Enables external tools (bb-viewer) to discover the Chrome CDP connection
* feat(provider): add view.start/answer/close commands + bb-viewer sidecar management
- Register view.start, view.answer, view.close commands in browser clip
- Viewer sidecar: auto-spawn bb-viewer on first view.start, kill on exit
- Read CDP info from daemon.json (cdpHost/cdpPort) for viewer config
- TURN config from env vars: TURN_URL, TURN_USER, TURN_CRED
- bb-viewer binary lookup: ~/.bb-browser/bin/bb-viewer or PATH fallback
- Sidecar health check with 10s startup timeout
* feat(provider): add Clip Web UI for remote browser viewing
- web/view.html: remote viewer page using @pinixai/core/web invoke()
- WebRTC video with playoutDelayHint=0 for low latency
- DataChannel binary input: mouse, keyboard, scroll, IME
- X11 keysym mapping, composition handling
- Connect/Disconnect with auto-cleanup
- provider: set hasWeb=true for browser clip
- provider: handle GetClipWebCommand to serve web/ files
- MIME type detection, ETag, range request support
- Path security validation
* feat(provider): TURN ephemeral credentials via TURN REST API
- Generate time-limited TURN credentials using HMAC-SHA1 shared secret
- Credentials valid for 24h, auto-generated at viewer sidecar spawn
- Config: TURN_URL + TURN_SECRET env vars (no user-facing config needed)
- Replaces static TURN_USER/TURN_CRED with secure ephemeral credentials
* fix(web): replace esm.sh import with direct /api/ fetch
@pinixai/core is a private package, not available on esm.sh.
Use direct fetch to /api/{command} which the Hub's subdomain
handler proxies to provider invoke.
Screenshot command now writes PNG to ~/.pinix/data/browser/screenshots/
and returns a pinix:// URI by default. Base64 dataUrl is only included
when explicitly requested (includeBase64 flag), keeping the response
lightweight for cross-clip consumption.
CLI screenshot command sets includeBase64 for local file saving.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
bb-browser provider now processes DataCommand from the Hub, supporting
read/write/list/delete/stat on per-clip data directories (~/.pinix/data/).
This enables pinix://browser/... URIs to work for cross-clip file sharing.
Updated @pinixai/hub-client to ^0.2.0 for Data protocol types.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Highlights accumulated across multiple snapshot calls because the
cleanup function was commented out. Now buildDomTree clears previous
overlays at the start, and screenshot removes them before capture.
Closes#173
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(cli): daemon self-healing on CDP disconnect + cookie persistence
- ensureDaemon() now checks cdpConnected from /status response; when
Chrome is killed and daemon loses its CDP WebSocket, the stale daemon
is stopped and a fresh daemon+Chrome is spawned automatically instead
of returning 503 on every command.
- daemon status command shows actionable hints: how to start when not
running, how to stop when running, and a warning with recovery steps
when CDP is disconnected.
- Add --use-mock-keychain to managed Chrome launch args so cookie
encryption uses a fixed key instead of macOS Keychain. This fixes
cookie persistence on headless/remote machines (e.g. Mac Mini via SSH)
where Keychain access is unavailable (errSecInteractionNotAllowed).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(cli): add `daemon start` subcommand for explicit background startup
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Hub may send IDs (Twitter, Snowflake) as JSON numbers which exceed
Number.MAX_SAFE_INTEGER. Wrap integers >=16 digits as strings before
JSON.parse to prevent silent precision loss.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When a site CLI command exits non-zero, prefer stdout (which contains
structured JSON with error/hint) over stderr (which is often empty),
so callers receive actionable error messages instead of generic
"Command failed: node ..." text.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When running a site adapter that exists in both ~/.bb-browser/sites/
(local) and ~/.bb-browser/bb-sites/ (community), print a warning to
stderr so users know they're running a local override that may be
outdated. Suppressed in --json mode.
Closes#178
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: rewrite Edge Clip provider using @pinixai/hub-client (#175)
Replace hand-written protobuf descriptor in bb-browserd.ts with typed
imports from @pinixai/hub-client. The new bb-browser-provider.ts uses
create() from @bufbuild/protobuf with generated schemas, registers site
adapters as separate per-platform clips, and routes invocations to
either the daemon HTTP layer (browser commands) or CLI (site commands).
- Delete bin/bb-browserd.ts (1140 lines)
- Add bin/bb-browser-provider.ts (~710 lines)
- Add @pinixai/hub-client dependency
- Add bb-browser-provider bin entry and tsup entry point
- Add esbuild plugin to resolve hub-client gen subpath import
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: import from @pinixai/hub-client top-level exports
Use hub-client 0.1.2 which exports ProviderStream types directly.
Remove esbuild plugin hack for deep gen/hub_pb import.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: delete dead CDP code, fix MCP auth, extract shared daemon client
- Delete cdp-client.ts (1212 lines), cdp-monitor.ts (521 lines),
cdp-monitor-state.ts (182 lines) — all dead code from pre-daemon era
- Fix MCP server to read daemon.json for token/port instead of
hardcoded DAEMON_BASE_URL without auth
- Extract httpJson, readDaemonJson, isProcessAlive, DaemonInfo to
packages/shared/src/daemon-client.ts — eliminates duplication across
CLI daemon-manager, MCP server, and Edge Clip provider
- Fix scroll left/right: deltaX was hardcoded to 0, now properly
maps direction to deltaX/deltaY
- Align daemon tsup target from node20 to node18 (matches engines)
- Remove cdp-monitor from tsup entry points
Net: -1891 lines
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: lint — use DAEMON_DIR from shared, remove unused os import
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: review feedback — refresh platformClipAliases on reconnect, remove dead DAEMON_BASE_URL
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: remove duplicate bun shebang from provider source
tsup adds #!/usr/bin/env node via banner config. The source file's
#!/usr/bin/env bun caused a double shebang in dist/provider.js,
breaking node execution.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add unified command registry (shared/commands.ts)
Single source of truth for all 30+ commands. CLI/MCP/Edge Clip
will auto-generate interfaces from this registry.
Part of #170
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: complete command registry (history args, fetch, site commands)
- Add missing `query` and `days` args to `history` command
- Add 6 site commands: site_list, site_search, site_info, site_recommend,
site_run, site_update (category: "site")
- Verified `tab_new` is a real dispatch case (handled before ensurePageTarget)
- Verified `get` attribute enum is complete (text, url, title, value, html)
- Confirmed `fetch` is CLI-only (composes eval), not a daemon action — skip
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: use Zod schemas in command registry
Replace custom CommandArg interface with Zod schemas for runtime
validation, JSON Schema generation, and zero-conversion MCP integration.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: MCP + Edge Clip auto-generate from command registry
MCP: 25 → 37 tools, auto-generated from COMMANDS registry.
13 new tools: back, forward, refresh, check, uncheck, select,
dialog, frame, frame_main, tab_select, tab_close, trace, history.
Special handlers preserved for snapshot/screenshot/eval/network etc.
Edge Clip: 7 → 37 commands. Removed all direct CDP code (~400 lines).
Now routes through daemon HTTP API like CLI and MCP.
Uses inline zod-to-json-schema converter for Hub registration.
Adding a new command = 1 registry entry + 1 dispatch case.
All three interfaces (CLI/MCP/Edge Clip) get it automatically.
Part of #170
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: address review issues (since type, MCP compat, description loss, scroll default)
- Fix since field type: use z.union([z.literal("last_action"), z.number()])
instead of z.string() for network/console/errors commands
- Add MCP backward compat: accept old arg names (time, command) alongside
new ones (ms, networkCommand, consoleCommand, errorsCommand)
- Fix bb-browserd ZodOptional/ZodDefault unwrap losing outer description
- Fix typo: executeViaDeamon → executeViaDaemon
- Remove unnecessary tab arg from history command (daemon mode unsupported)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: prefix unused cmd params with underscore for lint
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: route Edge Clip site commands through CLI instead of daemon
Site commands (site_list, site_run, etc.) are handled by CLI, not
daemon. Edge Clip now routes them via CLI execFile, matching MCP's
approach. Other commands still go through daemon HTTP API.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: Edge Clip site commands use installed bb-browser CLI, not source
bun running CLI source fails because __BB_BROWSER_VERSION__ is a tsup
define not available at runtime. Use installed bb-browser binary with
fallback to dist/cli.js.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When Chrome disconnects or CDP connection fails, the daemon now:
- Returns 503 immediately instead of waiting 30 seconds
- Includes CDP target address, failure reason, and remediation hint
- Stores lastError in CdpConnection for diagnostic context
Before: {"error":"CDP connection timeout"} after 30s wait
After: {"error":"Chrome not connected (CDP at host:port)","reason":"...","hint":"..."} immediately
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Breaking changes (Extension removal) were already shipped in 0.11.0.
This release is bug fixes only (daemon auto-launch Chrome).
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add bump-minor-pre-major and bump-patch-for-minor-pre-major so
breaking changes bump minor (not major) while version is 0.x.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: auto-launch Chrome when daemon starts (#136, #143, #141)
CLI's ensureDaemon() now discovers/launches Chrome via cdp-discovery
before spawning the daemon, and passes --cdp-host/--cdp-port to it.
Previously the daemon was spawned with no CDP info, failed silently,
and users got "Daemon did not start in time" for every command.
- CLI: call discoverCdpPort() before spawn, pass CDP endpoint to daemon
- CLI: improve error messages with specific remediation steps
- CLI: increase startup timeout from 5s to 10s (Chrome launch time)
- MCP: read managed port file and pass --cdp-port to daemon
- Tests: 8 new daemon-startup tests reproducing and verifying the fix
- Tests: fix daemon-lifecycle tests (unique ports, tsx runner, proper cleanup)
Closes#136, closes#143, relates to #141, #118, #146
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: remove unused variable in MCP ensureDaemon
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: fix daemon-lifecycle kill-9 assertion for parallel CI
Relax PID equality assertion since parallel test suites share
daemon.json in CI. Assert file existence and valid structure instead.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Revert "test: fix daemon-lifecycle kill-9 assertion for parallel CI"
This reverts commit ba572d0f2a.
* fix: isolate test suites with BB_BROWSER_HOME to avoid parallel conflicts
Daemon and CLI tests both spawn daemon processes that write to
~/.bb-browser/daemon.json. When turbo runs them in parallel, they
conflict. Fix by:
- Support BB_BROWSER_HOME env var in daemon and daemon-manager
- Each test suite uses its own temp dir via BB_BROWSER_HOME
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: use DAEMON_DIR for managed port file path in daemon
The managed port file path was hardcoded to ~/.bb-browser/browser/cdp-port
ignoring BB_BROWSER_HOME. This broke test isolation in CI.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace separate PID file (/tmp/bb-browser.pid) and token file
(~/.bb-browser/daemon.token) with a single ~/.bb-browser/daemon.json
containing pid, host, port, and token.
CLI now reads daemon.json to connect, using the actual bound address
instead of hardcoded DAEMON_HOST. PID liveness check via process.kill(0)
detects stale daemon.json from crashed processes and auto-recovers.
Add harness tests for PID strategy and cold-start recovery scenario.
Closes#140
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move buildDomTree.js to packages/shared/. Delete packages/extension/
entirely. Update path references in daemon and CLI. Remove
build:extension script and release-please manifest sync.
The daemon connects directly to Chrome via CDP WebSocket since v0.11.0.
The Extension is no longer needed.
BREAKING CHANGE: Chrome Extension is removed. Users who relied on the
extension-based flow should use the daemon-direct mode instead.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat(cli): support cdpUrl and cdpHost from OpenClaw
- Prioritize cdpUrl field for full CDP endpoint URL
- Fall back to cdpHost + cdpPort if cdpUrl not available
- cdpHost defaults to 127.0.0.1 when not specified
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(cli): increase openclaw timeout to 30s
* perf(cli): add env var and file cache for CDP discovery
---------
Co-authored-by: User <user@example.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
yan5xu