@struct-ai/sdk 0.3.0 → 0.4.2

package/dist/esm/integrations/langchain-callback.js

@@ -1,10 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { context as otelContext, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
-import { getAgentSpan, getSessionId, popPendingToolCallId, pushPendingToolCalls, } from "../context.js";
+import { getAgentSpan, getManualAgentSpan, getPendingToolCalls, getSessionId, stampProviderOnce, } from "../context.js";
 import { safe } from "../core.js";
-import { ERROR_TYPE, EVENT_NAMES, EVENT_NAME, GEN_AI, LANGCHAIN_FINISH_REASON_MAP, ROLE_TO_EVENT_NAME, STRUCT, } from "../semconv.js";
+import { ERROR_TYPE, EVENT_NAMES, EVENT_NAME, GEN_AI, LANGCHAIN, LANGCHAIN_FINISH_REASON_MAP, ROLE_TO_EVENT_NAME, STRUCT, } from "../semconv.js";
 import { safeJsonStringify, truncateAndSerialize, truncateParts, } from "../truncation.js";
-import { detectProvider, langchainMessageToRoleAndParts, langchainToInputMessages, langchainToOutputMessages, lastUserMessageParts, } from "./langchain-content.js";
+import { MODULE_PROVIDER_MAP, detectProvider, langchainMessageToRoleAndParts, langchainToInputMessages, langchainToOutputMessages, lastUserMessageParts, } from "./langchain-content.js";
 /**
  * LangChain CallbackHandler — creates OTel spans from LangChain callbacks.
  *
@@ -23,29 +23,37 @@ import { detectProvider, langchainMessageToRoleAndParts, langchainToInputMessage
  *
  * - `gen_ai.conversation.id` is the OTel GenAI-spec conversation identifier
  *   and Struct's UI grouping unit — one value = one entry in the sessions
- *   list. For the top-level agent we auto-derive it from thread_id, so a
- *   stable thread_id across multi-turn chats collapses into one session.
+ *   list. It is one id per run: every span belonging to a top-level agent
+ *   invocation AND any subagents it spawns shares the SAME
+ *   `gen_ai.conversation.id`, so the whole call tree collapses into one
+ *   session (OTel's `conversation.id` models "the thread", not "the
+ *   agent").
  *
- * For SUBAGENTS (an agent invoked from inside another's tool body) we
- * deliberately assign a DIFFERENT conversation.id — either from the subagent's
- * own thread_id if supplied, or a fresh UUID. The resulting session is
- * linked back to the outer agent's session via the
- * `struct.agent.parent_session_id` span attribute (what powers "Spawned
- * by" / subagent navigation in the UI). Without this split the subagent's
- * spans would collapse into the outer session, burying delegation.
+ * SUBAGENTS (an agent invoked from inside another's tool body) therefore
+ * INHERIT the parent run's `gen_ai.conversation.id` rather than minting
+ * their own. Structural linkage — "this invoke_agent span was spawned by
+ * that one" — is carried separately via the `struct.agent.parent_session_id`
+ * span attribute (what powers "Spawned by" / subagent navigation in the
+ * UI), not by giving the subagent a different session id.
  *
- * LangChain quirk (handled automatically): when `agent.invoke(...)` runs
- * nested inside a parent call, LangChain's config-merge inherits the
- * parent's `metadata.thread_id` onto the child even if its config provided
- * a different one. We detect that by comparing against the nearest agent
- * ancestor's session; if they match, treat it as "inherited, not
- * user-intended" and assign a fresh UUID to the subagent.
+ * A subagent MAY still be started with its own explicit thread_id (e.g. a
+ * LangGraph checkpoint key distinct from the parent's). When that happens
+ * we preserve it as `struct.agent.thread_id` for observability, but it does
+ * NOT split the session — `gen_ai.conversation.id` still follows the
+ * parent, because the grouping unit is the run, not the checkpoint.
+ *
+ * Chat / tool / retriever spans NEVER fabricate a conversation id. If no
+ * ancestor run, metadata thread_id, or ambient session supplies one, the
+ * span (and any log events it emits) simply omits `gen_ai.conversation.id`
+ * — an orphan span with no session is preferable to a fake one that can
+ * never be joined to anything else.
  *
  * End-user guidance:
  *   - Use thread_id per conversation; multi-turn chats reuse it.
- *   - For a subagent call, pass a DIFFERENT thread_id (or omit it and let
- *     LangGraph generate one). Each subagent then surfaces as its own
- *     session in the UI, linked back via parent_session_id.
+ *   - Subagents inherit the enclosing run's session automatically; you
+ *     don't need to (and shouldn't) pass a different thread_id purely to
+ *     separate them — use `struct.agent.parent_session_id` /
+ *     "Spawned by" navigation in the UI instead.
  */
 export class StructCallbackHandler {
     sdk;
@@ -70,6 +78,54 @@ export class StructCallbackHandler {
     raiseError = false;
     runs = new Map();
     internalLogger;
+    /**
+     * Index of live `execute_tool` spans by their `langgraph_checkpoint_ns`,
+     * keyed to an ARRAY of currently-live spans rather than a single span.
+     *
+     * The re-parenting trick this supports: LangGraph stamps a namespace
+     * (`tools:<uuid>`) on a tool-call branch AND the same value on the
+     * sub-agent graph that tool triggers, so a sub-agent's chain-start (whose
+     * `parentRunId` points at the parent GRAPH — a sibling of the tool in the
+     * run tree, not the tool itself) can look itself up by ns and re-parent
+     * under its triggering tool call instead of landing as a sibling.
+     *
+     * That assumption — "ns is unique even across parallel same-named tool
+     * calls" — is FALSE on every `@langchain/langgraph` release checked, up
+     * to and including the latest published as of this writing (`1.4.7`, and
+     * confirmed byte-identical on `main` at HEAD): `ToolNode.run()`
+     * (`0.2.x`: `dist/prebuilt/tool_node.js`; `1.x`: moved to
+     * `libs/langgraph-core/src/prebuilt/tool_node.ts`) invokes every parallel
+     * `tool_call` within one step (`Promise.all(...map(call => this.runTool(
+     * call, config, input)))`) with the exact SAME `config` object reference
+     * — no per-call config cloning, no call-index-derived namespace — so
+     * `config.metadata.langgraph_checkpoint_ns` collides across parallel
+     * same-named tool calls in that step on every version, not just 0.2.x.
+     * (One opt-in exception: routing tool calls through LangGraph `Send`
+     * objects, added ~PR #1498, gets Pregel's normal per-task namespacing —
+     * but `createReactAgent`/`ToolNode`'s default path does not use it.) If a
+     * future release fixes this, update this comment with the version and
+     * consider re-enabling direct pairing unconditionally on it. (Python's
+     * `langgraph.prebuilt.tool_node.ToolNode._afunc` does not have this
+     * problem: it calls `get_config_list(config, len(tool_calls))` to build a
+     * genuinely per-call config before fanning out.)
+     *
+     * An array-per-ns (instead of one span per ns) makes the collision
+     * DETECTABLE instead of silently last-write-wins: at consume time
+     * (`handleChainStart`'s sub-agent lookup), exactly one live candidate for
+     * the ns is an unambiguous pair (re-parent as before); zero or more than
+     * one live candidates means we cannot tell which tool call the sub-agent
+     * actually belongs to, so we deliberately do NOT re-parent — the
+     * sub-agent falls back to the normal `resolveParent` chain (renders as a
+     * graph sibling: degraded, but never wrong). Cross-wiring two unrelated
+     * spans is worse than under-wiring one. Entries are evicted (their
+     * specific span removed, not the whole ns bucket) in
+     * `handleToolEnd`/`handleToolError` so the map never grows unboundedly and
+     * so a tool call that finishes frees its slot for ambiguity resolution.
+     * Parity: python `_tool_spans_by_ns` / `_checkpoint_ns` (python's
+     * `langgraph` >= 1.2.0 does not need this same guard, since its ns values
+     * never collide — see above).
+     */
+    checkpointNsToolSpans = new Map();
     constructor(sdk, tracer, logger) {
         this.sdk = sdk;
         this.tracer = tracer;
@@ -82,7 +138,7 @@ export class StructCallbackHandler {
         // LangGraph nodes): don't create a span, but record the runId so
         // downstream children with parentRunId pointing here can still find
         // their effective parent span.
-        if (!isAgentChain(chain, runType, runName)) {
+        if (!isAgentChain(chain, runType, runName, metadata)) {
             // Skipped chains inherit session from parent (so chat/tool spans
             // created under them stay tied to the enclosing agent's session).
             const sessionId = this.resolveSessionId(parentRunId, metadata);
@@ -92,49 +148,171 @@ export class StructCallbackHandler {
                 effectiveParentSpan: parentSpan,
                 sessionId,
                 nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+                nearestAgentSpan: this.inheritedAgentSpan(parentRunId),
+                ...this.resolveQueueOwnership(parentRunId),
                 kind: "skipped-chain",
             });
             return;
         }
+        // Manual struct.agent() wins over the framework's chain — twin
+        // suppression (ownership: manual > framework > provider).
+        //
+        // Generalized check (0.3.14; was: only a TOP-LEVEL chain, gated on
+        // `if (!parentRunId)`): suppress THIS agent chain as a
+        // "suppressed-twin" whenever a manual struct.agent() scope is live
+        // (`getManualAgentSpan()`) AND the run's EFFECTIVE parent span —
+        // resolved exactly like every other span's parent, via
+        // `resolveParent`, which already walks THROUGH intervening
+        // skipped-chains (RunnableSequence, ChannelWrite, Branch, a
+        // `prompt | graph` composition, ...) — resolves to that manual span
+        // itself. That condition means this run is the FIRST real agent chain
+        // reachable from the manual root through ONLY skipped chains, with no
+        // real framework `invoke_agent` in between.
+        //
+        // This SUBSUMES the old top-level-only case: a genuine top-level
+        // chain's effective parent is `resolveParent`'s no-known-parent
+        // fallback, `getAgentSpan()` — which core.ts's `agent()` seeds to the
+        // SAME span object as `manualAgentSpan`, so it equals `manual`
+        // whenever a manual scope is live. It ALSO now catches what the old
+        // `!parentRunId` gate missed: `sdk.agent(() => sequence.invoke(...))`
+        // wrapping `RunnableSequence -> CompiledStateGraph` (or any skipped
+        // chain wrapping the real graph). The sequence is registered as a
+        // `skipped-chain` whose `effectiveParentSpan` already resolves to the
+        // manual span; the graph's chain-start DOES carry a `parentRunId` (the
+        // sequence's) — which used to bypass this check entirely and fall
+        // through to a REAL `invoke_agent`, emitting a duplicate — but now
+        // resolves ITS OWN effective parent (via the same `resolveParent` every
+        // other span uses) to the manual span too, and gets suppressed exactly
+        // like a top-level twin would.
+        //
+        // A genuine nested sub-agent (agent -> tool -> sub-agent, or a
+        // sub-agent spawned under a REAL framework `invoke_agent`) instead
+        // resolves its effective parent to that real tool/agent SPAN — never
+        // the manual span — so `parentSpan !== manual` and it is correctly NOT
+        // suppressed, emitting its own `invoke_agent` as before.
+        //
+        // Record the run pointing at the manual span so descendants parent
+        // under it — but emit NO twin invoke_agent span, and NEVER end the
+        // manual span from chain callbacks (span: undefined guards that via
+        // the `if (!r || !r.span) return;` early-returns in
+        // handleChainEnd/handleChainError).
+        //
+        // Python parity note: `struct-sdk-python`'s `on_chain_start`
+        // (langchain.py:681-698) gates the identical suppression on
+        // `parent_key is None` — i.e. Python has this SAME top-level-only
+        // limitation today; it is not something this TS fix introduces or
+        // widens. This fix intentionally puts TS ahead of Python on the
+        // RunnableSequence/skipped-chain-wrapped-graph scenario until a
+        // matching Python fix lands — filed as a follow-up rather than silently
+        // diverging.
+        const manual = getManualAgentSpan();
+        const { parentSpan, parentSpanIsAgent: parentSpanIsAgentChain } = this.resolveParent(parentRunId);
+        void parentSpanIsAgentChain;
+        const parentAgentSessionId = this.inheritedAgentSessionId(parentRunId);
+        if (manual && parentSpan === manual) {
+            // Self-audit round 5 (FIX C): `getSessionId()` alone is the AMBIENT
+            // session — `undefined` for a SESSION-LESS manual `struct.agent()`
+            // (no explicit/enclosing sessionId; core.ts never fabricates one for
+            // its OWN span). Python still gives the suppressed-twin's
+            // descendants a COHERENT conversation.id in that case: it resolves
+            // `session_id` via `_resolve_agent_session_id` (metadata thread_id,
+            // then ambient session, then a fresh UUID) BEFORE checking manual
+            // ownership, then falls back to it — `_current_session_id.get(None)
+            // or session_id` (langchain.py:685-696) — rather than leaving the
+            // suppressed-twin subtree session-less just because the manual scope
+            // itself chose not to fabricate one. Mirror that fallback exactly:
+            // ambient session first, else the same resolution a real invoke_agent
+            // for THIS run would use — `resolveAgentSessionId(metadata,
+            // parentAgentSessionId)`, identical to the real-agent path below, so
+            // a suppressed twin reached through skipped chains resolves exactly
+            // like the real invoke_agent it stands in for would (for a genuinely
+            // top-level twin, parentAgentSessionId is undefined, same as before).
+            const session = getSessionId() ?? this.resolveAgentSessionId(metadata, parentAgentSessionId);
+            this.runs.set(runId, {
+                span: undefined,
+                effectiveParentSpan: manual,
+                sessionId: session,
+                nearestAgentSessionId: session,
+                nearestAgentSpan: manual,
+                // Queue ownership generalizes the same way as everything else here:
+                // `resolveQueueOwnership` already inherits verbatim from a
+                // registered parent (the skipped chain(s) in between) when the live
+                // manual span matches what the parent captured, and only
+                // re-captures `getPendingToolCalls()` fresh when there's no
+                // resolvable parent (the genuinely-top-level case, matching the old
+                // hardcoded direct-capture behavior) or a NEW nested manual scope
+                // began (FIX F). No behavior change for the top-level twin; correct
+                // inheritance for the new skipped-chain-reached twin.
+                ...this.resolveQueueOwnership(parentRunId),
+                kind: "suppressed-twin",
+            });
+            return;
+        }
         const agentName = runName ??
             extractClassName(chain) ??
             (typeof inputs === "object" && inputs
                 ? inputs.name
                 : undefined) ??
             "agent";
-        // Agent-start: each agent invocation gets its OWN gen_ai.conversation.id.
-        // Prefer config.configurable.thread_id, then a fresh UUID. Never inherit
-        // from the parent agent — subagents should appear as separate sessions
-        // in the UI, linked via ``struct.agent.parent_session_id``.
+        // Agent-start: every agent invocation shares ONE gen_ai.conversation.id
+        // with the run it belongs to — subagents INHERIT the parent agent's
+        // session rather than minting their own (OTel: conversation.id models
+        // the thread, not the agent). Only when there's no parent session at
+        // all do we fall back to metadata.thread_id, the ambient session, or
+        // (as a last resort, so agent spans always have a coherent id) a fresh
+        // UUID.
         //
         // Convention (documented publicly):
         //   * thread_id is a LangGraph checkpoint identifier. Multiple turns
         //     of one conversation reuse a thread_id → we group them into one
         //     session.
-        //   * Subagents should be given a distinct thread_id (or none at all,
-        //     letting LangGraph generate one). That way a subagent surfaces
-        //     as its own entry in the sessions list.
+        //   * Subagents don't need a distinct thread_id to appear distinctly —
+        //     they surface via ``struct.agent.parent_session_id`` linkage
+        //     ("Spawned by" navigation) while staying in the same session.
         //
-        // LangChain quirk (handled below): when an invoke runs nested inside
-        // a parent's call (e.g. the tool body invokes a subagent), LangChain
-        // inherits the parent's ``metadata.thread_id`` into the child run's
-        // metadata — even when the child config supplied its own. Treat that
-        // inheritance as "no thread_id" and assign a fresh UUID.
+        // A subagent MAY still supply its own thread_id (e.g. a distinct
+        // LangGraph checkpoint key). We preserve that as ``struct.agent.thread_id``
+        // below for observability, but it does not override the inherited
+        // conversation.id.
         //
         // For the struct.agent.parent_session_id attribute, we need the
         // NEAREST agent ancestor's session — not just the immediate parent
         // run, which might be a tool span. That's what
-        // ``inheritedAgentSessionId`` walks.
-        const parentAgentSessionId = this.inheritedAgentSessionId(parentRunId);
+        // ``inheritedAgentSessionId`` walks. Both `parentAgentSessionId` and
+        // `parentSpan` were already resolved above (twin-suppression check),
+        // and are reused verbatim here — the run tree hasn't changed between
+        // the two reads within this single synchronous callback.
         const sessionId = this.resolveAgentSessionId(metadata, parentAgentSessionId);
         if (process.env.STRUCT_SDK_DEBUG === "1") {
             // eslint-disable-next-line no-console
             console.error("[struct-sdk] agent-start", agentName, "metadata.thread_id=", metadata?.thread_id, "parent.agent.session=", parentAgentSessionId, "→ resolved session=", sessionId);
         }
-        const { parentSpan, parentSpanIsAgent } = this.resolveParent(parentRunId);
-        void parentSpanIsAgent;
-        const parentCtx = parentSpan
-            ? trace.setSpan(otelContext.active(), parentSpan)
+        // LangChain agent-as-tool: a sub-agent graph runs as a SIBLING of its
+        // triggering execute_tool (parentRunId points at the parent graph, not
+        // the tool), so normal resolution would emit this invoke_agent as a
+        // sibling. LangGraph stamps the tool branch and its sub-agent with the
+        // same `langgraph_checkpoint_ns`, so on versions where that ns really is
+        // unique per tool call we re-parent under the matching live execute_tool
+        // span to nest natively (the UI's direct-tool-child path).
+        //
+        // But on every `@langchain/langgraph` release checked (0.2.x through the
+        // latest published, 1.4.7 — see the doc comment on
+        // `checkpointNsToolSpans`) the ns is NOT unique across parallel
+        // same-named tool calls in one step — so we only ever act on an
+        // UNAMBIGUOUS match: exactly one live tool span currently registered
+        // under this ns. Zero candidates (no tool ever registered this ns, or it
+        // already ended) or two-or-more candidates (a collision — we cannot tell
+        // which tool call this sub-agent belongs to) both fall back to the
+        // normal resolved parent instead of guessing. Cross-wiring two unrelated
+        // spans is a worse outcome than under-wiring one to a sibling position.
+        // Parity: python `delegating_tool_span` in `on_chain_start` (python's
+        // `langgraph` does not need this ambiguity guard — see above).
+        const ns = checkpointNs(metadata);
+        const nsCandidates = ns ? this.checkpointNsToolSpans.get(ns) : undefined;
+        const nsToolSpan = nsCandidates?.length === 1 ? nsCandidates[0] : undefined;
+        const effectiveParent = nsToolSpan ?? parentSpan;
+        const parentCtx = effectiveParent
+            ? trace.setSpan(otelContext.active(), effectiveParent)
             : otelContext.active();
         // Span creation can fail (custom tracer / broken context). Skip
         // run-state insertion when it does — end/error callbacks already
@@ -149,14 +327,25 @@ export class StructCallbackHandler {
         const startedSpan = span;
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "invoke_agent");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "langchain");
+            // gen_ai.provider.name is stamped later by the first chat run under
+            // this agent (write-once) — "langchain" is a framework, not a
+            // provider, and the real one isn't known at chain start.
             startedSpan.setAttribute(GEN_AI.AGENT_NAME, String(agentName));
             // Do NOT set gen_ai.agent.id from sessionId — that conflates agent
             // identity (spec: stable agent-definition id) with a per-invocation
             // session. LangChain doesn't surface a stable agent-id to us, so we
             // leave the attribute unset. Callers who use struct.agent() directly
             // can pass their own agentId via the scope options.
-            startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+            if (sessionId)
+                startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+            // A subagent may supply its own local thread_id distinct from the
+            // inherited conversation.id (e.g. its own LangGraph checkpoint key).
+            // Preserve it for observability WITHOUT letting it split the
+            // session — struct.agent.thread_id is non-grouping metadata.
+            const localThread = metadataThreadId(metadata);
+            if (localThread && localThread !== sessionId) {
+                startedSpan.setAttribute(STRUCT.AGENT_THREAD_ID, localThread);
+            }
             // Link subagents back to the parent agent's session. Use the nearest
             // agent ancestor (NOT the immediate parent run) — a subagent spawned
             // from inside a tool has the tool as its immediate parent, but we want
@@ -189,6 +378,12 @@ export class StructCallbackHandler {
             sessionId,
             // This agent IS itself the nearest agent ancestor for everything nested inside.
             nearestAgentSessionId: sessionId,
+            nearestAgentSpan: startedSpan,
+            // Unlike nearestAgentSessionId/nearestAgentSpan, this INHERITS rather
+            // than owns — a nested subagent (bare mode) shares its ancestor's
+            // queue so a tool call fired from deep inside a subagent's own
+            // tool-call cycle still resolves against the same run-tree queue.
+            ...this.resolveQueueOwnership(parentRunId),
             kind: "chain",
         });
     };
@@ -227,6 +422,17 @@ export class StructCallbackHandler {
         const parentCtx = parentSpan
             ? trace.setSpan(otelContext.active(), parentSpan)
             : otelContext.active();
+        // CLASS RULE: detection => propagation BEFORE any child-span telemetry —
+        // a throwing tracer or failing chat-span write must not leave the healthy
+        // ancestor agent provider-less. ("langchain" is the unknown-model
+        // fallback sentinel, never propagated.) Parity: python
+        // on_chat_model_start stamp_ancestor.
+        safe(() => {
+            const providerAncestor = this.inheritedAgentSpan(parentRunId);
+            if (providerAncestor && provider !== "langchain") {
+                stampProviderOnce(providerAncestor, provider);
+            }
+        }, "langchain.handleChatModelStart.stamp_provider", this.internalLogger);
         let span;
         safe(() => {
             span = this.tracer.startSpan(`chat ${model}`, { kind: SpanKind.CLIENT }, parentCtx);
@@ -239,7 +445,8 @@ export class StructCallbackHandler {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "chat");
             startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, provider);
             startedSpan.setAttribute(GEN_AI.REQUEST_MODEL, String(model));
-            startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+            if (sessionId)
+                startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
             setRequestAttrsFromInvocation(startedSpan, extraParams?.invocation_params);
             const flat = messages.flat();
             if (flat.length > 0) {
@@ -250,8 +457,13 @@ export class StructCallbackHandler {
                 if (this.sdk.emitSpanContent) {
                     startedSpan.setAttribute(GEN_AI.INPUT_MESSAGES, langchainToInputMessages(flat));
                 }
-                // Propagate the most recent user message onto the nearest agent span.
-                const ancestorAgentSpan = this.resolveParent(parentRunId).parentSpan ?? getAgentSpan();
+                // Propagate the most recent user message onto the nearest AGENT
+                // span — never a tool/chat span. `resolveParent(...).parentSpan`
+                // is the immediate parent (which may be a tool span when the chat
+                // fires from inside a tool body), so we must use the cached
+                // nearest-agent-ancestor lookup instead. Parity: python
+                // `_find_agent_ancestor` used at `on_chat_model_start` (:905-907).
+                const ancestorAgentSpan = this.inheritedAgentSpan(parentRunId);
                 if (ancestorAgentSpan)
                     this.propagateUserPrompt(ancestorAgentSpan, flat);
             }
@@ -261,6 +473,13 @@ export class StructCallbackHandler {
             effectiveParentSpan: startedSpan,
             sessionId,
             nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+            nearestAgentSpan: this.inheritedAgentSpan(parentRunId),
+            // No `parentRunId` here means a graph-less bare chat flow (e.g. a
+            // bound-tools chat model invoked directly, no AgentExecutor/graph
+            // wrapping it) — this run IS the top level, so it gets a fresh queue
+            // when bare, exactly like handleChainStart's top-level case.
+            ...this.resolveQueueOwnership(parentRunId),
+            forcedToolName: extractForcedToolName(extraParams?.invocation_params),
             kind: "llm",
         });
     };
@@ -295,17 +514,42 @@ export class StructCallbackHandler {
             if (!Array.isArray(toolCalls) || toolCalls.length === 0)
                 return;
             const pairs = [];
+            let forcedToolConsumed = false;
             for (const tc of toolCalls) {
                 if (tc && typeof tc === "object") {
                     const n = tc.name;
                     const id = tc.id;
                     if (typeof n === "string" && typeof id === "string" && n && id) {
+                        // A forced tool_choice (structured output extraction) is not a
+                        // real tool call the agent should autofill via @struct.tool() —
+                        // exclude it from the pending queue. Parity: python forced-tool
+                        // exclusion in `on_llm_end` (langchain.py:998-1027).
+                        if (n === r.forcedToolName) {
+                            forcedToolConsumed = true;
+                            continue;
+                        }
                         pairs.push([n, id]);
                     }
                 }
             }
-            if (pairs.length > 0)
-                pushPendingToolCalls(pairs);
+            if (pairs.length > 0 && r.toolCallQueue) {
+                // Push directly onto the RunState-PINNED queue OBJECT (decided
+                // once at the run-tree root and inherited by reference — see
+                // RunState's `toolCallQueue` doc comment), NOT via the
+                // ALS-reading `pushPendingToolCalls` helper: this run's callback
+                // may fire in a lost/foreign ALS frame, and reading/writing the
+                // pinned object directly sidesteps that entirely (in manual mode
+                // this object IS the same one context.ts's ALS-scoped helpers
+                // read, since it was captured via `getPendingToolCalls()` at the
+                // run-tree root — see `resolveQueueOwnership`).
+                const q = r.toolCallQueue;
+                for (const [name, id] of pairs) {
+                    (q[name] ??= []).push(id);
+                }
+            }
+            if (forcedToolConsumed) {
+                span.setAttribute(GEN_AI.OUTPUT_TYPE, "json");
+            }
         }, "langchain.handleLLMEnd.record_pending_tool_calls", this.internalLogger);
         safe(() => span.setStatus({ code: SpanStatusCode.OK }), "langchain.handleLLMEnd.set_status", this.internalLogger);
         safe(() => span.end(), "langchain.handleLLMEnd.span_end", this.internalLogger);
@@ -337,33 +581,86 @@ export class StructCallbackHandler {
             return;
         const startedSpan = span;
         const sessionId = this.resolveSessionId(parentRunId, metadata);
+        const queueOwnership = this.resolveQueueOwnership(parentRunId);
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "execute_tool");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "langchain");
+            // No gen_ai.provider.name: the spec's execute_tool span does not
+            // define that attribute.
             startedSpan.setAttribute(GEN_AI.TOOL_NAME, String(toolName));
-            // Tool call id from metadata (LangChain passes it there for ToolCall inputs)
-            // or fallback to the pending queue populated by the LLM's tool_calls.
+            // Tool call id from metadata (LangChain passes it there for ToolCall
+            // inputs) or fallback to the pending queue populated by the LLM's
+            // tool_calls — popped directly off THIS run's PINNED queue OBJECT
+            // (`queueOwnership.toolCallQueue`, inherited from the run-tree root —
+            // see RunState's `toolCallQueue` doc comment), NOT via the
+            // ALS-reading `popPendingToolCallId` helper: this callback may fire
+            // in a lost/foreign ALS frame, and popping from the pinned object
+            // directly sidesteps that entirely (in manual mode this object IS
+            // the same one context.ts's ALS-scoped helpers read/write, since it
+            // was captured via `getPendingToolCalls()` at the run-tree root).
             const callId = metadata?.tool_call_id ??
                 extractToolCallIdFromInput(input) ??
-                popPendingToolCallId(String(toolName));
+                popFromQueue(queueOwnership.toolCallQueue, String(toolName));
             if (callId)
                 startedSpan.setAttribute(GEN_AI.TOOL_CALL_ID, callId);
-            startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+            if (sessionId)
+                startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
             if (this.sdk.captureContent && input !== undefined) {
                 startedSpan.setAttribute(GEN_AI.TOOL_CALL_ARGUMENTS, safeJsonStringify(input).slice(0, 8192));
             }
         }, "langchain.handleToolStart.set_attrs", this.internalLogger);
