Integration request: deeper Stagehand adapter

[aaronlab]

BrowserTrace has a lightweight Stagehand page wrapper today, plus a no-network example in examples/stagehand_wrapper_example.py. The next useful step is a deeper adapter shaped by real Stagehand failure cases.

Guide:
https://aaronlab.github.io/browsertrace/stagehand-debugging.html

Current support:

• browsertrace.integrations.stagehand.wrap_stagehand wraps Stagehand-style page calls.
• Records goto, act, extract, observe, and click as BrowserTrace steps.
• Captures URL, screenshot when available, action name, method args/kwargs, status, and errors.
• Keeps Stagehand optional, not part of the base install.

For public sharing, use:

browsertrace export <run_id> --public -o public.html

--public omits prompt/model I/O, screenshots, and URLs from the standalone HTML export.

Feedback wanted from Stagehand users:

• Which Stagehand failure was hardest to debug?
• Should BrowserTrace capture observe output, selected elements, extracted text, agent state, action retries, screenshots, or model output?
• Which Stagehand hooks are stable enough to wrap without a hard dependency?
• Would a portable HTML export be enough to share a failed Stagehand run, or do you need hosted links?

A good first PR should keep Stagehand optional, include tests with fake Stagehand-shaped objects, and avoid network/API-key requirements.

[aaronlab]

Progress update: 4460ddc adds successful Stagehand wrapper return values to the recorded trace step as model_output. This makes observe / extract style results visible in BrowserTrace exports while keeping Stagehand optional and tested with fake Stagehand-shaped objects.

Also updated README, the Stagehand guide, and CHANGELOG.

Local verification before push: uv run --python 3.11 --extra dev pytest -q -> 100 passed.

[aaronlab]

Opened a Stagehand community feedback thread for BrowserTrace's Stagehand wrapper:\n\nhttps://github.com/browserbase/stagehand/discussions/2102\n\nThe post asks Stagehand users which failure artifacts matter most: observe output, selected elements, extracted text, agent state, action retries, screenshots, model output, task prompt, or other fields. It does not ask for stars or upvotes.

[aaronlab]

Stagehand community feedback update (2026-05-10): posted a targeted technical reply in browserbase/stagehand#2005 about a small observe -> selector -> selector-scoped extract external evidence seam.

Reply: browserbase/stagehand#2005 (comment)

Why it matters for this issue:

• The discussion is directly about the smallest honest Stagehand surface for external evidence consumers.
• The reply frames observe / selector anchor / scoped extract as useful provenance without importing DOM snapshots, screenshots, or full runtime state by default.
• This maps cleanly to a future deeper BrowserTrace Stagehand adapter: capture Stagehand call boundaries, selected anchors/selectors, structured outputs, status, and errors first; widen only when real failures show a missing artifact.

No stars/upvotes were requested. This was a technical feedback reply only.

[aaronlab]

Community feedback update (2026-05-10): browserbase/stagehand#2005 produced a useful confirmation for the small evidence seam around .

External thread:
browserbase/stagehand#2005 (comment)

Follow-up guardrail added:
browserbase/stagehand#2005 (reply in thread)

Takeaway for this adapter: preserve Stagehand call boundaries for debugging, but keep any future lower-noise evidence reducer separate from audit/replay capture. If reducer support is added, tie the selected selector/anchor and extraction schema hash/version to the same observation attempt or run id.

[aaronlab]

Community feedback update (2026-05-10): browserbase/stagehand#2005 produced a useful confirmation for the small evidence seam around observe -> selected selector/anchor -> selector-scoped extract result -> status/error.

External thread:
browserbase/stagehand#2005 (comment)

Follow-up guardrail added:
browserbase/stagehand#2005 (reply in thread)

Takeaway for this adapter: preserve Stagehand call boundaries for debugging, but keep any future lower-noise evidence reducer separate from audit/replay capture. If reducer support is added, tie the selected selector/anchor and extraction schema hash/version to the same observation attempt or run id.

[aaronlab]

Progress update: #238 was merged on 2026-05-10. It adds a compact stagehand_evidence summary for Stagehand observe/action-shaped results, extracting selector, description, and method values beside the existing recorded result.

Why it matters for this adapter: Stagehand users can now inspect the small evidence surface around an observation or action without digging through the full raw result. This keeps Stagehand optional and continues the narrow evidence-boundary approach for the deeper adapter.

Verification before merge:

• uv run --python 3.11 --extra dev pytest tests/test_stagehand_integration.py -q -> 3 passed
• uv run --python 3.11 --extra dev pytest -q -> 326 passed
• uv build -> wheel and sdist built
• Main CI after merge: success for Python 3.11, 3.12, 3.13, and package build

Keeping this issue open for deeper Stagehand adapter feedback, especially around selected anchors/selectors, scoped extract results, retry state, screenshots, and error boundaries.

[aaronlab]

Release update: the Stagehand evidence summary from #238 is now published in browsertrace==0.1.17.

Quick trial path:

uvx --from "browsertrace[ui]" browsertrace doctor
uvx --from "browsertrace[ui]" browsertrace demo
uvx --from "browsertrace[ui]" browsertrace

Persistent install:

pip install "browsertrace[ui]"

Release: https://github.com/aaronlab/browsertrace/releases/tag/v0.1.17
PyPI: https://pypi.org/project/browsertrace/

Still looking for real Stagehand failure shapes where the compact stagehand_evidence surface is not enough: selected anchors/selectors, scoped extract results, retry state, screenshots, model output, task prompt, or error boundaries.

[aaronlab]

Stagehand adapter research note (2026-05-11): browserbase/stagehand#1635 is a useful open failure shape to keep in mind for the deeper adapter.

External issue:
browserbase/stagehand#1635

Relevant signal:

• The report is about CUA agent screenshot timing around custom tools.
• The failure mode is not just "did an action run?" but "which screenshot did the model receive before and after a tool/action?"
• The existing Stagehand maintainer reply points toward returning a screenshot as part of custom-tool output or forcing a screenshot after tool calls.

Implication for BrowserTrace:

• Do not claim the current Python wrap_stagehand solves this TypeScript CUA path.
• A future deeper adapter should distinguish before_action_screenshot and after_tool_screenshot when the framework exposes both.
• Trace rows should preserve screenshot capture timestamp, action/tool name, tool result, URL, status/error, and any selected selector/anchor so a user can compare what the model believed against the actual browser state.
• If TypeScript Stagehand support is considered later, the smallest useful diagnostic surface is likely custom-tool boundary + screenshot id/digest/timestamp + returned tool output, not a full runtime recorder.

No external reply posted for now; this is internal adapter research until there is a concrete implementation or a direct maintainer ask.

[aaronlab]

Stagehand adapter research note (2026-05-11): browserbase/stagehand#1558 is a useful custom-tool replay/cache failure shape.

External thread:
browserbase/stagehand#1558 (comment)

Relevant signal:

• The failure is not just whether a browser action can be replayed; custom tools can mutate page state, fill credentials, or call side-effectful code outside normal act / goto / scroll steps.
• A cache/replay system needs to distinguish replay-safe tool calls from diagnostic-only tool boundaries.
• Silent skipping is especially risky because later browser clicks may run against missing page state.

Implication for BrowserTrace / future Stagehand support:

• Preserve custom-tool boundaries as trace steps when the framework exposes them.
• Useful fields: tool name, redacted argument summary, result summary, status/error, step id, timestamp, URL or page id before/after, and optional screenshot/observation ids before/after.
• Do not store raw credentials or sensitive tool args by default.
• Treat replayability as a separate opt-in property; a trace can show that a custom tool was non-replay-safe without trying to re-run it.

No stars/upvotes requested. This was a technical design reply only.

[aaronlab]

Stagehand adapter research note (2026-05-11): browserbase/stagehand#1880 is a useful semantic-verification/action-boundary design thread to track.

External thread:
browserbase/stagehand#1880 (comment)

Relevant signal:

• Verification is most useful when it creates an inspectable record, not only a boolean.
• The trace boundary should separate action proposal, evidence used to choose the target, verification result, and execution result.
• Failure classes become measurable: high-confidence proposal + failed verifier, passed verifier + wrong post-action state, ambiguous verifier + unsafe execution, and skipped verifier + later failure.

Implication for BrowserTrace / future Stagehand support:

• Preserve selected selector/role/text, confidence, candidate elements, URL, screenshot or DOM snapshot ids, semantic endpoint evidence, verifier type, verification status/reason, and post-action status/error when exposed.
• Treat blocked or escalated as first-class step outcomes rather than hidden control flow.
• Keep verification evidence linked to the action id so users can inspect why a target was authorized or rejected.

No external engagement request was made. This was a technical design reply only.