@agent-inspect/langchain 6.14.0 → 6.14.2

package/README.md

@@ -9,6 +9,7 @@ LangChain callback handler → local AgentInspect traces.
 
 - LangChain or LangGraph apps using `@langchain/core` callbacks
 - You want `persist: true` local JSONL without a hosted backend
+- Evidence-first CI / TraceContract gates over LangGraph runs (`init --framework langgraph`)
 
 ## When not to use
 

package/dist/index.cjs

@@ -473,6 +473,11 @@ function isSemanticParentLabel(parentLcRunId) {
   if (WELL_KNOWN_SEMANTIC_PARENTS.has(parentLcRunId)) return true;
   return parentLcRunId.startsWith("__") && parentLcRunId.endsWith("__");
 }
+function excludeSelf(stepId, excludeStepId) {
+  if (!stepId) return void 0;
+  if (excludeStepId && stepId === excludeStepId) return void 0;
+  return stepId;
+}
 var LANGGRAPH_PARENT_KEYS = [
   "handoffFrom",
   "taskId",
@@ -485,10 +490,11 @@ function langGraphRecord(attributes) {
   if (typeof lg !== "object" || lg === null || Array.isArray(lg)) return void 0;
   return lg;
 }
-function resolveParentRelationship(input, lookup) {
+function resolveParentRelationship(input, lookup, context = {}) {
   const parentLcRunId = input.parentLcRunId;
+  const excludeStepId = context.excludeStepId;
   if (parentLcRunId) {
-    const exact = lookup.exactStepByLcRunId(parentLcRunId);
+    const exact = excludeSelf(lookup.exactStepByLcRunId(parentLcRunId), excludeStepId);
     if (exact) {
       return {
         parentStepId: exact,
@@ -503,8 +509,14 @@ function resolveParentRelationship(input, lookup) {
       if (key !== "handoffFrom" && key !== "checkpointNamespace") continue;
       const raw = lg[key];
       if (typeof raw !== "string" || !raw.trim()) continue;
-      const stepId = lookup.uniqueStepByLangGraphKey(key === "handoffFrom" ? "taskId" : key, raw);
-      const matched = stepId ?? (key === "handoffFrom" ? lookup.uniqueStepByLangGraphKey("nodeName", raw) ?? lookup.uniqueStepByLangGraphKey("nodeId", raw) : void 0);
+      const stepId = excludeSelf(
+        lookup.uniqueStepByLangGraphKey(key === "handoffFrom" ? "taskId" : key, raw),
+        excludeStepId
+      );
+      const matched = stepId ?? excludeSelf(
+        key === "handoffFrom" ? lookup.uniqueStepByLangGraphKey("nodeName", raw) ?? lookup.uniqueStepByLangGraphKey("nodeId", raw) : void 0,
+        excludeStepId
+      );
       if (matched) {
         return {
           parentStepId: matched,
@@ -516,7 +528,10 @@ function resolveParentRelationship(input, lookup) {
     }
   }
   if (parentLcRunId && isSemanticParentLabel(parentLcRunId)) {
-    const semantic = lookup.uniqueStepBySemanticLabel(parentLcRunId);
+    const semantic = excludeSelf(
+      lookup.uniqueStepBySemanticLabel(parentLcRunId),
+      excludeStepId
+    );
     if (semantic) {
       return {
         parentStepId: semantic,
@@ -544,6 +559,30 @@ function resolveParentRelationship(input, lookup) {
     parentMapping: "exact"
   };
 }
+function rejectSelfParentResolution(resolution, stepId, parentLcRunId) {
+  if (resolution.parentStepId !== stepId) return resolution;
+  return {
+    confidence: "unresolved",
+    parentMapping: "unresolved",
+    unresolvedParentRunId: parentLcRunId ?? resolution.unresolvedParentRunId,
+    ...resolution.semanticParentLabel ? { semanticParentLabel: resolution.semanticParentLabel } : {}
+  };
+}
+var AI_LANGGRAPH_SELF_PARENT_REJECTED = "AI_LANGGRAPH_SELF_PARENT_REJECTED";
+function applySelfParentCaptureInvariant(stepId, parentStepId, metadata, originalParentRunId) {
+  if (!parentStepId || parentStepId !== stepId) {
+    return { parentStepId, rejected: false };
+  }
+  metadata.parentMapping = "self-parent-rejected";
+  metadata.parentConfidence = "unresolved";
+  metadata.relationshipWarning = "self-parent";
+  metadata.diagnosticCode = AI_LANGGRAPH_SELF_PARENT_REJECTED;
+  if (originalParentRunId && originalParentRunId.trim()) {
+    metadata.originalParentRunId = originalParentRunId.slice(0, 128);
+  }
+  delete metadata.parentCorrelatedVia;
+  return { parentStepId: void 0, rejected: true };
+}
 function applyParentResolutionMetadata(metadata, resolution) {
   const hasParentSignal = Boolean(resolution.parentStepId) || Boolean(resolution.unresolvedParentRunId) || Boolean(resolution.semanticParentLabel) || Boolean(resolution.correlatedVia);
   if (!hasParentSignal) return;
@@ -604,6 +643,7 @@ var LangChainTracePersistence = class {
   /** Count of unresolved semantic-parent children seen per label (this invocation). */
   #semanticParentCounts = /* @__PURE__ */ new Map();
   #lateEventCount = 0;
+  #selfParentRejectedCount = 0;
   constructor(options = {}) {
     const inContext = advanced.hasActiveContext();
     this.#standalone = !inContext;
@@ -641,12 +681,25 @@ var LangChainTracePersistence = class {
       pendingRelationshipCount: this.#lifecycle.pendingRelationships.length,
       knownRelationshipCount: this.#lifecycle.knownRelationships.size,
       syntheticGroupCount: this.#syntheticByLabel.size,
+      selfParentRejectedCount: this.#selfParentRejectedCount,
       envelopeStarted: this.#lifecycle.envelopeStarted,
       finalized: this.#lifecycle.finalized,
       completionGeneration: this.#lifecycle.completionGeneration,
       hasTerminalError: Boolean(this.#lifecycle.terminalError)
     };
   }
+  #parentIdForPersist(stepId, resolution, metadata, originalParentRunId) {
+    const guarded = applySelfParentCaptureInvariant(
+      stepId,
+      resolution.parentStepId,
+      metadata,
+      originalParentRunId ?? resolution.unresolvedParentRunId
+    );
+    if (guarded.rejected) {
+      this.#selfParentRejectedCount += 1;
+    }
+    return guarded.parentStepId;
+  }
   /**
    * Start a fresh envelope after a prior invocation finalized (callback reuse).
    * Allocates a new run id unless still nested in an inspectRun context.
@@ -659,6 +712,7 @@ var LangChainTracePersistence = class {
         resetInvocationState(this.#lifecycle, this.#runId);
         this.#clearStepIndexes();
         this.#lateEventCount = 0;
+        this.#selfParentRejectedCount = 0;
         return;
       }
     }
@@ -666,11 +720,13 @@ var LangChainTracePersistence = class {
     resetInvocationState(this.#lifecycle, this.#runId);
     this.#clearStepIndexes();
     this.#lateEventCount = 0;
+    this.#selfParentRejectedCount = 0;
   }
   reset() {
     resetInvocationState(this.#lifecycle);
     this.#clearStepIndexes();
     this.#lateEventCount = 0;
+    this.#selfParentRejectedCount = 0;
   }
   #clearStepIndexes() {
     this.#lcToStepId.clear();
@@ -718,8 +774,8 @@ var LangChainTracePersistence = class {
       }
     }
   }
-  #resolveParent(parentLcRunId, attributes) {
-    return resolveParentRelationship(
+  #resolveParent(parentLcRunId, attributes, excludeStepId) {
+    const resolution = resolveParentRelationship(
       { parentLcRunId, attributes },
       {
         exactStepByLcRunId: (lcRunId) => this.#lcToStepId.get(lcRunId),
@@ -731,8 +787,10 @@ var LangChainTracePersistence = class {
           const hit = this.#semanticLabelIndex.get(label);
           return hit === null || hit === void 0 ? void 0 : hit;
         }
-      }
+      },
+      excludeStepId ? { excludeStepId } : {}
     );
+    return excludeStepId ? rejectSelfParentResolution(resolution, excludeStepId, parentLcRunId) : resolution;
   }
   /**
    * When ≥2 steps share the same unresolved semantic parent label, emit one
@@ -810,8 +868,10 @@ var LangChainTracePersistence = class {
     try {
       this.#prepareForStart();
       const stepId = advanced.createStepId();
-      this.#lcToStepId.set(params.lcRunId, stepId);
-      this.#registerStepIndexes(stepId, params.name, params.attributes);
+      const resolution = await this.#maybeAttachSyntheticGroup(
+        this.#resolveParent(params.lcParentRunId, params.attributes, stepId),
+        params.startTime
+      );
       beginCallbackRun(this.#lifecycle, {
         lcRunId: params.lcRunId,
         parentLcRunId: params.lcParentRunId,
@@ -822,25 +882,29 @@ var LangChainTracePersistence = class {
       if (this.#standalone && !this.#lifecycle.envelopeStarted) {
         await this.#ensureRunStarted(params.startTime, params.attributes);
       }
-      const resolution = await this.#maybeAttachSyntheticGroup(
-        this.#resolveParent(params.lcParentRunId, params.attributes),
-        params.startTime
-      );
       const metadata = toStepMetadata(params.attributes);
       applyParentResolutionMetadata(metadata, resolution);
+      const parentId = this.#parentIdForPersist(
+        stepId,
+        resolution,
+        metadata,
+        params.lcParentRunId
+      );
       const event = {
         schemaVersion: "0.1",
         event: "step_started",
         timestamp: params.startTime,
         runId: this.#runId,
         stepId,
-        ...resolution.parentStepId ? { parentId: resolution.parentStepId } : {},
+        ...parentId ? { parentId } : {},
         name: params.name,
         type: kindToStepType(params.kind),
         startTime: params.startTime,
         metadata
       };
+      this.#lcToStepId.set(params.lcRunId, stepId);
       await this.#write(event);
+      this.#registerStepIndexes(stepId, params.name, params.attributes);
     } catch (err) {
       this.#warn(err);
     }
@@ -858,30 +922,38 @@ var LangChainTracePersistence = class {
           return;
         }
         stepId = advanced.createStepId();
-        this.#lcToStepId.set(params.lcRunId, stepId);
         const synthName = String(params.completionAttributes.name ?? "llm:llm");
-        this.#registerStepIndexes(stepId, synthName, params.completionAttributes);
+        const startTime = params.endTime - (params.durationMs ?? 0);
+        const resolution = await this.#maybeAttachSyntheticGroup(
+          this.#resolveParent(
+            params.lcParentRunId,
+            params.completionAttributes,
+            stepId
+          ),
+          startTime
+        );
         beginCallbackRun(this.#lifecycle, {
           lcRunId: params.lcRunId,
           parentLcRunId: params.lcParentRunId,
-          startedAt: params.endTime - (params.durationMs ?? 0),
+          startedAt: startTime,
           kind: params.completionAttributes.kind ?? "LLM",
           stepId
         });
-        const startTime = params.endTime - (params.durationMs ?? 0);
-        const resolution = await this.#maybeAttachSyntheticGroup(
-          this.#resolveParent(params.lcParentRunId, params.completionAttributes),
-          startTime
-        );
         const metadata = toStepMetadata(params.completionAttributes);
         applyParentResolutionMetadata(metadata, resolution);
+        const parentId = this.#parentIdForPersist(
+          stepId,
+          resolution,
+          metadata,
+          params.lcParentRunId
+        );
         const started = {
           schemaVersion: "0.1",
           event: "step_started",
           timestamp: startTime,
           runId: this.#runId,
           stepId,
-          ...resolution.parentStepId ? { parentId: resolution.parentStepId } : {},
+          ...parentId ? { parentId } : {},
           name: synthName,
           type: kindToStepType(
             params.completionAttributes.kind ?? "LLM"
@@ -892,7 +964,9 @@ var LangChainTracePersistence = class {
         if (this.#standalone && !this.#lifecycle.envelopeStarted) {
           await this.#ensureRunStarted(startTime, params.completionAttributes);
         }
+        this.#lcToStepId.set(params.lcRunId, stepId);
         await this.#write(started);
+        this.#registerStepIndexes(stepId, synthName, params.completionAttributes);
       }
       if (!stepId) return;
       const durationMs = typeof params.durationMs === "number" && Number.isFinite(params.durationMs) ? Math.max(0, Math.floor(params.durationMs)) : Math.max(
@@ -928,8 +1002,10 @@ var LangChainTracePersistence = class {
     try {
       this.#prepareForStart();
       const stepId = advanced.createStepId();
-      this.#lcToStepId.set(params.lcRunId, stepId);
-      this.#registerStepIndexes(stepId, params.name, params.attributes);
+      const resolution = await this.#maybeAttachSyntheticGroup(
+        this.#resolveParent(params.lcParentRunId, params.attributes, stepId),
+        params.timestamp
+      );
       beginCallbackRun(this.#lifecycle, {
         lcRunId: params.lcRunId,
         parentLcRunId: params.lcParentRunId,
@@ -940,25 +1016,29 @@ var LangChainTracePersistence = class {
       if (this.#standalone && !this.#lifecycle.envelopeStarted) {
         await this.#ensureRunStarted(params.timestamp, params.attributes);
       }
-      const resolution = await this.#maybeAttachSyntheticGroup(
-        this.#resolveParent(params.lcParentRunId, params.attributes),
-        params.timestamp
-      );
       const metadata = toStepMetadata(params.attributes);
       applyParentResolutionMetadata(metadata, resolution);
+      const parentId = this.#parentIdForPersist(
+        stepId,
+        resolution,
+        metadata,
+        params.lcParentRunId
+      );
       const started = {
         schemaVersion: "0.1",
         event: "step_started",
         timestamp: params.timestamp,
         runId: this.#runId,
         stepId,
-        ...resolution.parentStepId ? { parentId: resolution.parentStepId } : {},
+        ...parentId ? { parentId } : {},
         name: params.name,
         type: kindToStepType(params.kind),
         startTime: params.timestamp,
         metadata
       };
+      this.#lcToStepId.set(params.lcRunId, stepId);
       await this.#write(started);
+      this.#registerStepIndexes(stepId, params.name, params.attributes);
       const completed = {
         schemaVersion: "0.1",
         event: "step_completed",
@@ -1204,6 +1284,7 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       pendingRelationshipCount: 0,
       knownRelationshipCount: 0,
       syntheticGroupCount: 0,
+      selfParentRejectedCount: 0,
       envelopeStarted: false,
       finalized: false,
       completionGeneration: 0,