Add CrawlDex preflight reporting example

[adambot-droid]

PR: Add opt-in CrawlDex preflight and redacted reporting example

Summary

This PR adds a Stagehand example for users who want to set crawldex: true, preflight a web task against CrawlDex, and optionally submit a redacted outcome report after the run.

Why

CrawlDex is a public reliability index for AI agents using websites. The current corpus has 2,354 accepted observations across 17 categories, with roughly 60% of common web tasks requiring a human handoff. Stagehand is a natural place to make that signal available before an agent acts.

What changes

• Adds packages/core/examples/integrations/crawldex-preflight-report.ts.
• Demonstrates createReporter(...), preflight(site, task), and reportStagehandRun(...).
• Keeps the integration off unless crawldex: true is set by the caller.

Safety

• Fail-open: CrawlDex warnings never break the Stagehand task.
• Evidence is summarized into redacted signals; raw prompts, screenshots, page text, cookies, storage, and form values are not uploaded.
• Self-registered reports are attributed but score-neutral until CrawlDex verifies the reporter.
• The example stops before final confirmation and includes no bypass instructions for CAPTCHA, MFA, anti-bot controls, paywalls, or account controls.

Test plan

• git apply --check docs/integrations/stagehand.patch against Stagehand commit 4ee8d99.
• npx --yes prettier@3.2.5 --check packages/core/examples/integrations/crawldex-preflight-report.ts.
• Verified crawldex-report@0.1.0 is live on npm and clean-imports the Stagehand adapter.
• Additive example only; no production behavior changes.

---

Summary by cubic

Adds an opt‑in example that preflights Stagehand tasks with CrawlDex and optionally submits a redacted outcome report. It’s fail‑open and does not change production behavior.

• New Features
  • Adds packages/core/examples/integrations/crawldex-preflight-report.ts.
  • Demonstrates createReporter(...), preflight(site, task), and reportStagehandRun(...) from crawldex-report.
  • Opt-in via crawldex: true; warnings are logged and never block runs.
  • Reporting sends redacted signals only; no raw prompts/screenshots/page text.
  • Sample flow stops before final confirmation; no CAPTCHA/MFA/paywall bypass.

^{Written for commit a16890e. Summary will update on new commits.}

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a16890e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 1 file

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Code as User Script (runSubscriptionCancellation)
    participant Reporter as CrawlDex Reporter (crawldex-report)
    participant CrawlDex as CrawlDex API
    participant Stagehand as Stagehand Runtime

    Note over Code, Stagehand: CrawlDex Preflight and Reporting Example

    Code->>Reporter: createReporter({reportUrl, agentKey})
    Reporter-->>Code: reporter instance

    alt crawldex: true
        Code->>Reporter: preflight(site, task)
        Reporter->>CrawlDex: Preflight request (site, task)
        CrawlDex-->>Reporter: {verdict, warning}
        Reporter-->>Code: preflight result

        Note over Code: Fail‑open: always continue, never block
        opt preflight.warning exists
            Code->>Code: console.warn(preflight.warning)
        end
        opt verdict is "avoid_until_fresh_evidence" or "collect_evidence_first"
            Code->>Code: console.warn("CrawlDex recommends caution")
        end

        Code->>Reporter: reportStagehandRun({reporter, stagehand, site, task, ...})
        Reporter->>Stagehand: run({page, mark})
        Stagehand->>Stagehand: goto, act("Open subscription settings")
        Stagehand->>Reporter: mark("subscription_settings_visible")
        Stagehand->>Stagehand: act("Start cancellation, stop before confirmation")
        Stagehand->>Reporter: mark("cancel_flow_reached")
        Stagehand-->>Reporter: {outcome, friction, evidenceSignals}

        Note over Reporter: Build redacted report (no raw prompts, screenshots, page text)
        Reporter->>CrawlDex: Submit report (redacted signals)
        CrawlDex-->>Reporter: Ack
        Reporter-->>Code: return value (outcome + metadata)

    else crawldex: false
        Code->>Stagehand: goto("https://example.com/account")
        Stagehand->>Stagehand: act steps (no CrawlDex interaction)
        Stagehand-->>Code: {outcome: "success_with_handoff"}
    end

Loading

_{Re-trigger cubic}