@struct-ai/sdk 0.1.0

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

@@ -0,0 +1,723 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StructCallbackHandler = void 0;
+const node_crypto_1 = require("node:crypto");
+const api_1 = require("@opentelemetry/api");
+const context_js_1 = require("../context.js");
+const core_js_1 = require("../core.js");
+const semconv_js_1 = require("../semconv.js");
+const truncation_js_1 = require("../truncation.js");
+const langchain_content_js_1 = require("./langchain-content.js");
+/**
+ * LangChain CallbackHandler — creates OTel spans from LangChain callbacks.
+ *
+ * Parent-child linkage comes from `parentRunId` fields LangChain passes to us,
+ * NOT from OTel's async context. This survives LangGraph's internal task
+ * shuffling, which is why the callback API is the industry-standard integration
+ * point (LangSmith, OpenInference, Traceloop, Langfuse all use it).
+ *
+ * thread_id vs gen_ai.conversation.id
+ * -----------------------------------
+ * These are distinct concepts and Struct keeps them separate:
+ *
+ * - `config.configurable.thread_id` is LangGraph's checkpoint identifier,
+ *   keying a conversation's state in the checkpointer. Multiple turns of
+ *   the same conversation reuse one thread_id so history accumulates.
+ *
+ * - `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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+class StructCallbackHandler {
+    sdk;
+    tracer;
+    logger;
+    name = "struct";
+    lc_namespace = ["struct", "callbacks"];
+    lc_serializable = false;
+    awaitHandlers = false;
+    ignoreLLM = false;
+    ignoreChain = false;
+    ignoreAgent = false;
+    ignoreRetriever = false;
+    ignoreCustomEvent = true;
+    /**
+     * LangChain reads `raiseError` to decide whether a callback throw should
+     * abort the user's run. We keep this `false` because every callback method
+     * is wrapped in `safe()` and never throws — but a `true` here would tell
+     * LangChain to surface our (impossible) throws into the user's call.
+     * Locked by `test_handler_raiseError_is_false`.
+     */
+    raiseError = false;
+    runs = new Map();
+    internalLogger;
+    constructor(sdk, tracer, logger) {
+        this.sdk = sdk;
+        this.tracer = tracer;
+        this.logger = logger;
+        this.internalLogger = sdk.getInternalLogger();
+    }
+    // ─── Chain / Agent (Pregel, AgentExecutor, custom Runnables) ─────────────
+    handleChainStart = (chain, inputs, runId, parentRunId, _tags, metadata, runType, runName) => {
+        // Non-agent chain (RunnableSequence, ChannelWrite, Branch, internal
+        // 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)) {
+            // 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);
+            const { parentSpan } = this.resolveParent(parentRunId);
+            this.runs.set(runId, {
+                span: undefined,
+                effectiveParentSpan: parentSpan,
+                sessionId,
+                nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+                kind: "skipped-chain",
+            });
+            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``.
+        //
+        // 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.
+        //
+        // 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.
+        //
+        // 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);
+        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
+            ? api_1.trace.setSpan(api_1.context.active(), parentSpan)
+            : api_1.context.active();
+        // Span creation can fail (custom tracer / broken context). Skip
+        // run-state insertion when it does — end/error callbacks already
+        // tolerate missing run state via the early `_runs.get(...) === undefined`
+        // short-circuit at the top of each method.
+        let span;
+        (0, core_js_1.safe)(() => {
+            span = this.tracer.startSpan(`invoke_agent ${agentName}`, { kind: api_1.SpanKind.INTERNAL }, parentCtx);
+        }, "langchain.handleChainStart.create_span", this.internalLogger);
+        if (span === undefined)
+            return;
+        const startedSpan = span;
+        (0, core_js_1.safe)(() => {
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.OPERATION_NAME, "invoke_agent");
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.PROVIDER_NAME, "langchain");
+            startedSpan.setAttribute(semconv_js_1.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(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
+            // 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
+            // to point at the outer agent's session.
+            if (parentAgentSessionId && parentAgentSessionId !== sessionId) {
+                startedSpan.setAttribute(semconv_js_1.STRUCT.AGENT_PARENT_SESSION_ID, parentAgentSessionId);
+            }
+            // User prompt propagation — set gen_ai.input.messages on the agent
+            // span so the waterfall UI shows the question without drilling into
+            // chat spans.
+            if (this.sdk.emitSpanContent) {
+                const messages = extractChainInputMessages(inputs);
+                if (messages && messages.length > 0) {
+                    startedSpan.setAttribute(semconv_js_1.GEN_AI.INPUT_MESSAGES, (0, langchain_content_js_1.langchainToInputMessages)(messages));
+                }
+            }
+        }, "langchain.handleChainStart.set_attrs", this.internalLogger);
+        this.runs.set(runId, {
+            span: startedSpan,
+            effectiveParentSpan: startedSpan,
+            sessionId,
+            // This agent IS itself the nearest agent ancestor for everything nested inside.
+            nearestAgentSessionId: sessionId,
+            kind: "chain",
+        });
+    };
+    handleChainEnd = (_outputs, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => span.setStatus({ code: api_1.SpanStatusCode.OK }), "langchain.handleChainEnd.set_status", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleChainEnd.span_end", this.internalLogger);
+    };
+    handleChainError = (err, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => recordError(span, err), "langchain.handleChainError.record_error", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleChainError.span_end", this.internalLogger);
+    };
+    // ─── LLM / Chat model ────────────────────────────────────────────────────
+    handleChatModelStart = (llm, messages, runId, parentRunId, extraParams, _tags, metadata, runName) => {
+        const provider = detectProviderFromSerialized(llm);
+        // Note: we emit a chat span from the callback handler even when a
+        // provider-direct SDK monkey-patch is also active. The two integration
+        // layers often run against different @anthropic-ai/sdk instances due to
+        // pnpm hoisting; skipping here would silently drop the only chat span.
+        // Duplicate-span de-dup is done server-side if ever needed.
+        const model = extractParam(extraParams, "model") ??
+            extractParam(extraParams?.invocation_params, "model") ??
+            extractParam(extraParams?.invocation_params, "modelName") ??
+            runName ??
+            "unknown";
+        const { parentSpan } = this.resolveParent(parentRunId);
+        const parentCtx = parentSpan
+            ? api_1.trace.setSpan(api_1.context.active(), parentSpan)
+            : api_1.context.active();
+        let span;
+        (0, core_js_1.safe)(() => {
+            span = this.tracer.startSpan(`chat ${model}`, { kind: api_1.SpanKind.CLIENT }, parentCtx);
+        }, "langchain.handleChatModelStart.create_span", this.internalLogger);
+        if (span === undefined)
+            return;
+        const startedSpan = span;
+        const sessionId = this.resolveSessionId(parentRunId, metadata);
+        (0, core_js_1.safe)(() => {
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.OPERATION_NAME, "chat");
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.PROVIDER_NAME, provider);
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.REQUEST_MODEL, String(model));
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
+            setRequestAttrsFromInvocation(startedSpan, extraParams?.invocation_params);
+            const flat = messages.flat();
+            if (flat.length > 0) {
+                startedSpan.setAttribute(semconv_js_1.STRUCT.INPUT_MESSAGE_COUNT, flat.length);
+                if (this.sdk.emitEvents && this.logger) {
+                    emitMessageEvents(this.logger, flat, provider, sessionId, startedSpan);
+                }
+                if (this.sdk.emitSpanContent) {
+                    startedSpan.setAttribute(semconv_js_1.GEN_AI.INPUT_MESSAGES, (0, langchain_content_js_1.langchainToInputMessages)(flat));
+                }
+                // Propagate the most recent user message onto the nearest agent span.
+                const ancestorAgentSpan = this.resolveParent(parentRunId).parentSpan ?? (0, context_js_1.getAgentSpan)();
+                if (ancestorAgentSpan)
+                    this.propagateUserPrompt(ancestorAgentSpan, flat);
+            }
+        }, "langchain.handleChatModelStart.set_attrs", this.internalLogger);
+        this.runs.set(runId, {
+            span: startedSpan,
+            effectiveParentSpan: startedSpan,
+            sessionId,
+            nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+            kind: "llm",
+        });
+    };
+    handleLLMStart = (llm, prompts, runId, parentRunId, extraParams, tags, metadata, runName) => {
+        // Treat completion-style LLMs as chat with a single user message.
+        const messages = prompts.map((p) => [
+            { _getType: () => "human", content: p },
+        ]);
+        this.handleChatModelStart(llm, messages, runId, parentRunId, extraParams, tags, metadata, runName);
+    };
+    handleLLMEnd = (output, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        const sessionId = r.sessionId;
+        (0, core_js_1.safe)(() => {
+            const gen = output.generations?.[0]?.[0];
+            const message = gen?.message;
+            if (!message)
+                return;
+            setLlmResponseAttrs(span, this.sdk, this.logger, message, span.attributes?.[semconv_js_1.GEN_AI.PROVIDER_NAME], sessionId);
+        }, "langchain.handleLLMEnd.set_response_attrs", this.internalLogger);
+        (0, core_js_1.safe)(() => {
+            const gen = output.generations?.[0]?.[0];
+            const message = gen?.message;
+            if (!message)
+                return;
+            // Bridge tool_calls into the pending queue so @struct.tool() can autofill.
+            const toolCalls = message.tool_calls;
+            if (!Array.isArray(toolCalls) || toolCalls.length === 0)
+                return;
+            const pairs = [];
+            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) {
+                        pairs.push([n, id]);
+                    }
+                }
+            }
+            if (pairs.length > 0)
+                (0, context_js_1.pushPendingToolCalls)(pairs);
+        }, "langchain.handleLLMEnd.record_pending_tool_calls", this.internalLogger);
+        (0, core_js_1.safe)(() => span.setStatus({ code: api_1.SpanStatusCode.OK }), "langchain.handleLLMEnd.set_status", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleLLMEnd.span_end", this.internalLogger);
+    };
+    handleLLMError = (err, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => recordError(span, err), "langchain.handleLLMError.record_error", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleLLMError.span_end", this.internalLogger);
+    };
+    // ─── Tool ────────────────────────────────────────────────────────────────
+    handleToolStart = (tool, input, runId, parentRunId, _tags, metadata, runName) => {
+        const toolName = runName ??
+            (typeof tool === "object" && tool?.name) ??
+            extractClassName(tool) ??
+            "tool";
+        const { parentSpan } = this.resolveParent(parentRunId);
+        const parentCtx = parentSpan
+            ? api_1.trace.setSpan(api_1.context.active(), parentSpan)
+            : api_1.context.active();
+        let span;
+        (0, core_js_1.safe)(() => {
+            span = this.tracer.startSpan(`execute_tool ${toolName}`, { kind: api_1.SpanKind.INTERNAL }, parentCtx);
+        }, "langchain.handleToolStart.create_span", this.internalLogger);
+        if (span === undefined)
+            return;
+        const startedSpan = span;
+        const sessionId = this.resolveSessionId(parentRunId, metadata);
+        (0, core_js_1.safe)(() => {
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.OPERATION_NAME, "execute_tool");
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.PROVIDER_NAME, "langchain");
+            startedSpan.setAttribute(semconv_js_1.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.
+            const callId = metadata?.tool_call_id ??
+                extractToolCallIdFromInput(input) ??
+                (0, context_js_1.popPendingToolCallId)(String(toolName));
+            if (callId)
+                startedSpan.setAttribute(semconv_js_1.GEN_AI.TOOL_CALL_ID, callId);
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
+            if (this.sdk.captureContent && input !== undefined) {
+                startedSpan.setAttribute(semconv_js_1.GEN_AI.TOOL_CALL_ARGUMENTS, (0, truncation_js_1.safeJsonStringify)(input).slice(0, 8192));
+            }
+        }, "langchain.handleToolStart.set_attrs", this.internalLogger);
+        this.runs.set(runId, {
+            span: startedSpan,
+            effectiveParentSpan: startedSpan,
+            sessionId,
+            nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+            kind: "tool",
+        });
+    };
+    handleToolEnd = (output, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => {
+            if (this.sdk.captureContent && output != null) {
+                span.setAttribute(semconv_js_1.GEN_AI.TOOL_CALL_RESULT, (0, truncation_js_1.safeJsonStringify)(output).slice(0, 8192));
+            }
+        }, "langchain.handleToolEnd.set_result", this.internalLogger);
+        (0, core_js_1.safe)(() => span.setStatus({ code: api_1.SpanStatusCode.OK }), "langchain.handleToolEnd.set_status", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleToolEnd.span_end", this.internalLogger);
+    };
+    handleToolError = (err, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => recordError(span, err), "langchain.handleToolError.record_error", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleToolError.span_end", this.internalLogger);
+    };
+    // ─── Retriever ───────────────────────────────────────────────────────────
+    handleRetrieverStart = (retriever, query, runId, parentRunId, _tags, metadata, runName) => {
+        const name = runName ??
+            retriever?.name ??
+            extractClassName(retriever) ??
+            "retriever";
+        const { parentSpan } = this.resolveParent(parentRunId);
+        const parentCtx = parentSpan
+            ? api_1.trace.setSpan(api_1.context.active(), parentSpan)
+            : api_1.context.active();
+        let span;
+        (0, core_js_1.safe)(() => {
+            span = this.tracer.startSpan(`retrieval ${name}`, { kind: api_1.SpanKind.INTERNAL }, parentCtx);
+        }, "langchain.handleRetrieverStart.create_span", this.internalLogger);
+        if (span === undefined)
+            return;
+        const startedSpan = span;
+        const sessionId = this.resolveSessionId(parentRunId, metadata);
+        (0, core_js_1.safe)(() => {
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.OPERATION_NAME, "retrieval");
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.PROVIDER_NAME, "langchain");
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.DATA_SOURCE_ID, String(name));
+            startedSpan.setAttribute(semconv_js_1.GEN_AI.CONVERSATION_ID, sessionId);
+            if (this.sdk.captureContent && typeof query === "string") {
+                startedSpan.setAttribute(semconv_js_1.GEN_AI.RETRIEVAL_QUERY_TEXT, query.slice(0, 4096));
+            }
+        }, "langchain.handleRetrieverStart.set_attrs", this.internalLogger);
+        this.runs.set(runId, {
+            span: startedSpan,
+            effectiveParentSpan: startedSpan,
+            sessionId,
+            nearestAgentSessionId: this.inheritedAgentSessionId(parentRunId),
+            kind: "retriever",
+        });
+    };
+    handleRetrieverEnd = (documents, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => {
+            if (Array.isArray(documents)) {
+                span.setAttribute(semconv_js_1.GEN_AI.RETRIEVAL_DOCUMENTS, documents.length);
+            }
+        }, "langchain.handleRetrieverEnd.set_doc_count", this.internalLogger);
+        (0, core_js_1.safe)(() => span.setStatus({ code: api_1.SpanStatusCode.OK }), "langchain.handleRetrieverEnd.set_status", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleRetrieverEnd.span_end", this.internalLogger);
+    };
+    handleRetrieverError = (err, runId) => {
+        const r = this.runs.get(runId);
+        this.runs.delete(runId);
+        if (!r || !r.span)
+            return;
+        const span = r.span;
+        (0, core_js_1.safe)(() => recordError(span, err), "langchain.handleRetrieverError.record_error", this.internalLogger);
+        (0, core_js_1.safe)(() => span.end(), "langchain.handleRetrieverError.span_end", this.internalLogger);
+    };
+    // ─── Internals ───────────────────────────────────────────────────────────
+    resolveParent(parentRunId) {
+        if (parentRunId) {
+            const p = this.runs.get(parentRunId);
+            if (p) {
+                // Use the effective parent span, which correctly skips over
+                // filtered chains (RunnableSequence, ChannelWrite, ...).
+                return {
+                    parentSpan: p.effectiveParentSpan,
+                    parentSpanIsAgent: p.kind === "chain",
+                };
+            }
+        }
+        return { parentSpan: (0, context_js_1.getAgentSpan)(), parentSpanIsAgent: true };
+    }
+    /**
+     * Conversation-id resolution for chat/tool/retriever spans — INHERIT from
+     * the parent agent so everything rolls up under one gen_ai.conversation.id.
+     */
+    resolveSessionId(parentRunId, metadata) {
+        if (parentRunId) {
+            const p = this.runs.get(parentRunId);
+            if (p?.sessionId)
+                return p.sessionId;
+        }
+        const threadId = metadata?.thread_id;
+        if (typeof threadId === "string" && threadId.length > 0)
+            return threadId;
+        const ambient = (0, context_js_1.getSessionId)();
+        if (ambient)
+            return ambient;
+        return (0, node_crypto_1.randomUUID)();
+    }
+    /**
+     * Walk the run tree to find the nearest ``invoke_agent`` ancestor's
+     * gen_ai.conversation.id.
+     *
+     * The immediate ``parentRunId`` might be a tool, LLM, retriever, or a
+     * filtered RunnableSequence — none of which are agents themselves. We
+     * populate ``nearestAgentSessionId`` at each run's creation so any
+     * descendant can read it in O(1).
+     *
+     * Used to set ``struct.agent.parent_session_id`` on nested ``invoke_agent``
+     * spans (our UI's "Spawned by" / "Subagents" linkage).
+     */
+    inheritedAgentSessionId(parentRunId) {
+        if (!parentRunId)
+            return undefined;
+        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`.
+     *
+     * 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.
+     */
+    resolveAgentSessionId(metadata, parentSessionId) {
+        const threadId = metadata?.thread_id;
+        if (typeof threadId === "string" && threadId.length > 0) {
+            if (parentSessionId && threadId === parentSessionId) {
+                // Inherited from parent — treat as unset, assign fresh.
+                return (0, node_crypto_1.randomUUID)();
+            }
+            return threadId;
+        }
+        const ambient = (0, context_js_1.getSessionId)();
+        if (ambient)
+            return ambient;
+        return (0, node_crypto_1.randomUUID)();
+    }
+    propagateUserPrompt(parentSpan, messages) {
+        try {
+            const attrs = parentSpan
+                .attributes;
+            if (attrs && attrs[semconv_js_1.GEN_AI.INPUT_MESSAGES])
+                return;
+            const parts = (0, langchain_content_js_1.lastUserMessageParts)(messages);
+            if (!parts)
+                return;
+            parentSpan.setAttribute(semconv_js_1.GEN_AI.INPUT_MESSAGES, (0, truncation_js_1.truncateAndSerialize)([{ role: "user", parts }]));
+        }
+        catch {
+            /* never fail telemetry */
+        }
+    }
+}
+exports.StructCallbackHandler = StructCallbackHandler;
+// ─── helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Only promote explicit agent classes to `invoke_agent`. LangGraph fires
+ * chain-start for every internal node (`ChannelWrite`, `Branch`, `prompt`,
+ * `tools`, `__start__`, etc.); those are plumbing, not user-meaningful
+ * agent invocations, so we drop them to avoid flooding the waterfall.
+ *
+ * Users of non-standard agent frameworks can opt in by setting
+ * `runType: "agent"` in the Runnable config.
+ */
+const AGENT_CLASSES = new Set([
+    "AgentExecutor",
+    "CompiledStateGraph",
+    "CompiledGraph",
+    "Pregel",
+    "LangGraph",
+]);
+function isAgentChain(chain, runType, _runName) {
+    if (runType === "agent")
+        return true;
+    const cls = extractClassName(chain);
+    return !!cls && AGENT_CLASSES.has(cls);
+}
+function extractClassName(obj) {
+    if (!obj)
+        return undefined;
+    if (Array.isArray(obj.id) && obj.id.length > 0) {
+        const last = obj.id[obj.id.length - 1];
+        if (typeof last === "string")
+            return last;
+    }
+    if (typeof obj.name === "string")
+        return obj.name;
+    return undefined;
+}
+function detectProviderFromSerialized(llm) {
+    const cls = extractClassName(llm) ?? "";
+    const fake = { constructor: { name: cls }, _llmType: undefined };
+    return (0, langchain_content_js_1.detectProvider)(fake);
+}
+function extractParam(obj, key) {
+    if (!obj || typeof obj !== "object")
+        return undefined;
+    const v = obj[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+function setRequestAttrsFromInvocation(span, invocation) {
+    if (!invocation || typeof invocation !== "object")
+        return;
+    const m = invocation;
+    const mapping = [
+        ["temperature", semconv_js_1.GEN_AI.REQUEST_TEMPERATURE],
+        ["maxTokens", semconv_js_1.GEN_AI.REQUEST_MAX_TOKENS],
+        ["max_tokens", semconv_js_1.GEN_AI.REQUEST_MAX_TOKENS],
+        ["topP", semconv_js_1.GEN_AI.REQUEST_TOP_P],
+        ["top_p", semconv_js_1.GEN_AI.REQUEST_TOP_P],
+        ["topK", semconv_js_1.GEN_AI.REQUEST_TOP_K],
+        ["top_k", semconv_js_1.GEN_AI.REQUEST_TOP_K],
+        ["frequencyPenalty", semconv_js_1.GEN_AI.REQUEST_FREQUENCY_PENALTY],
+        ["presencePenalty", semconv_js_1.GEN_AI.REQUEST_PRESENCE_PENALTY],
+    ];
+    for (const [src, dst] of mapping) {
+        const v = m[src];
+        if (typeof v === "number")
+            span.setAttribute(dst, v);
+    }
+    const stop = m.stop ?? m.stopSequences ?? m.stop_sequences;
+    if (Array.isArray(stop) && stop.length > 0) {
+        span.setAttribute(semconv_js_1.GEN_AI.REQUEST_STOP_SEQUENCES, stop);
+    }
+}
+function setLlmResponseAttrs(span, sdk, logger, message, provider, sessionId) {
+    if (!message || typeof message !== "object")
+        return;
+    const m = message;
+    const usage = m.usage_metadata;
+    if (usage) {
+        if (typeof usage.input_tokens === "number")
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_INPUT_TOKENS, usage.input_tokens);
+        if (typeof usage.output_tokens === "number")
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_OUTPUT_TOKENS, usage.output_tokens);
+        const cr = usage.input_token_details?.cache_read;
+        const cc = usage.input_token_details?.cache_creation;
+        if (typeof cr === "number" && cr > 0)
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_CACHE_READ_INPUT_TOKENS, cr);
+        if (typeof cc === "number" && cc > 0)
+            span.setAttribute(semconv_js_1.GEN_AI.USAGE_CACHE_CREATION_INPUT_TOKENS, cc);
+    }
+    const respMeta = m.response_metadata ?? {};
+    const respModel = (typeof respMeta.model_name === "string" && respMeta.model_name) ||
+        (typeof respMeta.model === "string" && respMeta.model) ||
+        null;
+    if (respModel)
+        span.setAttribute(semconv_js_1.GEN_AI.RESPONSE_MODEL, respModel);
+    const finish = (typeof respMeta.finish_reason === "string" && respMeta.finish_reason) ||
+        (typeof respMeta.stop_reason === "string" && respMeta.stop_reason) ||
+        null;
+    if (finish) {
+        const mapped = semconv_js_1.LANGCHAIN_FINISH_REASON_MAP[finish] ?? finish;
+        span.setAttribute(semconv_js_1.GEN_AI.RESPONSE_FINISH_REASONS, [mapped]);
+    }
+    const respId = (typeof m.id === "string" && m.id) ||
+        (typeof respMeta.id === "string" && respMeta.id) ||
+        null;
+    if (respId)
+        span.setAttribute(semconv_js_1.GEN_AI.RESPONSE_ID, respId);
+    if (sdk.emitEvents && logger) {
+        emitChoiceEvent(logger, message, provider ?? "langchain", sessionId, span);
+    }
+    if (sdk.emitSpanContent) {
+        span.setAttribute(semconv_js_1.GEN_AI.OUTPUT_MESSAGES, (0, langchain_content_js_1.langchainToOutputMessages)(message));
+    }
+}
+// OTel logs convention for our emitted log events:
+//   - Body column = event tag string (human-readable signal)
+//   - LogAttributes["body"] = JSON-serialised structured payload
+// Both emitMessageEvents and emitChoiceEvent bypass the central emitLogRecord
+// helper in events.ts because they need to bind a specific span context (the
+// callback handler creates spans directly and doesn't enter them with
+// context.with). The flip is inlined at both sites.
+function emitMessageEvents(logger, messages, provider, sessionId, span) {
+    // Bind the log record's context to the chat span so the exported LogRecord
+    // carries non-zero TraceId/SpanId. Using `otelContext.active()` here would
+    // only work if the caller had entered `context.with(spanCtx, ...)` first —
+    // the LangChain callback handler doesn't (it creates the span directly).
+    const logCtx = api_1.trace.setSpan(api_1.context.active(), span);
+    for (let i = 0; i < messages.length; i++) {
+        const { role, parts } = (0, langchain_content_js_1.langchainMessageToRoleAndParts)(messages[i]);
+        const eventName = semconv_js_1.ROLE_TO_EVENT_NAME[role] ?? `gen_ai.${role}.message`;
+        const payload = (0, truncation_js_1.safeJsonStringify)({ role, parts: (0, truncation_js_1.truncateParts)(parts) });
+        logger.emit({
+            body: eventName,
+            context: logCtx,
+            attributes: {
+                [semconv_js_1.EVENT_NAME]: eventName,
+                body: payload,
+                [semconv_js_1.GEN_AI.SYSTEM]: provider,
+                [semconv_js_1.GEN_AI.MESSAGE_INDEX]: i,
+                [semconv_js_1.GEN_AI.CONVERSATION_ID]: sessionId,
+            },
+        });
+    }
+}
+function emitChoiceEvent(logger, message, provider, sessionId, span) {
+    const { parts } = (0, langchain_content_js_1.langchainMessageToRoleAndParts)(message);
+    const respMeta = (message && typeof message === "object"
+        ? message.response_metadata
+        : undefined) ?? {};
+    const finish = (typeof respMeta.finish_reason === "string" && respMeta.finish_reason) ||
+        (typeof respMeta.stop_reason === "string" && respMeta.stop_reason) ||
+        "stop";
+    const mapped = semconv_js_1.LANGCHAIN_FINISH_REASON_MAP[finish] ?? finish;
+    const payload = (0, truncation_js_1.safeJsonStringify)({
+        index: 0,
+        finish_reason: mapped,
+        message: { role: "assistant", parts: (0, truncation_js_1.truncateParts)(parts) },
+    });
+    logger.emit({
+        body: semconv_js_1.EVENT_NAMES.CHOICE,
+        context: api_1.trace.setSpan(api_1.context.active(), span),
+        attributes: {
+            [semconv_js_1.EVENT_NAME]: semconv_js_1.EVENT_NAMES.CHOICE,
+            body: payload,
+            [semconv_js_1.GEN_AI.SYSTEM]: provider,
+            [semconv_js_1.GEN_AI.CONVERSATION_ID]: sessionId,
+        },
+    });
+}
+function extractChainInputMessages(inputs) {
+    if (!inputs || typeof inputs !== "object")
+        return undefined;
+    const msgs = inputs.messages;
+    if (Array.isArray(msgs))
+        return msgs;
+    return undefined;
+}
+function extractToolCallIdFromInput(input) {
+    if (input && typeof input === "object" && !Array.isArray(input)) {
+        const id = input.id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return undefined;
+}
+function recordError(span, err) {
+    const errorType = err instanceof Error ? err.constructor.name : typeof err;
+    const message = err instanceof Error ? err.message : String(err);
+    span.setAttribute(semconv_js_1.ERROR_TYPE, errorType);
+    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message });
+    if (err instanceof Error)
+        span.recordException(err);
+}
+//# sourceMappingURL=langchain-callback.js.map