fix(node): Preserve CallbackManager handlers in LangChain instrumentation

[mdnanocom]

Summary

augmentCallbackHandlers in packages/node/src/integrations/tracing/langchain/instrumentation.ts previously fell into its typeof handlers === 'object' branch whenever options.callbacks was a single object and wrapped it into [handlers, sentryHandler]. When that object was a LangChain CallbackManager, downstream code treats the whole manager as one opaque handler — its inheritable children (notably LangGraph's StreamMessagesHandler installed by streamMode: ['messages'], and the LangSmith tracer) are never unpacked, so per-token streaming events and nested tracing silently disappear.

This PR detects CallbackManager via duck-typing (avoids coupling to a specific @langchain/core resolution) and registers Sentry's handler as an inheritable child on a copy via .addHandler(handler, true). The manager's existing children continue to receive handleLLMNewToken and friends.

Repro

A LangGraph compiled graph + ChatOpenAI (or any LangChain provider with bindTools(...)), driven through @ai-sdk/langchain's toUIMessageStream:

const stream = await graph.stream(
  { messages },
  { streamMode: ['values', 'messages'] },
);
return createUIMessageStreamResponse({ stream: toUIMessageStream(stream) });

• Without this fix: the SSE output collapses to a single aggregated text-delta at end of run. Probing inside _streamResponseChunks shows the per-token chunks fire runManager.handleLLMNewToken correctly, but the LLM-level run-manager's handlers list contains only [CallbackManager, SentryCallbackHandler, langchain_tracer] — StreamMessagesHandler is missing.
• With this fix: every token is delivered as the model produces it (verified end-to-end against gpt-5.5 + useResponsesApi: true + bindTools and against gpt-4o-mini with no tools).

Tests

Added packages/node/test/integrations/tracing/langchain.test.ts with 7 unit tests covering:

• undefined callbacks → single-handler array
• pre-existing array → append (idempotent)
• CallbackManager → preserves children, copies rather than mutates, deduplicates
• opaque non-manager object → returned unchanged

Verify

• Added unit tests for the fixed behaviour
• yarn build succeeds
• yarn test:unit passes (381/381 in packages/node)
• No related issue currently open — happy to open one if preferred.

[mdnanocom]

Thanks for the review — wanted to share what I found before pushing the fix.

Tracing through @langchain/core@1.1.39's CallbackManager:

• addHandler(handler, true) pushes to both handlers and inheritableHandlers.
• setHandlers(handlers, inherit=true) (used by getChild) clears both arrays, then calls addHandler(_, true) for each — so it also keeps both in sync.

That means in normal operation inheritableHandlers ⊆ handlers, and copied.handlers.includes(sentryHandler) already catches the nested-call case the bot describes. I don't think I can reproduce the duplicate-registration in practice with the stock CallbackManager.

That said, the suggested fix costs nothing and pre-empts the failure mode for any externally-constructed subclass that bypasses addHandler. Pushed it as commit 4c74bfa with a regression test (does not double-register when the handler lives only on inheritableHandlers) — and an explanatory comment on the dedupe so the reasoning doesn't decay.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b33352b. Configure here.}

[mdnanocom]

Done in 7d61cf5b (pushed). Lifted the fixed implementation to @sentry/core as mergeSentryCallback and routed both @sentry/instrumentation-langchain and @sentry/instrumentation-langgraph through it. The langgraph integration silently picks up the streaming fix as a bonus — the existing helper had the same three bugs (mutates caller manager, no inherit=true, dedupes only against handlers).

Net: 5 files, +163 / -215. Coverage is now in a single mergeSentryCallback suite (14 cases). 13/13 node tracing files (270 tests) and 83/83 core utils files (1439 tests) pass.

[JPeer264]

m: Is it 100% guaranteed that this works? addHandler and copy seem to be a little vague to check against these. Since CallbackManager is a class, maybe there is the possibility to check against its name?

We do something similar in Cloudflare:

sentry-javascript/packages/cloudflare/src/utils/isCloudflareClass.ts

Lines 38 to 61 in 62096ee

	export function isCloudflareClass(value: unknown, className: CloudflareClassName): boolean {
	if (!value || typeof value !== 'function') {
	return false;
	}
	if (value.name === className) {
	return false;
	}
	let proto: object | null = value.prototype;
	while (proto) {
	const ctor = (proto as { constructor?: { name?: string } }).constructor;
	const constructorName = ctor?.name;
	if (constructorName === className) {
	return true;
	}
	proto = Object.getPrototypeOf(proto);
	}
	return false;
	}

[mdnanocom]

Done, adopted the Cloudflare pattern: walk the prototype chain looking for constructor.name === 'CallbackManager', then confirm the shape.

[JPeer264]

l: I wonder if this was missed to be removed when mergeSentryCallback got added. @andreiborza any insights on this?

[mdnanocom]

Not dead — they cover different entry points:

wrapRunnableMethod patches chat-model prototypes (ChatOpenAI, ChatAnthropic, …) so model.invoke/stream/batch calls merge the Sentry handler. This is the bare-LangChain path (no graph involved).
The mergeSentryCallback call site in tracing/langgraph/index.ts patches StateGraph.compile() and merges at graph-entry — also tagging metadata with sentry_langgraph.
Inside a graph the two overlap (chat-model invokes also flow through wrapRunnableMethod), but for users on LangChain-only there's no graph patch to fall back on. Both call sites now share the same helper, which is what this PR consolidates.