ref!: Reduce API to a minimum that makes sense (#2429)

ref
[#1841](#1841)


- Replaced the root `braintrust` export surface with an explicit
allowlist, removing roughly 140 named exports—primarily internal
helpers, implementation classes, schemas, constants, and low-level
types.
- Stopped named-exporting most SDK-owned request/result types. Retained
types are primarily user extension points, including `StartSpanArgs`,
`Span`, tracing context types, eval callbacks, reporters, template
plugins, and durable-eval stores.
- Removed package subpaths `braintrust/browser`, `braintrust/util`, and
`braintrust/webpack-loader`; the util bundle is no longer built or
published.
- Kept the webpack loader private: `braintrust/next` now resolves its
built loader directly instead of exposing it as a package entrypoint.
- Removed public implementation/testing exports such as
`_exportsForTestingOnly`, `_internalIso`, `_internalGetGlobalState`,
`_internalSetInitialState`, `SpanImpl`, `NoopSpan`,
`TestBackgroundLogger`, `ObjectFetcher`, and ID-generator classes.
- Removed public runtime schemas and serialization internals, including
prompt, stream-chunk, attachment-reference, logs-overflow, and
propagation schemas/constants.
- Removed lower-level project/building APIs such as `graph`, `Project`,
`CodeFunction`, `CodePrompt`, `PromptBuilder`, `ScorerBuilder`, and
`ToolBuilder`; the `projects` facade remains.
- Removed miscellaneous convenience and implementation exports including
`log`, `summarize`, `traceable`, `newId`, `permalink`, `deepCopyEvent`,
template-registry internals, span fetchers, and logs-overflow helpers.
- Removed deprecated APIs:
  - `BraintrustMiddleware` and `wrapAISDKModel`
  - `wrapMastraAgent`
  - `withExperiment` and `withDataset`
  - `toAIStreamResponse`
- deprecated bundler aliases `esbuildPlugin`, `rollupPlugin`,
`vitePlugin`, and `webpackPlugin`
  - deprecated `useDiagnosticChannelCompatShim`
  - `Experiment.close()`, `Dataset.close()`, and `Span.close()`
- `EvalHooks.meta`, `EvalResultWithSummary.toString()`, and
`Score.error`
- Removed legacy aliases and call shapes:
  - `initExperiment`
  - string-first `init()` and `initDataset()` overloads
  - dataset `useOutput` mode and the `output` record alias
  - deprecated event `inputs` and `datasetRecordId` fields
  - `wrapOpenAIv4`
- Changed `EvalResultWithSummary` from an exported runtime class to a
plain `{ summary, results }` result shape.
- Restricted public span parenting to opaque `PropagationContext`;
serialized span-slug strings remain internal plumbing. The public type
is still named `StartSpanArgs`.
- Added `configureContextManager()` and
`ContextManager.getCurrentSpanStore()` as the supported context
integration mechanism, replacing global symbols and direct state
mutation.
- Moved instrumentation-only APIs off the root:
- `configureInstrumentation`, `InstrumentationConfig`, and Eve/Flue
instrumentation remain under `braintrust/instrumentation`.
  - `registerOtelFlush` now lives there as the narrow OTEL hook.
- Simplified OTEL integration:
  - Uses `configureContextManager()` instead of internal globals.
  - No longer overrides ID generation or V4 span serialization.
- Replaced `contextFromSpanExport(string)` with `contextFromSpan(span)`.
  - `parentFromHeaders()` now returns opaque W3C propagation context.
- Environment and `.env.braintrust` handling is self-contained and
Edge-safe.
  - Removed the OTEL-specific exported ID generator.
- Migrated Temporal propagation from private serialized span headers to
standard `traceparent`, `tracestate`, and `baggage`, covering
client→workflow, child workflow, and same-/cross-worker activity
parenting.
- Reworked `@braintrust/browser` to install a browser `ContextManager`
through the public configuration API instead of mutating core isomorph
internals.
- Updated OpenAI Agents and the Vercel adapter to avoid
`braintrust/util` and the exported `BraintrustStreamChunk`; the adapter
now derives its stream chunk type from `BraintrustStream`.
- Canonicalized instrumentation config keys by removing typed aliases
such as `vercel`, `google`, `cursor`, `bedrock`, and `awsBedrock`;
environment spellings still map to canonical keys.
- Updated smoke tests, integration tests, Deno/browser coverage, and e2e
scenarios to use only the curated public surface; added explicit tests
for the allowed root types and published package entrypoints.

Author: lforst

.changeset/reduce-api-to-a-minimum.md

@@ -0,0 +1,10 @@
+---
+"braintrust": major
+"@braintrust/otel": major
+"@braintrust/vercel-ai-sdk": major
+"@braintrust/browser": patch
+"@braintrust/openai-agents": patch
+"@braintrust/temporal": patch
+---
+
+ref!: Reduce API to a minimum that makes sense

e2e/package.json

@@ -8,6 +8,7 @@
     "test:e2e:record": "node ./scripts/run-record-tests.mjs"
   },
   "devDependencies": {
+    "@braintrust/browser": "workspace:^",
     "@braintrust/langchain-js": "workspace:^",
     "@braintrust/otel": "workspace:^",
     "@braintrust/seinfeld": "workspace:^",

e2e/scenarios/cloudflare-agents-instrumentation/vite.config.ts

@@ -7,9 +7,7 @@ const agentsPackageName =
 const instrumentationMode =
   process.env.CLOUDFLARE_AGENTS_INSTRUMENTATION_MODE ?? "auto";
 const braintrustPlugins =
-  instrumentationMode === "auto"
-    ? braintrustVitePlugin({ useDiagnosticChannelCompatShim: true })
-    : [];
+  instrumentationMode === "auto" ? braintrustVitePlugin({ browser: true }) : [];
 
 export default defineConfig({
   define: {

e2e/scenarios/cloudflare-ai-chat-instrumentation/vite.config.ts

@@ -25,9 +25,7 @@ export default defineConfig({
     __OPENAI_BASE_URL__: JSON.stringify(process.env.OPENAI_BASE_URL),
   },
   plugins: [
-    ...(mode === "auto"
-      ? [braintrustVitePlugin({ useDiagnosticChannelCompatShim: true })]
-      : []),
+    ...(mode === "auto" ? [braintrustVitePlugin({ browser: true })] : []),
     cloudflare({ configPath: "./wrangler.toml", inspectorPort: 0 }),
   ],
   resolve: {

e2e/scenarios/cloudflare-think-instrumentation/vite.config.ts

@@ -13,9 +13,7 @@ export default defineConfig({
     ),
   },
   plugins: [
-    ...(manual
-      ? []
-      : [braintrustVitePlugin({ useDiagnosticChannelCompatShim: true })]),
+    ...(manual ? [] : [braintrustVitePlugin({ browser: true })]),
     cloudflare({ inspectorPort: 0 }),
   ],
   resolve: {