@softprobe/langchain 0.1.6 → 0.1.8

package/dist/CallbackHandler.d.ts

@@ -7,8 +7,14 @@ import type { LLMResult } from "@langchain/core/outputs";
 import type { ChainValues } from "@langchain/core/utils/types";
 import { SoftprobeClient, type JsonValue } from "@softprobe/tracing";
 export type CallbackHandlerParams = {
-    softprobeClient: SoftprobeClient;
+    /** Defaults to {@link SoftprobeClient.fromEnv}. */
+    softprobeClient?: SoftprobeClient;
+    /**
+     * Fallback only when the run has no thread/session/chat id in LangChain
+     * metadata / `configurable`. Prefer your app's existing ids at invoke time.
+     */
     sessionId?: string;
+    /** Fallback only when the run has no user id in metadata / `configurable`. */
     userId?: string;
     tags?: string[];
     metadata?: Record<string, JsonValue>;
@@ -31,7 +37,9 @@ export declare class CallbackHandler extends BaseCallbackHandler {
     private readonly completionStart;
     private readonly toolMeta;
     lastTraceId: string | null;
-    constructor(params: CallbackHandlerParams);
+    constructor(params?: CallbackHandlerParams);
+    /** Flush pending OTLP spans (alias of the underlying client). */
+    flush(): Promise<void>;
     private parent;
     private start;
     private end;

package/dist/CallbackHandler.js

@@ -1,5 +1,5 @@
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
-import { recordToolCalls, recordToolDefinitions, toolResultEventPayload, toolSpanAttributes, normalizeToolCalls, } from "@softprobe/tracing";
+import { SoftprobeClient, resolveRunIdentity, recordToolCalls, recordToolDefinitions, toolResultEventPayload, toolSpanAttributes, normalizeToolCalls, } from "@softprobe/tracing";
 function asJsonValue(value) {
     return value;
 }
@@ -42,9 +42,9 @@ export class CallbackHandler extends BaseCallbackHandler {
     completionStart = new Map();
     toolMeta = new Map();
     lastTraceId = null;
-    constructor(params) {
+    constructor(params = {}) {
         super();
-        this.client = params.softprobeClient;
+        this.client = params.softprobeClient ?? SoftprobeClient.fromEnv();
         this.sessionId = params.sessionId;
         this.userId = params.userId;
         this.tags = params.tags ?? [];
@@ -52,6 +52,10 @@ export class CallbackHandler extends BaseCallbackHandler {
         this.version = params.version;
         this.parentSpanContext = params.parentSpanContext;
     }
+    /** Flush pending OTLP spans (alias of the underlying client). */
+    async flush() {
+        await this.client.flush();
+    }
     parent(parentRunId) {
         if (!parentRunId)
             return undefined;
@@ -64,10 +68,15 @@ export class CallbackHandler extends BaseCallbackHandler {
             ...(this.metadata ?? {}),
             ...(options.metadata ?? {}),
         };
+        const identity = resolveRunIdentity({
+            metadata: options.metadata,
+            fallbackSessionId: this.sessionId,
+            fallbackUserId: this.userId,
+        });
         const common = {
             name: options.name,
-            sessionId: this.sessionId,
-            userId: this.userId,
+            sessionId: identity.sessionId,
+            userId: identity.userId,
             tags: mergedTags.length ? mergedTags : undefined,
             metadata: Object.keys(mergedMeta).length ? mergedMeta : undefined,
             version: this.version,

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { CallbackHandler, type CallbackHandlerParams, } from "./CallbackHandler.js";
+export { instrument, uninstrument, autoInstrumentFromEnv, isInstrumented, getHandler, SOFTPROBE_LANGCHAIN_CONTEXT_VAR, } from "./instrument.js";

package/dist/index.js

@@ -1 +1,5 @@
 export { CallbackHandler, } from "./CallbackHandler.js";
+export { instrument, uninstrument, autoInstrumentFromEnv, isInstrumented, getHandler, SOFTPROBE_LANGCHAIN_CONTEXT_VAR, } from "./instrument.js";
+import { autoInstrumentFromEnv } from "./instrument.js";
+/** Best-tier UX: credentials present → auto-instrument (unless SOFTPROBE_LANGCHAIN=0). */
+autoInstrumentFromEnv();

package/dist/instrument.d.ts

@@ -0,0 +1,8 @@
+import { type SoftprobeEnvSource } from "@softprobe/tracing";
+import { CallbackHandler, type CallbackHandlerParams } from "./CallbackHandler.js";
+export declare const SOFTPROBE_LANGCHAIN_CONTEXT_VAR = "softprobe_langchain_handler";
+export declare function isInstrumented(): boolean;
+export declare function getHandler(): CallbackHandler | null;
+export declare function instrument(params?: CallbackHandlerParams): CallbackHandler;
+export declare function uninstrument(): void;
+export declare function autoInstrumentFromEnv(params?: CallbackHandlerParams, env?: SoftprobeEnvSource): CallbackHandler | null;

package/dist/instrument.js

@@ -0,0 +1,52 @@
+/**
+ * Zero-setup LangChain instrumentation (env auto + `instrument()`).
+ *
+ * When SOFTPROBE_PUBLIC_KEY and SOFTPROBE_BASE_URL are set, Softprobe
+ * registers into LangChain configure hooks so every run is traced without
+ * editing `callbacks`.
+ *
+ * Opt out: SOFTPROBE_LANGCHAIN=0
+ */
+import { registerConfigureHook, setContextVariable, } from "@langchain/core/context";
+import { resolveSoftprobeConfigFromEnv, } from "@softprobe/tracing";
+import { CallbackHandler, } from "./CallbackHandler.js";
+export const SOFTPROBE_LANGCHAIN_CONTEXT_VAR = "softprobe_langchain_handler";
+let hookRegistered = false;
+let activeHandler = null;
+function envFlagDisabled(env = process.env, name = "SOFTPROBE_LANGCHAIN") {
+    const raw = env[name];
+    if (raw == null)
+        return false;
+    return ["0", "false", "off", "no"].includes(raw.trim().toLowerCase());
+}
+export function isInstrumented() {
+    return activeHandler != null;
+}
+export function getHandler() {
+    return activeHandler;
+}
+export function instrument(params = {}) {
+    if (!hookRegistered) {
+        registerConfigureHook({
+            contextVar: SOFTPROBE_LANGCHAIN_CONTEXT_VAR,
+            inheritable: true,
+        });
+        hookRegistered = true;
+    }
+    if (activeHandler == null || Object.keys(params).length > 0) {
+        activeHandler = new CallbackHandler(params);
+    }
+    setContextVariable(SOFTPROBE_LANGCHAIN_CONTEXT_VAR, activeHandler);
+    return activeHandler;
+}
+export function uninstrument() {
+    setContextVariable(SOFTPROBE_LANGCHAIN_CONTEXT_VAR, undefined);
+    activeHandler = null;
+}
+export function autoInstrumentFromEnv(params = {}, env = process.env) {
+    if (envFlagDisabled(env))
+        return null;
+    if (!resolveSoftprobeConfigFromEnv(env))
+        return null;
+    return instrument(params);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softprobe/langchain",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Softprobe LangChain callback handler",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     "lint": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@softprobe/tracing": "0.1.6"
+    "@softprobe/tracing": "0.1.8"
   },
   "peerDependencies": {
     "@langchain/core": ">=0.3.0",