+        const tool_ns = checkpointNs(metadata);
         this.runs.set(runId, {
             span: startedSpan,
             effectiveParentSpan: startedSpan,
             sessionId,
             nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+            nearestAgentSpan: this.inheritedAgentSpan(parentRunId),
+            // Carried forward (not re-resolved) so a bare sub-agent spawned from
+            // inside this tool call inherits the SAME run-tree queue and pinned
+            // ownership.
+            ...queueOwnership,
+            checkpointNs: tool_ns,
             kind: "tool",
         });
+        // Index by checkpoint ns so a sub-agent graph triggered inside this tool
+        // (sharing this exact ns) can re-parent its invoke_agent span under us —
+        // PUSH onto the ns's candidate list rather than overwrite it, since
+        // `@langchain/langgraph@0.2.x` can hand two parallel same-named tool
+        // calls the identical ns (see `checkpointNsToolSpans`'s doc comment).
+        // Consume-side (`handleChainStart`) only acts when exactly one candidate
+        // is live for the ns; a 2+ list here is exactly the collision case it's
+        // built to detect.
+        if (tool_ns !== undefined) {
+            const bucket = this.checkpointNsToolSpans.get(tool_ns);
+            if (bucket)
+                bucket.push(startedSpan);
+            else
+                this.checkpointNsToolSpans.set(tool_ns, [startedSpan]);
+        }
     };
