feat: Add eve first party eve instrumentation

.agents/skills/instrumentation/SKILL.md

@@ -36,6 +36,7 @@ Map the change before editing:
 - Promise/stream behavior must be preserved. Patches need to keep subclass/helper semantics intact.
 - Contain instrumentation failures. Extraction/logging bugs should be logged or ignored as appropriate, but must not break the user call path.
 - Use the SDK `debugLogger` for SDK instrumentation diagnostics. Do not call `console.*` directly from instrumentation code; direct console use should stay inside the debug logger implementation or another explicitly justified exception.
+- Pass `Error` objects directly as `span.log({ error })` values. The SDK serializes errors correctly, so do not add local helpers that manually turn errors into message/stack strings unless an external API requires a non-`Error` representation.
 - Log only the useful surface. Prefer narrow, stable payloads over dumping full request/response objects; exclude redundant or overly large data when possible.
 - We want to limit our instrumentation to operations that are relevant for AI generations and operations (LLMs, embeddings, media generation, ...). Things like creating entities on platforms (CRUD for Workflows of Agent entities) is irrelevant to us.
 - When building instrumentation, we should always have a vendored type/interface for what we are wrapping. The type or interface should not be larger than what is relevant to the instrumentation. The type or interface should be used for typing tracing channels and also should be used to assert the type on whatever is passed into wrappers as soon as the wrapper has verified that the passed in value is plausibly what should be wrapped.

.changeset/eve-instrumentation.md

@@ -0,0 +1,5 @@
+---
+"braintrust": patch
+---
+
+feat: Add Eve instrumentation helpers for Braintrust tracing

e2e/config/pr-comment-scenarios.json

@@ -224,6 +224,12 @@
       { "variantKey": "flue-v1-0-0-beta-3", "label": "v1.0.0-beta.3" }
     ]
   },
+  {
+    "scenarioDirName": "eve-instrumentation",
+    "label": "Eve Instrumentation",
+    "metadataScenario": "eve-instrumentation",
+    "variants": [{ "variantKey": "eve-v0-20-0", "label": "v0.20.0" }]
+  },
   {
     "scenarioDirName": "github-copilot-instrumentation",
     "label": "GitHub Copilot SDK Instrumentation",

e2e/scenarios/eve-instrumentation/agent/agent.ts

@@ -0,0 +1,13 @@
+import { defineAgent } from "eve";
+import { createOpenAI } from "@ai-sdk/openai";
+
+const openai = createOpenAI({
+  ...(process.env.OPENAI_BASE_URL
+    ? { baseURL: process.env.OPENAI_BASE_URL }
+    : {}),
+});
+
+export default defineAgent({
+  model: openai("gpt-5.4-mini"),
+  modelContextWindowTokens: 8_192,
+});

e2e/scenarios/eve-instrumentation/agent/hooks/braintrust.ts

@@ -0,0 +1,15 @@
+import { braintrustEveHook } from "braintrust";
+import { defineState } from "eve/context";
+import { defineHook } from "eve/hooks";
+
+export default defineHook(
+  braintrustEveHook({
+    defineState,
+    metadata: {
+      scenario: "eve-instrumentation",
+      ...(process.env.BRAINTRUST_E2E_RUN_ID
+        ? { testRunId: process.env.BRAINTRUST_E2E_RUN_ID }
+        : {}),
+    },
+  }),
+);

e2e/scenarios/eve-instrumentation/agent/instructions.md

@@ -0,0 +1,11 @@
+You are a deterministic fixture agent for Braintrust Eve instrumentation tests.
+
+For every user task:
+
+1. Call the researcher subagent exactly once with the full user message as the
+   message.
+2. After the researcher result is available, call the read tool exactly once with
+   the URL https://eve.dev/docs/guides/instrumentation.
+3. After the read result is available, answer with a single sentence that starts
+   with "Final answer from read:" and includes the researcher result, read title,
+   URL, and read excerpt.

e2e/scenarios/eve-instrumentation/agent/instrumentation.ts

@@ -0,0 +1,14 @@
+import { braintrustEveInstrumentation, initLogger } from "braintrust";
+import { defineState } from "eve/context";
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation(
+  braintrustEveInstrumentation({
+    defineState,
+    setup: ({ agentName }) => {
+      initLogger({
+        projectName: process.env.BRAINTRUST_E2E_PROJECT_NAME || agentName,
+      });
+    },
+  }),
+);

e2e/scenarios/eve-instrumentation/agent/subagents/researcher/agent.ts

@@ -0,0 +1,15 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import { defineAgent } from "eve";
+
+const openai = createOpenAI({
+  ...(process.env.OPENAI_BASE_URL
+    ? { baseURL: process.env.OPENAI_BASE_URL }
+    : {}),
+});
+
+export default defineAgent({
+  description:
+    "Research the Eve instrumentation documentation before the parent reads it.",
+  model: openai("gpt-5.4-mini"),
+  modelContextWindowTokens: 8_192,
+});

e2e/scenarios/eve-instrumentation/agent/subagents/researcher/hooks/braintrust.ts

@@ -0,0 +1,15 @@
+import { braintrustEveHook } from "braintrust";
+import { defineState } from "eve/context";
+import { defineHook } from "eve/hooks";
+
+export default defineHook(
+  braintrustEveHook({
+    defineState,
+    metadata: {
+      scenario: "eve-instrumentation",
+      ...(process.env.BRAINTRUST_E2E_RUN_ID
+        ? { testRunId: process.env.BRAINTRUST_E2E_RUN_ID }
+        : {}),
+    },
+  }),
+);

e2e/scenarios/eve-instrumentation/agent/subagents/researcher/instructions.md

@@ -0,0 +1,7 @@
+You are the deterministic researcher subagent for Braintrust Eve instrumentation tests.
+
+For every task:
+
+1. Call the search tool exactly once with the full task as the query.
+2. After the search result is available, answer with a single sentence that starts
+   with "Researcher result:" and includes the search title and URL.

e2e/scenarios/eve-instrumentation/agent/subagents/researcher/tools/search.ts

@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Searches the Eve instrumentation documentation fixture.",
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+  async execute({ query }) {
+    return {
+      query,
+      title: "Eve instrumentation",
+      url: "https://eve.dev/docs/guides/instrumentation",
+    };
+  },
+});

e2e/scenarios/eve-instrumentation/agent/tools/read.ts

@@ -0,0 +1,18 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Reads a deterministic Eve documentation page fixture.",
+  inputSchema: z.object({
+    url: z.string(),
+  }),
+  async execute({ url }) {
+    return {
+      excerpt:
+        "Eve hooks expose runtime stream events that Braintrust maps into a nested turn trace.",
+      section: "Runtime context",
+      title: "Eve instrumentation",
+      url,
+    };
+  },
+});

e2e/scenarios/eve-instrumentation/agent/tools/search.ts

@@ -0,0 +1,16 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Searches the Eve instrumentation documentation fixture.",
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+  async execute({ query }) {
+    return {
+      query,
+      title: "Eve instrumentation",
+      url: "https://eve.dev/docs/guides/instrumentation",
+    };
+  },
+});

e2e/scenarios/eve-instrumentation/cassette-filter.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+export { filter } from "../ai-sdk-instrumentation/cassette-filter.mjs";
+
+/** @type {import("@braintrust/seinfeld").RedactionSpec} */
+export const redact = [
+  "paranoid",
+  {
+    redactResponse(response) {
+      return {
+        ...response,
+        headers: Object.fromEntries(
+          Object.entries(response.headers).filter(
+            ([key]) =>
+              key.toLowerCase() !== "openai-organization" &&
+              key.toLowerCase() !== "openai-project",
+          ),
+        ),
+      };
+    },
+  },
+];

e2e/scenarios/eve-instrumentation/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "eve-instrumentation-scenario",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@ai-sdk/openai": "4.0.0-beta.44",
+    "eve": "0.20.0",
+    "zod": "4.3.6"
+  }
+}