ref!: Remove flushAsync option

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",

.changeset/remove-flush-async.md

@@ -0,0 +1,5 @@
+---
+"braintrust": major
+---
+
+ref!: Remove `flushAsync` option

e2e/helpers/prod-forwarding.ts

@@ -31,7 +31,6 @@ export async function initializeProdForwarding(): Promise<void> {
  const logger = initLogger({
  apiKey,
  appUrl: process.env.BRAINTRUST_APP_URL,
- asyncFlush: false,
  forceLogin: true,
  projectName,
  });

integrations/langchain-js/src/BraintrustCallbackHandler.ts

@@ -11,23 +11,18 @@ import {
  type LangChainCallbackHandlerOptions,
 } from "braintrust";
 
-type BraintrustCallbackHandlerOptions<IsAsyncFlush extends boolean> =
- LangChainCallbackHandlerOptions<IsAsyncFlush>;
+type BraintrustCallbackHandlerOptions = LangChainCallbackHandlerOptions;
 
 /**
  * A Braintrust tracer for LangChain.js that logs LLM calls, chains, and tools.
  */
-export class BraintrustCallbackHandler<
- IsAsyncFlush extends boolean,
-> extends BaseCallbackHandler {
+export class BraintrustCallbackHandler extends BaseCallbackHandler {
  name = "BraintrustCallbackHandler";
- private inner: BraintrustLangChainCallbackHandler<IsAsyncFlush>;
+ private inner: BraintrustLangChainCallbackHandler;
 
- constructor(
- options?: Partial<BraintrustCallbackHandlerOptions<IsAsyncFlush>>,
- ) {
+ constructor(options?: Partial<BraintrustCallbackHandlerOptions>) {
  super();
- this.inner = new BraintrustLangChainCallbackHandler<IsAsyncFlush>(options);
+ this.inner = new BraintrustLangChainCallbackHandler(options);
  }
 
  handleLLMStart(

integrations/openai-agents-js/src/index.ts

@@ -118,7 +118,7 @@ function getTimeElapsed(end?: string, start?: string): number | undefined {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

integrations/openai-agents-js/src/openai-agents-integration.test.ts

@@ -55,7 +55,7 @@ describe(
  TEST_SUITE_OPTIONS,
  () => {
  let backgroundLogger: TestBackgroundLogger;
- let _logger: Logger<false>;
+ let _logger: Logger;
  let Agent: any;
  let run: any;
  let tool: any;

integrations/openai-agents-js/src/types.ts

@@ -50,7 +50,7 @@ export type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 

js/src/exports.ts

@@ -31,13 +31,11 @@ export type {
  InitLoggerOptions,
  InitOptions,
  LoadPromptOptions,
- LogOptions,
  LoginOptions,
  Logs3OverflowInputRow,
  Logs3OverflowUpload,
  MetricSummary,
  ObjectMetadata,
- PromiseUnless,
  PropagationContext,
  PromptRowWithId,
  ScoreSummary,
@@ -125,7 +123,6 @@ export {
  withCurrent,
  withDataset,
  withExperiment,
- withLogger,
  withParent,
  wrapTraced,
  registerOtelFlush,

js/src/instrumentation/providers/eve-instrumentation.ts

@@ -585,7 +585,7 @@ class EveBridge {
  turn: TurnState,
  event: { input?: unknown; output?: unknown },
  ): void {
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  root_span_id: turn.rootSpanId,
  span_id: turn.spanId,
@@ -637,7 +637,7 @@ class EveBridge {
  if (Object.keys(totals).length === 0) {
  return;
  }
- currentLogger<true>()?.updateSpan({
+ currentLogger()?.updateSpan({
  id: turn.rowId,
  metrics: totals,
  root_span_id: turn.rootSpanId,

js/src/instrumentation/providers/openai-agents-trace-processor.ts

@@ -44,7 +44,7 @@ type TraceMetadata = {
 };
 
 export interface OpenAIAgentsTraceProcessorOptions {
- logger?: Logger<any>;
+ logger?: Logger;
  maxTraces?: number;
 }
 
@@ -180,7 +180,7 @@ function parseUsageMetrics(usage: unknown): Record<string, number> {
 export class OpenAIAgentsTraceProcessor {
  private static readonly DEFAULT_MAX_TRACES = 10000;
 
- private logger?: Logger<any>;
+ private logger?: Logger;
  private maxTraces: number;
  private traceSpans = new Map<
  string,

js/src/logger.test.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/consistent-type-assertions */
 
-import { vi, expect, test, describe, beforeEach, afterEach } from "vitest";
+import {
+ vi,
+ expect,
+ expectTypeOf,
+ test,
+ describe,
+ beforeEach,
+ afterEach,
+} from "vitest";
 import {
  _exportsForTestingOnly,
  init,
@@ -11,6 +19,7 @@ import {
  loadPrompt,
  loadParameters,
  wrapTraced,
+ traced,
  currentSpan,
  withParent,
  startSpan,
@@ -19,6 +28,8 @@ import {
  deepCopyEvent,
  ReadonlyExperiment,
  renderMessageImpl,
+ flush,
+ type InitLoggerOptions,
 } from "./logger";
 
 import { configureNode } from "./node/config";
@@ -31,6 +42,12 @@ import { SpanCache } from "./span-cache";
 
 configureNode();
 
+type InitLoggerHasAsyncFlush = "asyncFlush" extends keyof InitLoggerOptions
+ ? true
+ : false;
+
+expectTypeOf<InitLoggerHasAsyncFlush>().toEqualTypeOf<false>();
+
 test("renderMessage with file content parts", () => {
  const message = {
  role: "user" as const,
@@ -426,6 +443,57 @@ test("verify MemoryBackgroundLogger intercepts logs", async () => {
  _exportsForTestingOnly.clearTestBackgroundLogger(); // can go back to normal
 });
 
+test("logger and tracing APIs preserve return shapes without implicit flushing", async () => {
+ await _exportsForTestingOnly.simulateLoginForTests();
+ const backgroundLogger = _exportsForTestingOnly.useTestBackgroundLogger();
+ const flushSpy = vi.spyOn(backgroundLogger, "flush");
+
+ try {
+ const logger = initLogger({
+ projectName: "test",
+ projectId: "test-project-id",
+ });
+
+ const id = logger.log({ input: "input" });
+ expectTypeOf(id).toEqualTypeOf<string>();
+
+ const loggerSyncResult = logger.traced(() => 42 as const);
+ expectTypeOf(loggerSyncResult).toEqualTypeOf<42>();
+ expect(loggerSyncResult).toBe(42);
+
+ const loggerAsyncResult = logger.traced(async () => 43);
+ expectTypeOf(loggerAsyncResult).toEqualTypeOf<Promise<number>>();
+ await expect(loggerAsyncResult).resolves.toBe(43);
+
+ const tracedSyncResult = traced(() => "sync" as const);
+ expectTypeOf(tracedSyncResult).toEqualTypeOf<"sync">();
+ expect(tracedSyncResult).toBe("sync");
+
+ const syncFunction = (value: number) => value + 1;
+ const wrappedSyncFunction = wrapTraced(syncFunction);
+ expectTypeOf(wrappedSyncFunction).toEqualTypeOf<typeof syncFunction>();
+ expect(wrappedSyncFunction(1)).toBe(2);
+
+ const asyncFunction = async (value: number) => value + 1;
+ const wrappedAsyncFunction = wrapTraced(asyncFunction);
+ expectTypeOf(wrappedAsyncFunction).toEqualTypeOf<typeof asyncFunction>();
+ await expect(wrappedAsyncFunction(2)).resolves.toBe(3);
+
+ expect(flushSpy).not.toHaveBeenCalled();
+
+ await logger.flush();
+ const span = logger.startSpan({ name: "explicit-flush" });
+ span.end();
+ await span.flush();
+ await flush();
+
+ expect(flushSpy).toHaveBeenCalledTimes(3);
+ } finally {
+ _exportsForTestingOnly.clearTestBackgroundLogger();
+ _exportsForTestingOnly.simulateLogoutForTests();
+ }
+});
+
 test("init validation", () => {
  expect(() => init({})).toThrow(
  "Must specify at least one of project or projectId",