+    /**
+     * Remove one specific span from its checkpoint-ns bucket (not the whole
+     * bucket) — a sibling parallel tool call under the same colliding ns may
+     * still be live and must keep its own candidate-list membership. Deletes
+     * the ns key entirely once its bucket is empty so the map never grows
+     * unboundedly.
+     */
+    evictCheckpointNsSpan(ns, span) {
+        if (ns === undefined || span === undefined)
+            return;
+        const bucket = this.checkpointNsToolSpans.get(ns);
+        if (!bucket)
+            return;
+        const idx = bucket.indexOf(span);
+        if (idx !== -1)
+            bucket.splice(idx, 1);
+        if (bucket.length === 0)
+            this.checkpointNsToolSpans.delete(ns);
+    }
     handleToolEnd = (output, runId) => {
         const r = this.runs.get(runId);
         this.runs.delete(runId);
+        this.evictCheckpointNsSpan(r?.checkpointNs, r?.span);
         if (!r || !r.span)
             return;
         const span = r.span;
@@ -372,12 +669,24 @@ export class StructCallbackHandler {
                 span.setAttribute(GEN_AI.TOOL_CALL_RESULT, safeJsonStringify(output).slice(0, 8192));
             }
         }, "langchain.handleToolEnd.set_result", this.internalLogger);
