feat(instrument): browser_use adapter full implementation (replaces placeholder from #116)

[mmercuri]

Summary

Replaces the M7 placeholder shipped in PR #116 (truncation policy) with the full BrowserUseAdapter — every lifecycle hook wired, every event emitted, and every cross-cutting CLAUDE.md contract enforced from day one. Stacks on feat/instrument-truncation-policy (PR #116).

What changed

Full lifecycle adapter (src/layerlens/instrument/adapters/frameworks/browser_use/lifecycle.py)

• connect / disconnect / health_check / get_adapter_info / serialize_for_replay (all five abstract BaseAdapter methods).
• on_session_start, on_session_end, on_navigation, on_action, on_screenshot, on_dom_extraction, on_llm_call (every spec'd hook).
• Capabilities: TRACE_TOOLS + TRACE_MODELS + TRACE_STATE + STREAMING + REPLAY (no longer the placeholder's TRACE_TOOLS-only set).
• Canonical events: browser.session.start, browser.navigate, browser.action, browser.screenshot, browser.dom.extract, tool.call, model.invoke, agent.input/output/state.change, cost.record, environment.config — plus agent.error / tool.error / model.error per the PR feat(instrument): Error-aware event emission on framework exceptions across 10 lighter adapters (cross-poll #2) #115 error-aware emission contract.
• Per-callback resilience wrapper per PR feat(instrument): Per-callback try/except resilience wrapper across 10 lighter adapters (cross-poll #5) #117 — observability errors NEVER crash the customer's agent, surfaced via resilience_snapshot().
• Multi-tenant org_id propagation per PR fix(instrument): Propagate org_id through all event emissions (multi-tenancy CLAUDE.md fix) #118 — bound at construction, stamped defensively on every emit, caller-supplied values overwritten to prevent cross-tenant leaks.
• Truncation policy from day one (DEFAULT_POLICY) — screenshot bytes DROPPED to deterministic SHA-256 references, DOM/HTML capped at 16 KiB.
• requires_pydantic = PydanticCompat.V2_ONLY (browser_use is a v2 library).

Public surface (__init__.py)

• ADAPTER_CLASS = BrowserUseAdapter
• instrument_agent(agent, stratix=, capture_config=, org_id=) one-liner
• STRATIXBrowserUseAdapter legacy alias — fires DeprecationWarning on construction

Pyproject

• Adds browser-use optional extra: browser-use>=0.1.0,<2; python_version >= '3.11'

Tests (40 tests, replaces 7-test scaffold from #116)

Coverage: wiring + alias + lifecycle round-trip + truncation (screenshot drop, hash determinism, HTML cap, short-payload no-audit) + multi-tenancy (kwarg, client attribute, defensive overwrite) + resilience (poison stratix, exploding agent attribute access) + error-aware emission (agent.error / tool.error / model.error) + per-hook coverage + sync + async wrapping + replay round-trip + 10-case provider detection table.

Sample (samples/instrument/browser_use/)

Runs OFFLINE — no browser-use install, no Playwright, no API key, no network. Three-step duck-typed agent + happy/--fail paths exercise the full event surface.

Doc (docs/adapters/frameworks-browser_use.md)

Install + quickstart + capability matrix + 14-event reference + truncation table + multi-tenancy + resilience + error-aware emission + capture config + browser_use specifics + BYOK + replay.

Manifest

Promoted browser_use from _LIFECYCLE_PREVIEW to _MATURE — every required artifact (test file with >= 12 funcs, sample, doc, STRATIX→LayerLens deprecation alias) ships in this PR.

Test plan

• uv run pytest tests/instrument/adapters/frameworks/test_browser_use_adapter.py -x → 40 passed
• mypy --strict src/layerlens/instrument/adapters/frameworks/browser_use → Success: no issues found in 2 source files
• ruff check on src + test + script → All checks passed!
• Sample runs cleanly offline (happy + --fail)
• pip install -e .[browser-use] resolves cleanly
• test_manifest_consistency.py::test_mature_adapters_have_required_artifacts[browser_use] passes
• Full instrument suite: 312 passed, 1 skipped, 12 xfailed (lazy_imports + bulk smoke skipped — pre-existing references to crewai/protocols not on this branch)