feat(evals): bump braintrust to 3.x; first-party BraintrustSpanProcessor OTEL sink

[miguelg719]

why

@braintrust/otel requires braintrust>=1.0 (every published version), so the pinned 0.4.x blocked the first-party OTEL processor. 3.x unlocks it — richer ai.* span handling than a generic OTLP exporter.

what changed

• braintrust ^0.4.10 → ^3.21.0 (all used exports verified intact: Eval, flush, traced, wrapAISDK, loginToState); @braintrust/otel added
• framework/otel.ts: Braintrust sink → BraintrustSpanProcessor({ apiKey, parent, filterAISpans: false }) (false so manual task/agent/verifier spans reach Braintrust too); BRAINTRUST_OTEL_URL → apiUrl
• lib/AISdkClientWrapped.ts: typing-only fix (ReturnType<wrapAISDK> collapses in 3.x) — no runtime change
• Dead @opentelemetry/exporter-trace-otlp-proto dep removed

test plan

• Unit suite 362/362; typecheck/lint green; runtime import smokes (braintrust exports, processor instantiation)
• Manual: native eval run on 3.x; evals experiments against live Braintrust (report-layer parity); dual-backend otel run (env: browserbase)

Stack 5/5 · base: #2354

---

Summary by cubic

Upgrade braintrust to 3.x and switch our OTEL sink to the first‑party BraintrustSpanProcessor. This improves ai.* span capture, removes the generic OTLP exporter, and updates tests to cover parent override and BRAINTRUST_OTEL_URL → apiUrl derivation.

• New Features

  • Use BraintrustSpanProcessor({ apiKey, parent, filterAISpans: false }) for Braintrust traces.
  • If BRAINTRUST_OTEL_URL is set, derive apiUrl by stripping /otel/v1/traces. Tests mock BraintrustSpanProcessor and assert this derivation.

• Dependencies

  • Bump braintrust from ^0.4.10 to ^3.21.0.
  • Add @braintrust/otel ^0.2.1.
  • Remove @opentelemetry/exporter-trace-otlp-proto.
  • Type-only update in AISdkClientWrapped for wrapAISDK return shape (no runtime change).

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: e1169ec

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]

All reported issues were addressed across 6 files

Confidence score: 5/5

• Safe to merge after the addressed issues were fixed.

Architecture diagram

sequenceDiagram
    participant App as otel.ts (initializeTracerProvider)
    participant Provider as NodeTracerProvider
    participant Processor as BraintrustSpanProcessor
    participant BraintrustAPI as Braintrust API

    Note over App,BraintrustAPI: NEW: First‑party span processor replaces generic OTLP exporter

    App->>App: Read BRAINTRUST_API_KEY
    alt API key present
        App->>App: Derive project name (stagehand/stagehand-dev) from CI flag
        App->>App: Read BRAINTRUST_OTEL_PARENT (default: project_name:…)
        App->>App: Read BRAINTRUST_OTEL_URL
        opt BRAINTRUST_OTEL_URL set
            App->>App: Strip suffix /otel/v1/traces to get apiUrl
        end
        App->>Processor: new BraintrustSpanProcessor({apiKey, parent, filterAISpans: false, apiUrl?})
        Note over Processor: filterAISpans: false ensures manual spans (task/agent/verifier) reach Braintrust
        Processor->>BraintrustAPI: Authenticate with apiKey
        App->>Provider: addSpanProcessor(Processor)
    end
    Note over App: Also still configures LangSmith exporter if enabled

    Note over Provider,BraintrustAPI: During evaluation run
    Provider->>Processor: onStart(span)
    Processor->>Processor: Check filterAISpans (false → always pass)
    Processor->>Processor: Enrich span with parent context
    loop Every batch or scheduled flush
        Processor->>BraintrustAPI: Export spans (via Braintrust OTLP endpoint)
        BraintrustAPI-->>Processor: Acknowledge
    end
    Provider->>Processor: shutdown()
    Processor->>BraintrustAPI: Final flush
    BraintrustAPI-->>Processor: Complete

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[miguelg719]

Superseded by the Stagehand 4.0 retarget stack (#2757–#2762). Main moved to the 4.0 monorepo restructure (packages/core → packages/sdk-ts; evals package restructured), so this 3.x-era diff no longer applies. The OTEL/LangSmith tracing work — plus native-span capture via 4.0's global tracer and claude_code/codex agent spans — is reimplemented additively on 4.0 in the new stack.