@struct-ai/sdk 0.1.0

package/dist/esm/integrations/langchain-callback.d.ts

@@ -0,0 +1,134 @@
+import { type Tracer } from "@opentelemetry/api";
+import type { Logger } from "@opentelemetry/api-logs";
+import { type StructSDK } from "../core.js";
+type Serialized = {
+    lc?: number;
+    type?: string;
+    id?: string[];
+    kwargs?: Record<string, unknown>;
+    name?: string;
+};
+type UnknownMessage = unknown;
+interface ChatGenerationLike {
+    text?: string;
+    message?: UnknownMessage;
+    generationInfo?: Record<string, unknown>;
+}
+interface LLMResultLike {
+    generations: ChatGenerationLike[][];
+    llmOutput?: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export declare class StructCallbackHandler {
+    private readonly sdk;
+    private readonly tracer;
+    private readonly logger;
+    readonly name = "struct";
+    readonly lc_namespace: readonly string[];
+    readonly lc_serializable = false;
+    readonly awaitHandlers = false;
+    readonly ignoreLLM = false;
+    readonly ignoreChain = false;
+    readonly ignoreAgent = false;
+    readonly ignoreRetriever = false;
+    readonly 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`.
+     */
+    readonly raiseError = false;
+    private readonly runs;
+    private readonly internalLogger;
+    constructor(sdk: StructSDK, tracer: Tracer, logger: Logger | undefined);
+    handleChainStart: (chain: Serialized, inputs: unknown, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runType?: string, runName?: string) => void;
+    handleChainEnd: (_outputs: unknown, runId: string) => void;
+    handleChainError: (err: Error, runId: string) => void;
+    handleChatModelStart: (llm: Serialized, messages: UnknownMessage[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, _tags?: string[], metadata?: Record<string, unknown>, runName?: string) => void;
+    handleLLMStart: (llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string) => void;
+    handleLLMEnd: (output: LLMResultLike, runId: string) => void;
+    handleLLMError: (err: Error, runId: string) => void;
+    handleToolStart: (tool: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string) => void;
+    handleToolEnd: (output: unknown, runId: string) => void;
+    handleToolError: (err: Error, runId: string) => void;
+    handleRetrieverStart: (retriever: Serialized, query: string, runId: string, parentRunId?: string, _tags?: string[], metadata?: Record<string, unknown>, runName?: string) => void;
+    handleRetrieverEnd: (documents: unknown[], runId: string) => void;
+    handleRetrieverError: (err: Error, runId: string) => void;
+    private resolveParent;
+    /**
+     * Conversation-id resolution for chat/tool/retriever spans — INHERIT from
+     * the parent agent so everything rolls up under one gen_ai.conversation.id.
+     */
+    private resolveSessionId;
+    /**
+     * 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).
+     */
+    private inheritedAgentSessionId;
+    /**
+     * 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.
+     */
+    private resolveAgentSessionId;
+    private propagateUserPrompt;
+}
+export {};
+//# sourceMappingURL=langchain-callback.d.ts.map