-        safe(() => span.setStatus({ code: SpanStatusCode.OK }), "langchain.handleToolEnd.set_status", this.internalLogger);
+        safe(() => {
+            if (toolOutputSignalsError(output)) {
+                span.setAttribute(ERROR_TYPE, "tool_error");
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "tool returned an error result",
+                });
+            }
+            else {
+                span.setStatus({ code: SpanStatusCode.OK });
+            }
+        }, "langchain.handleToolEnd.set_status", this.internalLogger);
         safe(() => span.end(), "langchain.handleToolEnd.span_end", this.internalLogger);
     };
     handleToolError = (err, runId) => {
         const r = this.runs.get(runId);
         this.runs.delete(runId);
+        this.evictCheckpointNsSpan(r?.checkpointNs, r?.span);
         if (!r || !r.span)
             return;
         const span = r.span;
@@ -404,9 +713,11 @@ export class StructCallbackHandler {
         const sessionId = this.resolveSessionId(parentRunId, metadata);
         safe(() => {
             startedSpan.setAttribute(GEN_AI.OPERATION_NAME, "retrieval");
-            startedSpan.setAttribute(GEN_AI.PROVIDER_NAME, "langchain");
+            // No gen_ai.provider.name: not an inference span, and "langchain"
+            // isn't a provider.
             startedSpan.setAttribute(GEN_AI.DATA_SOURCE_ID, String(name));
-            startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
+            if (sessionId)
+                startedSpan.setAttribute(GEN_AI.CONVERSATION_ID, sessionId);
             if (this.sdk.captureContent && typeof query === "string") {
                 startedSpan.setAttribute(GEN_AI.RETRIEVAL_QUERY_TEXT, query.slice(0, 4096));
             }
@@ -416,6 +727,8 @@ export class StructCallbackHandler {
             effectiveParentSpan: startedSpan,
             sessionId,
             nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+            nearestAgentSpan: this.inheritedAgentSpan(parentRunId),
+            ...this.resolveQueueOwnership(parentRunId),
             kind: "retriever",
         });
     };
@@ -451,7 +764,7 @@ export class StructCallbackHandler {
                 // filtered chains (RunnableSequence, ChannelWrite, ...).
                 return {
                     parentSpan: p.effectiveParentSpan,
-                    parentSpanIsAgent: p.kind === "chain",
+                    parentSpanIsAgent: p.kind === "chain" || p.kind === "suppressed-twin",
                 };
             }
         }
@@ -459,7 +772,11 @@ export class StructCallbackHandler {
     }
     /**
      * Conversation-id resolution for chat/tool/retriever spans — INHERIT from
-     * the parent agent so everything rolls up under one gen_ai.conversation.id.
+     * the parent run so everything rolls up under one gen_ai.conversation.id.
+     * Returns `undefined` (never fabricates a UUID) when no ancestor run,
+     * metadata thread_id, or ambient session supplies one — an orphan span
+     * with no conversation.id is preferable to a fake one that can never be
+     * joined to anything else (parity: python `_resolve_session_id`).
      */
     resolveSessionId(parentRunId, metadata) {
         if (parentRunId) {
@@ -470,10 +787,7 @@ export class StructCallbackHandler {
         const threadId = metadataThreadId(metadata);
         if (threadId)
             return threadId;
-        const ambient = getSessionId();
-        if (ambient)
-            return ambient;
-        return randomUUID();
+        return getSessionId();
     }
     /**
      * Walk the run tree to find the nearest ``invoke_agent`` ancestor's
@@ -493,32 +807,137 @@ export class StructCallbackHandler {
         return this.runs.get(parentRunId)?.nearestAgentSessionId;
     }
     /**
-     * Conversation-id resolution for AGENT spans — each agent invocation gets
-     * its own gen_ai.conversation.id. We deliberately do NOT inherit from the
-     * parent run, so subagents surface as separate entries in the sessions
-     * list. Parent linkage is preserved via `struct.agent.parent_session_id`.
+     * Nearest ``invoke_agent`` ancestor SPAN — O(1) lookup, mirrors
+     * ``inheritedAgentSessionId`` for the span pointer itself. Cached at every
+     * RunState creation so descendants (and prompt propagation) can reach the
+     * ancestor without walking a parent chain we don't retain.
+     *
+     * Unlike ``inheritedAgentSessionId``, a missing ``parentRunId`` falls back
+     * to the ambient `getAgentSpan()` (matching `resolveParent`'s top-level
+     * fallback) rather than `undefined` — a run with no LangChain parent may
+     * still be nested inside a manually-created `struct.agent()` span.
+     * Parity: python `_inherited_agent_span`.
+     */
+    inheritedAgentSpan(parentRunId) {
+        if (!parentRunId)
+            return getAgentSpan();
+        return this.runs.get(parentRunId)?.nearestAgentSpan ?? getAgentSpan();
+    }
+    /**
+     * Resolve the pending-tool-call queue OBJECT a run should push/pop
+     * against for `gen_ai.tool.call.id` autofill, per `RunState.toolCallQueue`'s
+     * doc comment.
      *
-     * LangChain inherits `metadata.thread_id` from the parent invoke's config
-     * when a nested invoke runs inside it (even if the child config supplied
-     * its own). We detect that inheritance by comparing against the parent's
-     * resolved session and ignore the inherited value.
+     * PINNED AT THE RUN-TREE ROOT, INHERITED DOWN AS THE SAME OBJECT
+     * REFERENCE — this is the crux of the design, and it is the OBJECT that
+     * must be pinned, not merely a manual-vs-bare boolean. Whenever a parent
+     * run is known (`parentRunId` resolves to a live `RunState`), we copy its
+     * `toolCallQueue` reference VERBATIM rather than re-deriving anything from
+     * the live ALS frame. Only a run with no resolvable parent (a genuine
+     * root, or an orphaned `parentRunId` whose `RunState` was never
+     * registered) consults the live `getManualAgentSpan()` signal — and even
+     * then, only ONCE, at that run's creation.
+     *
+     * Why the OBJECT, not just a boolean: a descendant run's OWN callback can
+     * fire in a lost or foreign ALS frame — the LangChain FRAMEWORK layer
+     * (`langchain.ts`'s `BaseChatModel.generate`/`.stream` patch) opens its
+     * own short-lived ALS scope (`runWithContext({ suppressGenAi: true },
+     * fn)`) around each chat completion, entirely independent of any customer
+     * `struct.agent()` call; more generally, LangGraph's internal scheduling
+     * can run a node's callback outside the async context that originally
+     * held the manual scope. A design that pins only a manual-vs-bare
+     * ownership BOOLEAN but still routes the actual push (`handleLLMEnd`) and
+     * pop (`handleToolStart`) through the ALS-reading
+     * `pushPendingToolCalls`/`popPendingToolCallId` helpers (context.ts) is
+     * still broken: those helpers read whatever `pendingToolCalls` object is
+     * on the CURRENT frame, so a push in one lost/foreign frame and a pop in a
+     * DIFFERENT lost/foreign frame silently disagree, even though both frames
+     * correctly resolved the same boolean. Operating directly on the
+     * RunState-pinned `toolCallQueue` object sidesteps the ALS frame entirely
+     * for both operations: whatever object the root observed is what the
+     * whole run tree pushes into and pops from, regardless of ALS frame state
+     * at either callback.
+     *
+     * Three cases:
+     *   1. `parentRunId` resolves to a registered parent `RunState` — inherit
+     *      `toolCallQueue` from it verbatim (decided once at the tree root) —
+     *      UNLESS a NEW manual scope began mid-tree (see FIX F below).
+     *   2. No parent (root, or an orphaned `parentRunId`) AND a MANUAL
+     *      `struct.agent()` scope is live right now (`getManualAgentSpan()`
+     *      set) — capture `getPendingToolCalls()`, the SAME object
+     *      `struct.agent()` seeded onto the ALS store and that manual
+     *      `struct.tool()` calls pop from via `popPendingToolCallId`
+     *      (context.ts). Captured IN-FRAME here (this callback necessarily
+     *      runs inside the live manual scope), so the RunState-pinned
+     *      reference and the ALS store's `pendingToolCalls` stay identical.
+     *   3. No parent AND no manual scope — this run IS the top of a bare run
+     *      tree; mint a fresh queue `{}`.
+     *
+     * Self-audit round 5 (FIX F): case 1's "inherit verbatim" is only correct
+     * when the parent's queue was captured under the SAME manual ownership
+     * that is live right now. A NESTED manual `struct.agent()` — opened from
+     * inside a tool body, whose own LangChain graph LangChain threads as a
+     * CHILD of the outer run tree, parented on a REAL tool span rather than
+     * reaching the manual span through skipped chains (so it never reaches
+     * the suppressed-twin branch in `handleChainStart`) — would otherwise
+     * silently inherit the OUTER run's
+     * queue object, even though the CURRENT ambient `getManualAgentSpan()` is
+     * the INNER agent's own (different) span and the inner agent's own
+     * `pendingToolCalls` (a fresh object seeded by that inner `struct.agent()`
+     * call) is what its descendants actually push/pop against. Detect this by
+     * comparing the live `getManualAgentSpan()` against the PARENT run's
+     * `queueManualSpan` (the manual span that owned the parent's queue): if
+     * they differ and the live one is truthy, a new manual scope has begun —
+     * re-capture `getPendingToolCalls()` fresh, exactly like case 2. When they
+     * match (including both `undefined`, i.e. bare on both sides — preserves
+     * the F2 frame-independence fix, where a merely lost/foreign ALS frame
+     * reads as `undefined` and must NOT trigger a spurious re-capture),
+     * inherit verbatim as before.
+     */
+    resolveQueueOwnership(parentRunId) {
+        const manual = getManualAgentSpan();
+        if (parentRunId) {
+            const parent = this.runs.get(parentRunId);
+            if (parent) {
+                if (manual && manual !== parent.queueManualSpan) {
+                    return { toolCallQueue: getPendingToolCalls() ?? {}, queueManualSpan: manual };
+                }
+                return { toolCallQueue: parent.toolCallQueue, queueManualSpan: parent.queueManualSpan };
+            }
+        }
+        return {
+            toolCallQueue: manual ? (getPendingToolCalls() ?? {}) : {},
+            queueManualSpan: manual,
+        };
+    }
+    /**
+     * Conversation-id resolution for AGENT spans — INHERIT from the parent
+     * run first, so a subagent shares its outer agent's gen_ai.conversation.id
+     * (one id per run; parity: python `_resolve_agent_session_id`). Only when
+     * there's no parent session do we fall back to metadata.thread_id, the
+     * ambient session, or — as a last resort, since agent spans should always
+     * have a coherent id — a fresh UUID. A subagent's own divergent thread_id
+     * (if any) is preserved separately as `struct.agent.thread_id`; see the
+     * caller in `handleChainStart`.
      */
     resolveAgentSessionId(metadata, parentSessionId) {
+        if (parentSessionId)
+            return parentSessionId; // inherit — one id per run
         const threadId = metadataThreadId(metadata);
-        if (threadId) {
-            if (parentSessionId && threadId === parentSessionId) {
-                // Inherited from parent — treat as unset, assign fresh.
-                return randomUUID();
-            }
+        if (threadId)
             return threadId;
-        }
         const ambient = getSessionId();
         if (ambient)
             return ambient;
-        return randomUUID();
+        return randomUUID(); // agents always get a coherent id
     }
     propagateUserPrompt(parentSpan, messages) {
         try {
+            // Parent-prompt preview is CONTENT — never emit it in ContentCaptureMode
+            // .None (same gate as the anthropic/openai provider paths; kept in
+            // EventOnly deliberately: shipped behavior the waterfall UI reads).
+            if (!this.sdk.captureContent)
+                return;
             const attrs = parentSpan
                 .attributes;
             if (attrs && attrs[GEN_AI.INPUT_MESSAGES])
@@ -550,6 +969,77 @@ const AGENT_CLASSES = new Set([
     "Pregel",
     "LangGraph",
 ]);
+/**
+ * LangChain/LangGraph fires chain-start for every internal Runnable. In
+ * Python, ``serialized`` is usually ``None`` for these, so we filter on
+ * run_name via a denylist. Matches LangSmith's promotion heuristic.
+ * Parity: python `_INTERNAL_RUN_NAMES` (langchain.py:267-306).
+ */
+const INTERNAL_RUN_NAMES = new Set([
+    // Runnable wiring/plumbing
+    "RunnableSequence",
+    "RunnableLambda",
+    "RunnablePassthrough",
+    "RunnableParallel",
+    "RunnableBinding",
+    "RunnableMap",
+    "RunnableAssign",
+    "RunnableBranch",
+    "RunnableWithFallbacks",
+    "RunnableEach",
+    "RunnablePick",
+    "RunnableGenerator",
+    // Prompt templates
+    "Prompt",
+    "ChatPromptTemplate",
+    "PromptTemplate",
+    // langchain.agents (1.x) / legacy create_react_agent internal node names
+    "agent",
+    "tools",
+    "call_model",
+    "should_continue",
+    "__start__",
+    "__end__",
+    // Output parsers — invoked as Runnables but not agents. LangChain's
+    // ``langchain.agents.create_agent`` with ``ToolStrategy`` (or fallback
+    // from ``ProviderStrategy`` on models without native structured output)
+    // invokes these as a separate step and they fire on_chain_start.
+    "PydanticToolsParser",
+    "PydanticOutputParser",
+    "JsonOutputParser",
+    "JsonOutputToolsParser",
+    "JsonOutputKeyToolsParser",
+    "StrOutputParser",
+    "OutputParser",
+    "BaseOutputParser",
+    "OpenAIToolsAgentOutputParser",
+    "OpenAIFunctionsAgentOutputParser",
+    // TS-ecosystem addition beyond the Python `_INTERNAL_RUN_NAMES` list: this
+    // class only exists in @langchain/anthropic (JS), not in Python LangChain,
+    // so the byte-identical port doesn't cover it. `ChatAnthropic
+    // .withStructuredOutput(schema)` (without `include_raw`) internally chains
+    // through @langchain/anthropic's AnthropicToolsOutputParser
+    // (dist/output_parsers.js), which fires on_chain_start with this run name.
+    // Do not remove this during a cross-SDK denylist diff against Python.
+    "AnthropicToolsOutputParser",
+    // TS-ecosystem addition beyond Python's `_INTERNAL_RUN_NAMES`: needed for
+    // @langchain/langgraph 0.2.x internal sub-chains. `createReactAgent`'s
+    // prompt-application step (dist/prebuilt/react_agent_executor.js,
+    // `PROMPT_RUNNABLE_NAME = "prompt"`) is wired via
+    // `RunnableLambda.from(...).withConfig({ runName: "prompt" })` and invoked
+    // as a step INSIDE the "agent" Pregel node — so its own
+    // `metadata.langgraph_node` is stamped with the PARENT node's name (e.g.
+    // "agent"), not "prompt" itself, and the self-match rule (3 above) can't
+    // suppress it. Confirmed live: this fires on_chain_start once per model
+    // turn on installed @langchain/langgraph@0.2.74, producing spurious
+    // `invoke_agent prompt` spans (live-parity REPORT.md). Python's
+    // currently-resolved langgraph (1.2.0, via `create_agent`) doesn't hit
+    // this — a LangGraph major-version confound, not something struct-sdk
+    // controls. Do not remove this during a cross-SDK denylist diff against
+    // Python.
+    "prompt",
+]);
+const INTERNAL_RUN_NAME_PREFIXES = ["ChannelWrite<", "Branch<", "RunnableSequence<"];
 /**
  * Threading-id metadata keys, in resolution order.
  *
@@ -576,11 +1066,67 @@ function metadataThreadId(metadata) {
     }
     return undefined;
 }
-function isAgentChain(chain, runType, _runName) {
+/**
+ * LangGraph stamps a unique `langgraph_checkpoint_ns` (`tools:<uuid>`) on
+ * each tool-call branch, and the SAME value on the sub-agent graph that the
+ * tool triggers — even across parallel same-named tool calls. Used to
+ * re-parent a sub-agent's `invoke_agent` span under its triggering
+ * `execute_tool` span. Returns the namespace, or `undefined` if absent.
+ * Parity: python `_checkpoint_ns` (langchain.py:325-341).
+ */
+function checkpointNs(metadata) {
+    if (!metadata || typeof metadata !== "object")
+        return undefined;
+    const ns = metadata["langgraph_checkpoint_ns"];
+    return typeof ns === "string" && ns.length > 0 ? ns : undefined;
+}
+/**
+ * Only promote user-meaningful chains to `invoke_agent` spans.
+ *
+ * Decision order (parity: python `_is_agent_chain`, langchain.py:360-407):
+ *
+ * 1. Explicit `runType === "agent"` (legacy AgentExecutor) → agent.
+ * 2. `chain` class identifies a Pregel/CompiledStateGraph → agent.
+ * 3. `metadata.langgraph_node === runName` → INTERNAL Pregel node (every
+ *    internal step of a `create_agent` Pregel fires chain-start with
+ *    metadata.langgraph_node set to its node name; for real top-level
+ *    agents or sub-agents the names differ or langgraph_node is absent).
+ * 4. Known LangChain plumbing run names (denylist) → not agent.
+ * 5. Otherwise, if there's a runName → agent (user-named chain).
+ */
+function isAgentChain(chain, runType, runName, metadata) {
     if (runType === "agent")
         return true;
     const cls = extractClassName(chain);
-    return !!cls && AGENT_CLASSES.has(cls);
+    if (cls && AGENT_CLASSES.has(cls))
+        return true;
+    // Internal Pregel node detection: LangGraph populates metadata with
+    // `langgraph_node` (and `langgraph_step`) on every internal node
+    // callback. The run_name of an internal node matches its langgraph_node;
+    // for the top-level Pregel invocation, langgraph_node is absent; for a
+    // sub-agent invoked from a tool body, langgraph_node may be set BUT
+    // contains the *parent's* node name (e.g. "tools"), which differs from
+    // the sub-agent's own run_name. So equality is the discriminator.
+    if (metadata && runName) {
+        const lgNode = metadata["langgraph_node"];
+        if (typeof lgNode === "string" && lgNode && lgNode === runName)
+            return false;
+    }
+    if (runName) {
+        // LangChain names parametrized runnables `Base<...>` — e.g.
+        // `RunnableParallel<raw>` and `RunnableAssign<parsed,parsing_error>`
+        // from `with_structured_output(include_raw=True)`. Strip the `<...>`
+        // so the base class matches the denylist instead of falling through to
+        // the user-named-chain promotion below (a real production phantom-agent
+        // bug found via a customer's structured-output topology).
+        const baseName = runName.split("<", 1)[0];
+        if (INTERNAL_RUN_NAMES.has(baseName))
+            return false;
+        if (INTERNAL_RUN_NAME_PREFIXES.some((p) => runName.startsWith(p)))
+            return false;
+        return true; // user-named chain → promoted
+    }
+    return false;
 }
 function extractClassName(obj) {
     if (!obj)
@@ -597,14 +1143,77 @@ function extractClassName(obj) {
 function detectProviderFromSerialized(llm) {
     const cls = extractClassName(llm) ?? "";
     const fake = { constructor: { name: cls }, _llmType: undefined };
-    return detectProvider(fake);
+    const byClass = detectProvider(fake);
+    if (byClass !== "langchain")
+        return byClass;
+    // Module-path fallback (parity with python's _detect_provider_from_serialized):
+    // an unknown/wrapped class under a known provider module (e.g.
+    // langchain_openai) still resolves to the real provider.
+    const ids = llm.id;
+    const modulePath = Array.isArray(ids) && typeof ids[0] === "string" ? ids[0] : "";
+    // SEGMENT-exact matching, scoped to langchain partner packages — substring
+    // classified lookalikes (langchain_notopenai -> openai), and the value gets
+    // write-once stamped onto agent spans, so a false positive is sticky.
+    if (modulePath === "langchain" ||
+        modulePath.startsWith("langchain_") ||
+        modulePath.startsWith("langchain.")) {
+        const segments = modulePath.split(/[._]/).filter(Boolean);
+        for (const [key, provider] of Object.entries(MODULE_PROVIDER_MAP)) {
+            if (segments.includes(key))
+                return provider;
+        }
+    }
+    return "langchain";
 }
+/** @internal */
+export const _detectProviderFromSerializedForTest = detectProviderFromSerialized;
 function extractParam(obj, key) {
     if (!obj || typeof obj !== "object")
         return undefined;
     const v = obj[key];
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
+/**
+ * Extract the tool name the model was forced to call via `tool_choice`, if
+ * any. Handles both provider shapes LangChain forwards in
+ * `invocation_params.tool_choice`:
+ *   - Anthropic: `{type:"tool", name}`
+ *   - OpenAI:    `{type:"function", function:{name}}`
+ * `invocation` is unknown-typed (LangChain's `extraParams.invocation_params`
+ * is untyped provider passthrough) — every layer is defensively checked.
+ * Parity: python `_forced_tool_name` (langchain.py:410-432).
+ */
+function extractForcedToolName(invocation) {
+    if (!invocation || typeof invocation !== "object")
+        return undefined;
+    const tc = invocation["tool_choice"];
+    if (!tc || typeof tc !== "object")
+        return undefined;
+    const t = tc;
+    if (t.type === "tool" && typeof t.name === "string")
+        return t.name;
+    if (t.type === "function") {
+        const fn = t.function;
+        if (fn && typeof fn === "object" && typeof fn.name === "string") {
+            return fn.name;
+        }
+    }
+    return undefined;
+}
+/**
+ * `@langchain/anthropic` (JS) keys whose value is a negative sentinel
+ * meaning "not set by the caller" rather than a real request parameter.
+ * `dist/chat_models.js` defaults BOTH `topK` and `topP` to `-1` and always
+ * includes them in `invocationParams()` as `top_k`/`top_p` — unlike
+ * Python's `ChatAnthropic`, which never forwards `top_k`/`top_p` unless the
+ * caller genuinely set them. Confirmed live: TS was stamping
+ * `gen_ai.request.top_k = -1` on every chat span (live-parity REPORT.md).
+ * Scoped tightly to these two keys — do NOT extend blanket-negative
+ * filtering to `frequencyPenalty`/`presencePenalty`, which are legitimately
+ * negative in OpenAI's real range (-2.0..2.0). JS-ecosystem sentinel;
+ * python parity: absent-when-unset.
+ */
+const NEGATIVE_SENTINEL_KEYS = new Set(["topK", "top_k", "topP", "top_p"]);
 function setRequestAttrsFromInvocation(span, invocation) {
     if (!invocation || typeof invocation !== "object")
         return;
@@ -622,8 +1231,11 @@ function setRequestAttrsFromInvocation(span, invocation) {
     ];
     for (const [src, dst] of mapping) {
         const v = m[src];
-        if (typeof v === "number")
-            span.setAttribute(dst, v);
+        if (typeof v !== "number")
+            continue;
+        if (NEGATIVE_SENTINEL_KEYS.has(src) && v < 0)
+            continue;
+        span.setAttribute(dst, v);
     }
     const stop = m.stop ?? m.stopSequences ?? m.stop_sequences;
     if (Array.isArray(stop) && stop.length > 0) {
@@ -660,11 +1272,24 @@ function setLlmResponseAttrs(span, sdk, logger, message, provider, sessionId) {
         const mapped = LANGCHAIN_FINISH_REASON_MAP[finish] ?? finish;
         span.setAttribute(GEN_AI.RESPONSE_FINISH_REASONS, [mapped]);
     }
-    const respId = (typeof m.id === "string" && m.id) ||
-        (typeof respMeta.id === "string" && respMeta.id) ||
-        null;
-    if (respId)
+    // Prefer the provider message id (`msg_...` / `chatcmpl-...`) from
+    // response_metadata over LangChain's own run id. ChatAnthropic (and most
+    // LangChain chat model adapters) place the real API-level id in
+    // `response_metadata.id` while `message.id` carries a LangChain-internal
+    // run id. gen_ai.response.id is used as the duplicate-detection
+    // fingerprint downstream, so the provider id must take priority. The
+    // LangChain run id is preserved under `langchain.run.id` (only when it
+    // diverges) so consumers can still join back to LangChain/LangSmith run
+    // data. Parity: python `_set_llm_response_attrs` (langchain.py:1560-1576).
+    const providerId = typeof respMeta.id === "string" ? respMeta.id : undefined;
+    const lcRunId = typeof m.id === "string" ? m.id : undefined;
+    const respId = providerId ?? lcRunId ?? null;
+    if (respId) {
         span.setAttribute(GEN_AI.RESPONSE_ID, respId);
+        if (lcRunId && lcRunId !== respId) {
+            span.setAttribute(LANGCHAIN.RUN_ID, lcRunId);
+        }
+    }
     if (sdk.emitEvents && logger) {
         emitChoiceEvent(logger, message, provider ?? "langchain", sessionId, span);
     }
@@ -695,9 +1320,9 @@ function emitMessageEvents(logger, messages, provider, sessionId, span) {
             attributes: {
                 [EVENT_NAME]: eventName,
                 body: payload,
-                [GEN_AI.SYSTEM]: provider,
+                [GEN_AI.PROVIDER_NAME]: provider,
                 [GEN_AI.MESSAGE_INDEX]: i,
-                [GEN_AI.CONVERSATION_ID]: sessionId,
+                ...(sessionId ? { [GEN_AI.CONVERSATION_ID]: sessionId } : {}),
             },
         });
     }
@@ -722,8 +1347,8 @@ function emitChoiceEvent(logger, message, provider, sessionId, span) {
         attributes: {
             [EVENT_NAME]: EVENT_NAMES.CHOICE,
             body: payload,
-            [GEN_AI.SYSTEM]: provider,
-            [GEN_AI.CONVERSATION_ID]: sessionId,
+            [GEN_AI.PROVIDER_NAME]: provider,
+            ...(sessionId ? { [GEN_AI.CONVERSATION_ID]: sessionId } : {}),
         },
     });
 }
@@ -743,6 +1368,23 @@ function extractToolCallIdFromInput(input) {
     }
     return undefined;
 }
+/**
+ * Pop the first pending tool_use id matching `name` from a RunState-pinned
+ * (run-tree-scoped, not ALS-scoped) queue object. FIFO semantics identical
+ * to `context.ts`'s `popPendingToolCallId` — see `RunState.toolCallQueue`.
+ * Used for BOTH manual and bare ownership: in manual mode the queue object
+ * passed in is the same one `getPendingToolCalls()` (context.ts) reads, so
+ * popping here and popping via that ALS-scoped helper observe the same
+ * state.
+ */
+function popFromQueue(queue, name) {
+    if (!queue)
+        return undefined;
+    const ids = queue[name];
+    if (!ids || ids.length === 0)
+        return undefined;
+    return ids.shift();
+}
 function recordError(span, err) {
     const errorType = err instanceof Error ? err.constructor.name : typeof err;
     const message = err instanceof Error ? err.message : String(err);
@@ -751,4 +1393,29 @@ function recordError(span, err) {
     if (err instanceof Error)
         span.recordException(err);
 }
+/**
+ * Whether a LangChain tool OUTPUT signals in-band failure: a
+ * ToolMessage with status "error", or an MCP-style isError/is_error
+ * boolean-true flag on the top-level object. Mirrors python
+ * langchain.on_tool_end semantics — keep in lockstep.
+ */
+function toolOutputSignalsError(output) {
+    if (typeof output !== "object" || output === null)
+        return false;
+    // Per-key probe isolation: a hostile getter on one key must not mask a
+    // readable sibling. Mirrors python _tool_output_signals_error.
+    return (probe(output, "status") === "error" ||
+        probe(output, "isError") === true ||
+        probe(output, "is_error") === true);
+}
+/** Isolated single-property read of untrusted host data (see core.ts
+ * safeProbe — duplicated here because it is module-private there). */
+function probe(obj, key) {
+    try {
+        return obj[key];
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=langchain-callback.js.map