fix(core): Preserve .withResponse() on Anthropic instrumentation (#19935)

The Anthropic SDK lets you call `.withResponse()` and `.asResponse()` on
the result of `client.messages.create()` (see
https://platform.claude.com/docs/en/api/sdks/typescript#accessing-raw-response-data-e-g-headers).
Our instrumentation was breaking this because the SDK returns a custom
`APIPromise` (a Promise subclass with extra methods) and our wrapping
stripped those methods away.

We had the exact same problem with OpenAI (#19073) and fixed it using a
Proxy that routes `.then/.catch/.finally` to the instrumented promise
(preserving spans) while forwarding SDK-specific methods like
`.withResponse()` to the original. This PR refactors that solution into
a shared utility and applies it to the Anthropic integration for both
non-streaming and streaming paths.

Closes #19912

Author: nicohrubec

dev-packages/node-integration-tests/suites/tracing/anthropic/scenario-with-response.mjs

@@ -0,0 +1,199 @@
+import * as Sentry from '@sentry/node';
+import express from 'express';
+import Anthropic from '@anthropic-ai/sdk';
+
+function startMockAnthropicServer() {
+  const app = express();
+  app.use(express.json());
+
+  app.post('/anthropic/v1/messages', (req, res) => {
+    const model = req.body.model;
+
+    res.set('request-id', 'req_withresponse_test');
+
+    if (req.body.stream) {
+      res.set('content-type', 'text/event-stream');
+      res.flushHeaders();
+
+      const events = [
+        `event: message_start\ndata: ${JSON.stringify({ type: 'message_start', message: { id: 'msg_stream_withresponse', type: 'message', role: 'assistant', model, content: [], usage: { input_tokens: 10 } } })}\n\n`,
+        `event: content_block_start\ndata: ${JSON.stringify({ type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } })}\n\n`,
+        `event: content_block_delta\ndata: ${JSON.stringify({ type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'Streaming with response!' } })}\n\n`,
+        `event: content_block_stop\ndata: ${JSON.stringify({ type: 'content_block_stop', index: 0 })}\n\n`,
+        `event: message_delta\ndata: ${JSON.stringify({ type: 'message_delta', delta: { stop_reason: 'end_turn' }, usage: { output_tokens: 5 } })}\n\n`,
+        `event: message_stop\ndata: ${JSON.stringify({ type: 'message_stop' })}\n\n`,
+      ];
+
+      let i = 0;
+      const interval = setInterval(() => {
+        if (i < events.length) {
+          res.write(events[i]);
+          i++;
+        } else {
+          clearInterval(interval);
+          res.end();
+        }
+      }, 10);
+      return;
+    }
+
+    res.send({
+      id: 'msg_withresponse',
+      type: 'message',
+      model: model,
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: 'Testing .withResponse() method!',
+        },
+      ],
+    });
+  });
+
+  return new Promise(resolve => {
+    const server = app.listen(0, () => {
+      resolve(server);
+    });
+  });
+}
+
+async function run() {
+  const server = await startMockAnthropicServer();
+
+  await Sentry.startSpan({ op: 'function', name: 'main' }, async () => {
+    const client = new Anthropic({
+      apiKey: 'mock-api-key',
+      baseURL: `http://localhost:${server.address().port}/anthropic`,
+    });
+
+    // Test 1: Verify .withResponse() method is preserved and works correctly
+    const result = client.messages.create({
+      model: 'claude-3-haiku-20240307',
+      messages: [{ role: 'user', content: 'Test withResponse' }],
+    });
+
+    // Verify .withResponse() method exists and can be called
+    if (typeof result.withResponse !== 'function') {
+      throw new Error('.withResponse() method does not exist');
+    }
+
+    // Call .withResponse() and verify structure
+    const withResponseResult = await result.withResponse();
+
+    // Verify expected properties are present
+    if (!withResponseResult.data) {
+      throw new Error('.withResponse() did not return data');
+    }
+    if (!withResponseResult.response) {
+      throw new Error('.withResponse() did not return response');
+    }
+    if (withResponseResult.request_id === undefined) {
+      throw new Error('.withResponse() did not return request_id');
+    }
+
+    // Verify returned data structure matches expected Anthropic response
+    const { data } = withResponseResult;
+    if (data.id !== 'msg_withresponse') {
+      throw new Error(`Expected data.id to be 'msg_withresponse', got '${data.id}'`);
+    }
+    if (data.model !== 'claude-3-haiku-20240307') {
+      throw new Error(`Expected data.model to be 'claude-3-haiku-20240307', got '${data.model}'`);
+    }
+    if (data.content[0].text !== 'Testing .withResponse() method!') {
+      throw new Error(
+        `Expected data.content[0].text to be 'Testing .withResponse() method!', got '${data.content[0].text}'`,
+      );
+    }
+
+    // Verify response is a Response object with correct headers
+    if (!(withResponseResult.response instanceof Response)) {
+      throw new Error('response is not a Response object');
+    }
+    if (withResponseResult.response.headers.get('request-id') !== 'req_withresponse_test') {
+      throw new Error(
+        `Expected request-id header 'req_withresponse_test', got '${withResponseResult.response.headers.get('request-id')}'`,
+      );
+    }
+
+    // Verify request_id matches the header
+    if (withResponseResult.request_id !== 'req_withresponse_test') {
+      throw new Error(`Expected request_id 'req_withresponse_test', got '${withResponseResult.request_id}'`);
+    }
+
+    // Test 2: Verify .asResponse() method works
+    const result2 = client.messages.create({
+      model: 'claude-3-haiku-20240307',
+      messages: [{ role: 'user', content: 'Test asResponse' }],
+    });
+
+    // Verify .asResponse() method exists and can be called
+    if (typeof result2.asResponse !== 'function') {
+      throw new Error('.asResponse() method does not exist');
+    }
+
+    // Call .asResponse() and verify it returns raw Response
+    const rawResponse = await result2.asResponse();
+
+    // Verify response is a Response object with correct headers
+    if (!(rawResponse instanceof Response)) {
+      throw new Error('.asResponse() did not return a Response object');
+    }
+
+    // Verify response has correct status
+    if (rawResponse.status !== 200) {
+      throw new Error(`Expected status 200, got ${rawResponse.status}`);
+    }
+
+    // Verify response headers
+    if (rawResponse.headers.get('request-id') !== 'req_withresponse_test') {
+      throw new Error(
+        `Expected request-id header 'req_withresponse_test', got '${rawResponse.headers.get('request-id')}'`,
+      );
+    }
+
+    // Test 3: Verify .withResponse() works with streaming (stream: true)
+    const streamResult = client.messages.create({
+      model: 'claude-3-haiku-20240307',
+      messages: [{ role: 'user', content: 'Test stream withResponse' }],
+      stream: true,
+    });
+
+    if (typeof streamResult.withResponse !== 'function') {
+      throw new Error('.withResponse() method does not exist on streaming result');
+    }
+
+    const streamWithResponse = await streamResult.withResponse();
+
+    if (!streamWithResponse.data) {
+      throw new Error('streaming .withResponse() did not return data');
+    }
+    if (!streamWithResponse.response) {
+      throw new Error('streaming .withResponse() did not return response');
+    }
+    if (streamWithResponse.request_id === undefined) {
+      throw new Error('streaming .withResponse() did not return request_id');
+    }
+
+    if (!(streamWithResponse.response instanceof Response)) {
+      throw new Error('streaming response is not a Response object');
+    }
+    if (streamWithResponse.response.headers.get('request-id') !== 'req_withresponse_test') {
+      throw new Error(
+        `Expected request-id header 'req_withresponse_test', got '${streamWithResponse.response.headers.get('request-id')}'`,
+      );
+    }
+
+    // Consume the stream to allow span to complete
+    for await (const _ of streamWithResponse.data) {
+      void _;
+    }
+  });
+
+  // Wait for the stream event handler to finish
+  await Sentry.flush(2000);
+
+  server.close();
+}
+
+run();

dev-packages/node-integration-tests/suites/tracing/anthropic/test.ts

@@ -359,6 +359,37 @@ describe('Anthropic integration', () => {
     });
   });
 
+  createEsmAndCjsTests(__dirname, 'scenario-with-response.mjs', 'instrument.mjs', (createRunner, test) => {
+    const chatSpan = (responseId: string) =>
+      expect.objectContaining({
+        data: expect.objectContaining({
+          [GEN_AI_OPERATION_NAME_ATTRIBUTE]: 'chat',
+          [GEN_AI_REQUEST_MODEL_ATTRIBUTE]: 'claude-3-haiku-20240307',
+          [GEN_AI_RESPONSE_ID_ATTRIBUTE]: responseId,
+        }),
+        description: 'chat claude-3-haiku-20240307',
+        op: 'gen_ai.chat',
+        status: 'ok',
+      });
+
+    test('preserves .withResponse() and .asResponse() for non-streaming and streaming', async () => {
+      await createRunner()
+        .ignore('event')
+        .expect({
+          transaction: {
+            transaction: 'main',
+            spans: expect.arrayContaining([
+              chatSpan('msg_withresponse'),
+              chatSpan('msg_withresponse'),
+              chatSpan('msg_stream_withresponse'),
+            ]),
+          },
+        })
+        .start()
+        .completed();
+    });
+  });
+
   createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
     test('creates anthropic related spans with sendDefaultPii: false', async () => {
       await createRunner()

packages/core/src/tracing/ai/utils.ts

@@ -1,8 +1,10 @@
 /**
  * Shared utils for AI integrations (OpenAI, Anthropic, Verce.AI, etc.)
  */
+import { captureException } from '../../exports';
 import { getClient } from '../../currentScopes';
 import type { Span } from '../../types-hoist/span';
+import { isThenable } from '../../utils/is';
 import {
   GEN_AI_USAGE_INPUT_TOKENS_ATTRIBUTE,
   GEN_AI_USAGE_OUTPUT_TOKENS_ATTRIBUTE,
@@ -172,3 +174,81 @@ export function extractSystemInstructions(messages: unknown[] | unknown): {
 
   return { systemInstructions, filteredMessages };
 }
+
+/**
+ * Creates a wrapped version of .withResponse() that replaces the data field
+ * with the instrumented result while preserving metadata (response, request_id).
+ */
+async function createWithResponseWrapper<T>(
+  originalWithResponse: Promise<unknown>,
+  instrumentedPromise: Promise<T>,
+  mechanismType: string,
+): Promise<unknown> {
+  // Attach catch handler to originalWithResponse immediately to prevent unhandled rejection
+  // If instrumentedPromise rejects first, we still need this handled
+  const safeOriginalWithResponse = originalWithResponse.catch(error => {
+    captureException(error, {
+      mechanism: {
+        handled: false,
+        type: mechanismType,
+      },
+    });
+    throw error;
+  });
+
+  const instrumentedResult = await instrumentedPromise;
+  const originalWrapper = await safeOriginalWithResponse;
+
+  // Combine instrumented result with original metadata
+  if (originalWrapper && typeof originalWrapper === 'object' && 'data' in originalWrapper) {
+    return {
+      ...originalWrapper,
+      data: instrumentedResult,
+    };
+  }
+  return instrumentedResult;
+}
+
+/**
+ * Wraps a promise-like object to preserve additional methods (like .withResponse())
+ * that AI SDK clients (OpenAI, Anthropic) attach to their APIPromise return values.
+ *
+ * Standard Promise methods (.then, .catch, .finally) are routed to the instrumented
+ * promise to preserve Sentry's span instrumentation, while custom SDK methods are
+ * forwarded to the original promise to maintain the SDK's API surface.
+ */
+export function wrapPromiseWithMethods<R>(
+  originalPromiseLike: Promise<R>,
+  instrumentedPromise: Promise<R>,
+  mechanismType: string,
+): Promise<R> {
+  // If the original result is not thenable, return the instrumented promise
+  if (!isThenable(originalPromiseLike)) {
+    return instrumentedPromise;
+  }
+
+  // Create a proxy that forwards Promise methods to instrumentedPromise
+  // and preserves additional methods from the original result
+  return new Proxy(originalPromiseLike, {
+    get(target: object, prop: string | symbol): unknown {
+      // For standard Promise methods (.then, .catch, .finally, Symbol.toStringTag),
+      // use instrumentedPromise to preserve Sentry instrumentation.
+      // For custom methods (like .withResponse()), use the original target.
+      const useInstrumentedPromise = prop in Promise.prototype || prop === Symbol.toStringTag;
+      const source = useInstrumentedPromise ? instrumentedPromise : target;
+
+      const value = Reflect.get(source, prop) as unknown;
+
+      // Special handling for .withResponse() to preserve instrumentation
+      // .withResponse() returns { data: T, response: Response, request_id: string }
+      if (prop === 'withResponse' && typeof value === 'function') {
+        return function wrappedWithResponse(this: unknown): unknown {
+          const originalWithResponse = (value as (...args: unknown[]) => unknown).call(target);
+          return createWithResponseWrapper(originalWithResponse, instrumentedPromise, mechanismType);
+        };
+      }
+
+      return typeof value === 'function' ? value.bind(source) : value;
+    },
+  }) as Promise<R>;
+}