Skip to content

fix(langchain): keep LangGraph pauses and handoffs out of error spans - #508

Merged
nik13 merged 1 commit into
devfrom
fix/opus-followup-traceAI-383
Nov 1, 2026
Merged

nik13 merged 1 commit into
devfrom
fix/opus-followup-traceAI-383

Conversation

@nik13

@nik13 nik13 commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Follow-up to #383. That PR made @traceai/langchain the supported TypeScript LangGraph integration. Three problems remained, all older than #383.

What was wrong

  1. LangGraph interrupt() and Command.PARENT handoffs were exported as ERROR spans. LangGraph pauses and hands off by throwing GraphBubbleUp signals (GraphInterrupt, ParentCommand) through handleChainError. The tracer treated any run.error as a failure. With @langchain/langgraph 1.6.0 and @langchain/core 1.3.2, a human-in-the-loop pause produced an ERROR ask_human span. Its exception event and status message contained the interrupt payload. A handoff made the route, subgraph and sub spans ERROR even though the graph returned normally. The Python integration already treats these signals as non-errors.
  2. @opentelemetry/core was imported but not declared. tracer.ts imports isTracingSuppressed from it. With npm and the hoisting workspace this only worked because @traceai/fi-core's copy was hoisted. Under Yarn PnP and pnpm with hoist=false, both require() and import of @traceai/langchain failed, so tracing never started.
  3. The README Quick Start passed openAIApiKey. ChatOpenAI 1.x ignores that alias at runtime and reads only apiKey, configuration.apiKey or OPENAI_API_KEY.

Changes

  • src/tracer.ts: an error with is_bubble_up === true, which is LangGraph's own isGraphBubbleUp check, now ends the span OK, with no exception event and no status message. When only run.error is available, the tracer matches the LangGraph signal names instead. Without importing LangGraph, it now:
    • marks GraphInterrupt and NodeInterrupt with langgraph.interrupt: true and an interrupt event, as Python does. The payload is never recorded.
    • leaves ParentCommand handoffs unmarked.
    • records real errors exactly as before.
  • package.json and pnpm-lock.yaml: declare @opentelemetry/core@^2.0.1. This matches @traceai/fi-core, so it resolves to the same 2.0.1 the lock already has. The only lockfile change is the 3-line importer entry.
  • README: the Quick Start uses apiKey, and the Features list gains one line on LangGraph pauses and handoffs. contract/readme.mjs now rejects openAIApiKey.

Tests

  • New src/__tests__/bubbleUp.test.ts covers:

    • an interrupt is OK, marked, and its payload is not leaked
    • a handoff is OK and not marked
    • the run.error-only fallback
    • negative controls: a real error and a falsy is_bubble_up are still errors

    Before the fix, 3 of these tests fail. The negative controls pass both before and after.

  • New src/__tests__/dependencies.test.ts: every package imported by the shipped source must be listed in dependencies or peerDependencies. The workspace hoists everything, so only a static check can catch this in the repo. It fails before the fix by naming @opentelemetry/core.

  • New contract/langgraph.mjs, using real LangGraph, CJS and ESM, no network. It checks an interrupt() pause and resume, a Command.PARENT handoff from a subgraph, and a real node failure as a control. CI runs it with LangGraph 0.2.74 and 0.4.10 on core 0.3.80, and 1.0.0 and 1.6.0 on core 1.3.2.

  • New CI step: install the packed tarballs with pnpm hoist=false, then require and import the package.

Local results, all run with outbound network denied:

  • The unit suite: 44/44 pass.
  • The existing lifecycle contract on core 0.2.0, 0.3.0, 0.3.80, 1.0.0 and 1.3.2, in every mode, public and private: all pass.
  • Packed type checks on all five cores: all pass.
  • The LangGraph contract on all four LangGraph versions, CJS and ESM: all pass. It fails before the fix.
  • Loading with Yarn 4.5.3 PnP and pnpm hoist=false, CJS and ESM: all pass. It failed before the fix.
  • The README Quick Start contract with @langchain/openai 1.8.0: passes.
  • release_plan.py --check and pnpm install --frozen-lockfile pass.

pnpm run lint for this package was already failing before this change, because ESLint 9 finds no flat config. CI does not run it.

🤖 Generated with Claude Code

LangGraph's interrupt() and Command.PARENT handoffs throw GraphBubbleUp
control-flow signals through handleChainError. The tracer exported those
runs as ERROR spans with an exception event, and the interrupt() status
message carried the interrupt payload. Treat bubble-ups as successful
runs, mark interrupt() pauses with langgraph.interrupt (as the Python
integration does), and keep real errors as errors.

Declare @opentelemetry/core, which the tracer imports: under Yarn PnP and
pnpm without hoisting the package failed to load. Pass the README's
OpenAI key as apiKey, since ChatOpenAI 1.x ignores openAIApiKey.

CI runs the LangGraph contract on LangGraph 0.2.74, 0.4.10, 1.0.0 and
1.6.0, and loads the packed package with strict pnpm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nik13
nik13 merged commit 054b9ba into dev Nov 1, 2026
70 checks passed
@nik13
nik13 deleted the fix/opus-followup-traceAI-383 branch November 1, 2026 23:19
@nik13 nik13 mentioned this pull request Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant