Skip to content

feat: add persistent browser sessions and VNC URL discovery for Camofox#4400

Open
el-analista wants to merge 5 commits intoNousResearch:mainfrom
el-analista:feature/camoufox-persistant-session
Open

feat: add persistent browser sessions and VNC URL discovery for Camofox#4400
el-analista wants to merge 5 commits intoNousResearch:mainfrom
el-analista:feature/camoufox-persistant-session

Conversation

@el-analista
Copy link
Copy Markdown

Summary

Adds two features to the Camofox browser backend:

Persistent Browser Sessions

  • New browser.camofox.managed_persistence config option (also CAMOFOX_MANAGED_PERSISTENCE env var)
  • When enabled, Hermes sends a deterministic profile-scoped userId to Camofox so the server maps it to a persistent browser profile directory
  • Cookies, logins, and browser state survive across agent restarts
  • Default remains ephemeral (random userId per session)
  • New tools/browser_camofox_state.py module for profile-scoped identity generation

VNC URL Discovery

  • Camofox /health endpoint now returns vncPort when running in headed mode
  • Hermes constructs the VNC URL from the same hostname as CAMOFOX_URL (works with remote hosts, not just localhost)
  • VNC link included in camofox_navigate responses so the agent can share it with users
  • Port validated as integer in range 1-65535

Test Coverage

Tests: 377 → 377 (+0 new files, +9 new tests in existing files)

CODE PATH COVERAGE: 18/18 paths tested (100%)
QUALITY:  ★★★: 15  ★★: 2  ★: 0

Key test coverage:

  • Managed persistence toggle (env var, config yaml, explicit false values)
  • Ephemeral mode (random IDs, task isolation, session reuse)
  • Managed mode (stable IDs, cross-task identity, profile isolation, post-close reuse)
  • VNC URL discovery (port present/absent/invalid, caching, navigate hint)
  • Config registration (DEFAULT_CONFIG, OPTIONAL_ENV_VARS, ENV_VARS_BY_VERSION)

Pre-Landing Review

Pre-Landing Review: 3 issues (0 critical, 3 auto-fixed)

  • [tools/browser_camofox.py:71] _vnc_url_checked set before resp.json() could fail → moved after parse
  • [tools/browser_camofox.py:73] vncPort accepted without type validation → added int + range check
  • [tests/test_browser_camofox_persistence.py:33] Test fixture missing VNC global cleanup → added

Test plan

  • All persistence tests pass (28 tests)
  • All browser camofox tests pass (83 total)
  • Config tests pass

🤖 Generated with Claude Code

analista and others added 5 commits April 1, 2026 04:21
- Move _vnc_url_checked flag after JSON parse to prevent permanent
  failure when health returns non-JSON body
- Validate vncPort is integer in range 1-65535
- Reset VNC globals in test fixture to prevent order-dependent flakiness
- Add tests for config-yaml toggle, explicit-false env values, VNC URL
  discovery (port present/absent/invalid), and navigate VNC hint

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Enables running arbitrary JS in the page context (e.g. window.scrollBy
for horizontal scrolling, DOM queries for elements outside the
accessibility tree). Wraps the existing /evaluate endpoint in camofox.
call_llm returns a response object with .choices[0].message.content,
not a plain string. Passing the raw object to json.dumps caused
serialization failures, making browser_vision always error out.
The browser_tool default (8K chars) was too aggressive and cut off
sidebar elements like "Add to Watchlist" buttons that appear late in
the accessibility tree. Camofox snapshots rarely exceed 80K chars
(server-side limit), so a 400K char (~100K token) threshold avoids
losing interactive elements while still capping truly huge pages.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant