@agent-inspect/langchain 6.7.4 → 6.8.0

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import path from 'path';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { getCurrentCorrelationMetadata, hasActiveContext, getTraceDirFromContext, resolveTraceDir, getCurrentRunId, createRunId, resolveTraceSafetyOptions, createStepId, initializeTraceFile, prepareTraceEventForDisk, writeTraceEvent } from 'agent-inspect/advanced';
 import { Redactor } from 'agent-inspect/logs';
@@ -316,6 +317,247 @@ function streamMetadataFromState(state, options) {
   }
   return out;
 }
+
+// packages/langchain/src/tool-identity.ts
+function serializedLabel(s) {
+  if (typeof s.name === "string" && s.name.trim()) return s.name.trim();
+  if (Array.isArray(s.id) && s.id.length > 0) {
+    const last = s.id[s.id.length - 1];
+    if (typeof last === "string" && last.trim()) return last.trim();
+  }
+  return typeof s.type === "string" && s.type.trim() ? s.type.trim() : void 0;
+}
+function nonEmpty(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveToolIdentity(tool, runName, metadata, toolCallId) {
+  const frameworkRunName = nonEmpty(runName);
+  const metaToolName = nonEmpty(metadata?.toolName);
+  const metaTool = nonEmpty(metadata?.tool);
+  const classLabel = serializedLabel(tool);
+  const callId = nonEmpty(toolCallId) ?? nonEmpty(metadata?.toolCallId) ?? nonEmpty(metadata?.tool_call_id);
+  const displayName = frameworkRunName ?? metaToolName ?? metaTool ?? classLabel ?? "unknown-tool";
+  return {
+    displayName,
+    toolName: displayName,
+    ...classLabel && classLabel !== displayName ? { toolClass: classLabel } : {},
+    ...callId ? { toolCallId: callId } : {},
+    ...frameworkRunName ? { frameworkRunName } : {}
+  };
+}
+function applyToolIdentityAttributes(attrs, identity) {
+  attrs.tool = identity.displayName;
+  attrs.toolName = identity.toolName;
+  if (identity.toolClass) attrs.toolClass = identity.toolClass;
+  if (identity.toolCallId) attrs.toolCallId = identity.toolCallId;
+  if (identity.frameworkRunName) attrs.frameworkRunName = identity.frameworkRunName;
+}
+
+// packages/langchain/src/persist-intent.ts
+function resolvePersistIntent(input) {
+  const hasTraceDir = typeof input.traceDir === "string" && input.traceDir.trim().length > 0;
+  const explicit = input.persist;
+  if (explicit === false) {
+    return { persist: false, contradictory: hasTraceDir };
+  }
+  if (explicit === true) {
+    return { persist: true, contradictory: false };
+  }
+  return { persist: hasTraceDir, contradictory: false };
+}
+
+// packages/langchain/src/invocation-state.ts
+function createInvocationState(envelopeRunId) {
+  return {
+    envelopeRunId,
+    activeRuns: /* @__PURE__ */ new Map(),
+    endedRuns: /* @__PURE__ */ new Set(),
+    knownRelationships: /* @__PURE__ */ new Map(),
+    pendingRelationships: [],
+    completionGeneration: 0,
+    envelopeStarted: false,
+    finalized: false
+  };
+}
+function isObservedCallbackRun(state, parentLcRunId) {
+  return state.activeRuns.has(parentLcRunId) || state.endedRuns.has(parentLcRunId);
+}
+function beginCallbackRun(state, input) {
+  state.completionGeneration += 1;
+  const run = {
+    lcRunId: input.lcRunId,
+    ...input.parentLcRunId !== void 0 ? { parentLcRunId: input.parentLcRunId } : {},
+    startedAt: input.startedAt,
+    ...input.kind !== void 0 ? { kind: input.kind } : {},
+    ...input.stepId !== void 0 ? { stepId: input.stepId } : {}
+  };
+  state.activeRuns.set(input.lcRunId, run);
+  if (input.parentLcRunId !== void 0) {
+    if (isObservedCallbackRun(state, input.parentLcRunId)) {
+      state.knownRelationships.set(input.lcRunId, input.parentLcRunId);
+    } else {
+      state.pendingRelationships.push({
+        childLcRunId: input.lcRunId,
+        parentLcRunId: input.parentLcRunId,
+        reason: "unobserved-parent"
+      });
+    }
+  }
+  return run;
+}
+function endCallbackRun(state, lcRunId) {
+  const active = state.activeRuns.get(lcRunId);
+  if (active === void 0) {
+    if (state.endedRuns.has(lcRunId) || state.finalized) {
+      return { ended: false, late: true };
+    }
+    return { ended: false, late: true };
+  }
+  state.completionGeneration += 1;
+  state.activeRuns.delete(lcRunId);
+  state.endedRuns.add(lcRunId);
+  return { ended: true, late: false };
+}
+function markEnvelopeStarted(state, startTime) {
+  if (state.envelopeStarted) return false;
+  state.envelopeStarted = true;
+  state.runStartTime = startTime;
+  return true;
+}
+function markFinalized(state) {
+  if (state.finalized) return false;
+  if (!state.envelopeStarted) return false;
+  state.finalized = true;
+  return true;
+}
+function noteTerminalError(state, message) {
+  state.terminalError = { message };
+}
+function canScheduleFinalize(state) {
+  return state.envelopeStarted && !state.finalized && state.activeRuns.size === 0;
+}
+function bumpCompletionGeneration(state) {
+  state.completionGeneration += 1;
+  return state.completionGeneration;
+}
+function resetInvocationState(state, nextEnvelopeRunId) {
+  state.activeRuns.clear();
+  state.endedRuns.clear();
+  state.knownRelationships.clear();
+  state.pendingRelationships.length = 0;
+  state.terminalError = void 0;
+  state.completionGeneration += 1;
+  state.envelopeStarted = false;
+  state.finalized = false;
+  state.runStartTime = void 0;
+  if (nextEnvelopeRunId !== void 0) {
+    state.envelopeRunId = nextEnvelopeRunId;
+  }
+}
+
+// packages/langchain/src/parent-reconciliation.ts
+var WELL_KNOWN_SEMANTIC_PARENTS = /* @__PURE__ */ new Set([
+  "LangGraph",
+  "__start__",
+  "__end__"
+]);
+function isSemanticParentLabel(parentLcRunId) {
+  if (WELL_KNOWN_SEMANTIC_PARENTS.has(parentLcRunId)) return true;
+  return parentLcRunId.startsWith("__") && parentLcRunId.endsWith("__");
+}
+var LANGGRAPH_PARENT_KEYS = [
+  "handoffFrom",
+  "taskId",
+  "nodeId",
+  "nodeName",
+  "checkpointNamespace"
+];
+function langGraphRecord(attributes) {
+  const lg = attributes?.langGraph;
+  if (typeof lg !== "object" || lg === null || Array.isArray(lg)) return void 0;
+  return lg;
+}
+function resolveParentRelationship(input, lookup) {
+  const parentLcRunId = input.parentLcRunId;
+  if (parentLcRunId) {
+    const exact = lookup.exactStepByLcRunId(parentLcRunId);
+    if (exact) {
+      return {
+        parentStepId: exact,
+        confidence: "explicit",
+        parentMapping: "exact"
+      };
+    }
+  }
+  const lg = langGraphRecord(input.attributes);
+  if (lg) {
+    for (const key of LANGGRAPH_PARENT_KEYS) {
+      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);
+      if (matched) {
+        return {
+          parentStepId: matched,
+          confidence: "correlated",
+          parentMapping: "langgraph-metadata",
+          correlatedVia: key
+        };
+      }
+    }
+  }
+  if (parentLcRunId && isSemanticParentLabel(parentLcRunId)) {
+    const semantic = lookup.uniqueStepBySemanticLabel(parentLcRunId);
+    if (semantic) {
+      return {
+        parentStepId: semantic,
+        confidence: "correlated",
+        parentMapping: "semantic-name",
+        semanticParentLabel: parentLcRunId
+      };
+    }
+    return {
+      confidence: "unresolved",
+      parentMapping: "unresolved",
+      semanticParentLabel: parentLcRunId,
+      unresolvedParentRunId: parentLcRunId
+    };
+  }
+  if (parentLcRunId) {
+    return {
+      confidence: "unresolved",
+      parentMapping: "unresolved",
+      unresolvedParentRunId: parentLcRunId
+    };
+  }
+  return {
+    confidence: "explicit",
+    parentMapping: "exact"
+  };
+}
+function applyParentResolutionMetadata(metadata, resolution) {
+  const hasParentSignal = Boolean(resolution.parentStepId) || Boolean(resolution.unresolvedParentRunId) || Boolean(resolution.semanticParentLabel) || Boolean(resolution.correlatedVia);
+  if (!hasParentSignal) return;
+  metadata.parentMapping = resolution.parentMapping;
+  metadata.parentConfidence = resolution.confidence;
+  if (resolution.semanticParentLabel) {
+    metadata.semanticParentLabel = resolution.semanticParentLabel;
+  }
+  if (resolution.unresolvedParentRunId) {
+    metadata.unresolvedParentRunId = resolution.unresolvedParentRunId;
+  }
+  if (resolution.correlatedVia) {
+    metadata.parentCorrelatedVia = resolution.correlatedVia;
+  }
+  if (resolution.parentMapping === "synthetic-group") {
+    metadata.synthetic = true;
+  }
+}
+
+// packages/langchain/src/trace-persistence.ts
 function kindToStepType(kind) {
   switch (kind) {
     case "LLM":
@@ -345,27 +587,30 @@ var LangChainTracePersistence = class {
   #standalone;
   #silent;
   #safety;
-  #runStarted = false;
-  #runCompleted = false;
-  #runStartTime;
-  #rootLcRunId;
-  /** Live LangChain callback runIds for standalone envelope finalization. */
-  #activeLcRunIds = /* @__PURE__ */ new Set();
-  #sawError = false;
-  #lastErrorMessage;
-  #finalizationToken = 0;
+  #lifecycle;
   #lcToStepId = /* @__PURE__ */ new Map();
+  /** `${field}\0${value}` → stepId, or null when ambiguous. */
+  #langGraphIndex = /* @__PURE__ */ new Map();
+  /** Semantic / display label → stepId, or null when ambiguous. */
+  #semanticLabelIndex = /* @__PURE__ */ new Map();
+  /** Semantic label → synthetic step id (created once ≥2 siblings share the label). */
+  #syntheticByLabel = /* @__PURE__ */ new Map();
+  /** Count of unresolved semantic-parent children seen per label (this invocation). */
+  #semanticParentCounts = /* @__PURE__ */ new Map();
+  #lateEventCount = 0;
   constructor(options = {}) {
     const inContext = hasActiveContext();
     this.#standalone = !inContext;
     this.#silent = options.silent ?? false;
     this.#traceDir = inContext ? getTraceDirFromContext() ?? resolveTraceDir({ dir: options.traceDir }) : resolveTraceDir({ dir: options.traceDir });
-    this.#runId = (inContext ? getCurrentRunId() : void 0) ?? options.runId ?? createRunId();
+    const contextRunId = inContext ? getCurrentRunId() : void 0;
+    this.#runId = contextRunId ?? options.runId ?? createRunId();
     this.#runName = options.runName ?? "langchain-agent";
     this.#safety = resolveTraceSafetyOptions({
       redact: options.redact ? { rules: options.redact } : true,
       maxPreviewLength: options.maxPreviewChars
     });
+    this.#lifecycle = createInvocationState(this.#runId);
   }
   get runId() {
     return this.#runId;
@@ -373,49 +618,217 @@ var LangChainTracePersistence = class {
   get traceDir() {
     return this.#traceDir;
   }
+  /** @internal Test / diagnostics access to per-invocation lifecycle. */
+  get lifecycle() {
+    return this.#lifecycle;
+  }
+  /** Count of end/start events ignored after finalize (diagnostics). */
+  get lateEventCount() {
+    return this.#lateEventCount;
+  }
+  /** Bounded adapter diagnostics for CLI/MCP summaries (no filesystem paths). */
+  getDiagnostics() {
+    return {
+      lateEventCount: this.#lateEventCount,
+      activeRunCount: this.#lifecycle.activeRuns.size,
+      endedRunCount: this.#lifecycle.endedRuns.size,
+      pendingRelationshipCount: this.#lifecycle.pendingRelationships.length,
+      knownRelationshipCount: this.#lifecycle.knownRelationships.size,
+      syntheticGroupCount: this.#syntheticByLabel.size,
+      envelopeStarted: this.#lifecycle.envelopeStarted,
+      finalized: this.#lifecycle.finalized,
+      completionGeneration: this.#lifecycle.completionGeneration,
+      hasTerminalError: Boolean(this.#lifecycle.terminalError)
+    };
+  }
+  /**
+   * Start a fresh envelope after a prior invocation finalized (callback reuse).
+   * Allocates a new run id unless still nested in an inspectRun context.
+   */
+  beginNewInvocation() {
+    if (hasActiveContext()) {
+      const ctxId = getCurrentRunId();
+      if (ctxId) {
+        this.#runId = ctxId;
+        resetInvocationState(this.#lifecycle, this.#runId);
+        this.#clearStepIndexes();
+        this.#lateEventCount = 0;
+        return;
+      }
+    }
+    this.#runId = createRunId();
+    resetInvocationState(this.#lifecycle, this.#runId);
+    this.#clearStepIndexes();
+    this.#lateEventCount = 0;
+  }
   reset() {
-    this.#finalizationToken += 1;
-    this.#runStarted = false;
-    this.#runCompleted = false;
-    this.#runStartTime = void 0;
-    this.#rootLcRunId = void 0;
-    this.#activeLcRunIds.clear();
-    this.#sawError = false;
-    this.#lastErrorMessage = void 0;
+    resetInvocationState(this.#lifecycle);
+    this.#clearStepIndexes();
+    this.#lateEventCount = 0;
+  }
+  #clearStepIndexes() {
     this.#lcToStepId.clear();
+    this.#langGraphIndex.clear();
+    this.#semanticLabelIndex.clear();
+    this.#syntheticByLabel.clear();
+    this.#semanticParentCounts.clear();
+  }
+  #registerUnique(index, key, stepId) {
+    if (!index.has(key)) {
+      index.set(key, stepId);
+      return;
+    }
+    if (index.get(key) !== stepId) {
+      index.set(key, null);
+    }
+  }
+  #langGraphIndexKey(field, value) {
+    return `${field}\0${value}`;
   }
-  noteRoot(lcRunId, parentRunId) {
-    if (!parentRunId && !this.#rootLcRunId) {
-      this.#rootLcRunId = lcRunId;
+  #registerStepIndexes(stepId, name, attributes) {
+    const labels = /* @__PURE__ */ new Set([name]);
+    const stripped = name.replace(/^(chain|tool|llm|retriever|agent):/, "");
+    if (stripped) labels.add(stripped);
+    for (const label of labels) {
+      this.#registerUnique(this.#semanticLabelIndex, label, stepId);
+    }
+    const lg = attributes.langGraph;
+    if (typeof lg === "object" && lg !== null && !Array.isArray(lg)) {
+      const record = lg;
+      for (const field of [
+        "taskId",
+        "nodeId",
+        "nodeName",
+        "checkpointNamespace"
+      ]) {
+        const raw = record[field];
+        if (typeof raw === "string" && raw.trim()) {
+          this.#registerUnique(
+            this.#langGraphIndex,
+            this.#langGraphIndexKey(field, raw),
+            stepId
+          );
+        }
+      }
     }
   }
+  #resolveParent(parentLcRunId, attributes) {
+    return resolveParentRelationship(
+      { parentLcRunId, attributes },
+      {
+        exactStepByLcRunId: (lcRunId) => this.#lcToStepId.get(lcRunId),
+        uniqueStepByLangGraphKey: (key, value) => {
+          const hit = this.#langGraphIndex.get(this.#langGraphIndexKey(key, value));
+          return hit === null || hit === void 0 ? void 0 : hit;
+        },
+        uniqueStepBySemanticLabel: (label) => {
+          const hit = this.#semanticLabelIndex.get(label);
+          return hit === null || hit === void 0 ? void 0 : hit;
+        }
+      }
+    );
+  }
+  /**
+   * When ≥2 steps share the same unresolved semantic parent label, emit one
+   * synthetic grouping node and attach this (and later) siblings under it.
+   * The first sibling remains unresolved (append-only JSONL cannot rewrite it).
+   */
+  async #maybeAttachSyntheticGroup(resolution, startTime) {
+    const label = resolution.semanticParentLabel;
+    if (resolution.parentMapping !== "unresolved" || !label || resolution.parentStepId) {
+      return resolution;
+    }
+    const existing = this.#syntheticByLabel.get(label);
+    if (existing) {
+      return {
+        parentStepId: existing,
+        confidence: "synthetic",
+        parentMapping: "synthetic-group",
+        semanticParentLabel: label,
+        unresolvedParentRunId: label
+      };
+    }
+    const nextCount = (this.#semanticParentCounts.get(label) ?? 0) + 1;
+    this.#semanticParentCounts.set(label, nextCount);
+    if (nextCount < 2) {
+      return resolution;
+    }
+    const syntheticStepId = createStepId();
+    this.#syntheticByLabel.set(label, syntheticStepId);
+    const metadata = {
+      adapter: "langchain",
+      confidence: "synthetic",
+      synthetic: true,
+      parentMapping: "synthetic-group",
+      parentConfidence: "synthetic",
+      semanticParentLabel: label,
+      unresolvedParentRunId: label
+    };
+    const event = {
+      schemaVersion: "0.1",
+      event: "step_started",
+      timestamp: startTime,
+      runId: this.#runId,
+      stepId: syntheticStepId,
+      name: `synthetic:${label}`,
+      type: "logic",
+      startTime,
+      metadata
+    };
+    await this.#write(event);
+    return {
+      parentStepId: syntheticStepId,
+      confidence: "synthetic",
+      parentMapping: "synthetic-group",
+      semanticParentLabel: label,
+      unresolvedParentRunId: label
+    };
+  }
+  /** Rotate when a prior standalone invocation already finalized. */
+  #prepareForStart() {
+    if (this.#standalone && this.#lifecycle.finalized) {
+      this.beginNewInvocation();
+    }
+  }
+  /**
+   * @deprecated Root-ID heuristics are no longer used for envelope completion.
+   * Retained as a no-op for call-site compatibility during the v6.8 train.
+   */
+  noteRoot(_lcRunId, _parentRunId) {
+  }
   resolveParentId(lcParentRunId) {
     if (!lcParentRunId) return void 0;
     return this.#lcToStepId.get(lcParentRunId);
   }
   async onStepStart(params) {
     try {
-      this.#finalizationToken += 1;
-      this.noteRoot(params.lcRunId, params.lcParentRunId);
-      this.#activeLcRunIds.add(params.lcRunId);
-      if (this.#standalone && !this.#runStarted) {
-        await this.#ensureRunStarted(params.startTime, params.attributes);
-      }
+      this.#prepareForStart();
       const stepId = createStepId();
       this.#lcToStepId.set(params.lcRunId, stepId);
-      const parentId = this.resolveParentId(params.lcParentRunId);
-      const metadata = toStepMetadata(params.attributes);
-      if (params.lcParentRunId && !parentId) {
-        metadata.parentMapping = "unresolved";
-        metadata.unresolvedParentRunId = params.lcParentRunId;
+      this.#registerStepIndexes(stepId, params.name, params.attributes);
+      beginCallbackRun(this.#lifecycle, {
+        lcRunId: params.lcRunId,
+        parentLcRunId: params.lcParentRunId,
+        startedAt: params.startTime,
+        kind: params.kind,
+        stepId
+      });
+      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 event = {
         schemaVersion: "0.1",
         event: "step_started",
         timestamp: params.startTime,
         runId: this.#runId,
         stepId,
-        ...parentId ? { parentId } : {},
+        ...resolution.parentStepId ? { parentId: resolution.parentStepId } : {},
         name: params.name,
         type: kindToStepType(params.kind),
         startTime: params.startTime,
@@ -428,35 +841,58 @@ var LangChainTracePersistence = class {
   }
   async onStepEnd(params) {
     try {
+      if (this.#lifecycle.finalized && !this.#lifecycle.activeRuns.has(params.lcRunId) && !this.#lcToStepId.has(params.lcRunId)) {
+        this.#lateEventCount += 1;
+        return;
+      }
       let stepId = this.#lcToStepId.get(params.lcRunId);
       if (!stepId && params.completionAttributes) {
+        if (this.#lifecycle.finalized) {
+          this.#lateEventCount += 1;
+          return;
+        }
         stepId = createStepId();
         this.#lcToStepId.set(params.lcRunId, stepId);
-        const parentId = this.resolveParentId(params.lcParentRunId);
-        const metadata = toStepMetadata(params.completionAttributes);
-        if (params.lcParentRunId && !parentId) {
-          metadata.parentMapping = "unresolved";
-          metadata.unresolvedParentRunId = params.lcParentRunId;
-        }
+        const synthName = String(params.completionAttributes.name ?? "llm:llm");
+        this.#registerStepIndexes(stepId, synthName, params.completionAttributes);
+        beginCallbackRun(this.#lifecycle, {
+          lcRunId: params.lcRunId,
+          parentLcRunId: params.lcParentRunId,
+          startedAt: params.endTime - (params.durationMs ?? 0),
+          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 started = {
           schemaVersion: "0.1",
           event: "step_started",
           timestamp: startTime,
           runId: this.#runId,
           stepId,
-          ...parentId ? { parentId } : {},
-          name: String(params.completionAttributes.name ?? "llm:llm"),
+          ...resolution.parentStepId ? { parentId: resolution.parentStepId } : {},
+          name: synthName,
           type: kindToStepType(
             params.completionAttributes.kind ?? "LLM"
           ),
           startTime,
           metadata
         };
+        if (this.#standalone && !this.#lifecycle.envelopeStarted) {
+          await this.#ensureRunStarted(startTime, params.completionAttributes);
+        }
         await this.#write(started);
       }
       if (!stepId) return;
-      const durationMs = typeof params.durationMs === "number" && Number.isFinite(params.durationMs) ? Math.max(0, Math.floor(params.durationMs)) : Math.max(0, params.endTime - (this.#runStartTime ?? params.endTime));
+      const durationMs = typeof params.durationMs === "number" && Number.isFinite(params.durationMs) ? Math.max(0, Math.floor(params.durationMs)) : Math.max(
+        0,
+        params.endTime - (this.#lifecycle.runStartTime ?? params.endTime)
+      );
       const event = {
         schemaVersion: "0.1",
         event: "step_completed",
@@ -470,10 +906,12 @@ var LangChainTracePersistence = class {
       };
       await this.#write(event);
       if (params.status === "error") {
-        this.#sawError = true;
-        if (params.errorMessage) this.#lastErrorMessage = params.errorMessage;
+        noteTerminalError(
+          this.#lifecycle,
+          params.errorMessage ?? "adapter step error"
+        );
       }
-      this.#activeLcRunIds.delete(params.lcRunId);
+      endCallbackRun(this.#lifecycle, params.lcRunId);
       await this.#scheduleStandaloneFinalization(params.endTime);
     } catch (err) {
       this.#warn(err);
@@ -482,27 +920,33 @@ var LangChainTracePersistence = class {
   /** Point-in-time adapter events (e.g. agent action) — writes start + completed pair. */
   async onInstantStep(params) {
     try {
-      this.#finalizationToken += 1;
-      this.noteRoot(params.lcRunId, params.lcParentRunId);
-      this.#activeLcRunIds.add(params.lcRunId);
-      if (this.#standalone && !this.#runStarted) {
-        await this.#ensureRunStarted(params.timestamp, params.attributes);
-      }
+      this.#prepareForStart();
       const stepId = createStepId();
       this.#lcToStepId.set(params.lcRunId, stepId);
-      const parentId = this.resolveParentId(params.lcParentRunId);
-      const metadata = toStepMetadata(params.attributes);
-      if (params.lcParentRunId && !parentId) {
-        metadata.parentMapping = "unresolved";
-        metadata.unresolvedParentRunId = params.lcParentRunId;
+      this.#registerStepIndexes(stepId, params.name, params.attributes);
+      beginCallbackRun(this.#lifecycle, {
+        lcRunId: params.lcRunId,
+        parentLcRunId: params.lcParentRunId,
+        startedAt: params.timestamp,
+        kind: params.kind,
+        stepId
+      });
+      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 started = {
         schemaVersion: "0.1",
         event: "step_started",
         timestamp: params.timestamp,
         runId: this.#runId,
         stepId,
-        ...parentId ? { parentId } : {},
+        ...resolution.parentStepId ? { parentId: resolution.parentStepId } : {},
         name: params.name,
         type: kindToStepType(params.kind),
         startTime: params.timestamp,
@@ -522,15 +966,71 @@ var LangChainTracePersistence = class {
       };
       await this.#write(completed);
       if (params.status === "error") {
-        this.#sawError = true;
-        if (params.errorMessage) this.#lastErrorMessage = params.errorMessage;
+        noteTerminalError(
+          this.#lifecycle,
+          params.errorMessage ?? "adapter step error"
+        );
       }
-      this.#activeLcRunIds.delete(params.lcRunId);
+      endCallbackRun(this.#lifecycle, params.lcRunId);
       await this.#scheduleStandaloneFinalization(params.timestamp);
     } catch (err) {
       this.#warn(err);
     }
   }
+  /**
+   * Drain deferred microtask finalization. Idempotent; never throws to callers.
+   * @experimental
+   */
+  async flush() {
+    try {
+      await Promise.resolve();
+      await Promise.resolve();
+    } catch (err) {
+      this.#warn(err);
+    }
+  }
+  /**
+   * Force-complete the standalone envelope when safe/started.
+   * Works even if active callback runs remain (unusual framework shapes / serverless).
+   * Idempotent; never throws to callers.
+   * @experimental
+   */
+  async finalize(options = {}) {
+    try {
+      if (!this.#standalone) return false;
+      if (this.#lifecycle.finalized) return false;
+      if (!this.#lifecycle.envelopeStarted) return false;
+      bumpCompletionGeneration(this.#lifecycle);
+      const status = options.status ?? (this.#lifecycle.terminalError ? "error" : "success");
+      if (status === "error") {
+        noteTerminalError(
+          this.#lifecycle,
+          options.errorMessage ?? this.#lifecycle.terminalError?.message ?? "adapter finalize error"
+        );
+      }
+      await this.#ensureRunCompleted(
+        options.endTime ?? Date.now(),
+        status,
+        status === "error" ? options.errorMessage ?? this.#lifecycle.terminalError?.message : void 0
+      );
+      return this.#lifecycle.finalized;
+    } catch (err) {
+      this.#warn(err);
+      return false;
+    }
+  }
+  /**
+   * Flush + finalize. Idempotent; never throws to callers.
+   * @experimental
+   */
+  async close() {
+    try {
+      await this.flush();
+      await this.finalize();
+    } catch (err) {
+      this.#warn(err);
+    }
+  }
   /**
    * When the last active LangChain callback ends, yield one microtask so a
    * same-turn sibling start can cancel finalization, then write run_completed
@@ -538,24 +1038,20 @@ var LangChainTracePersistence = class {
    * block the envelope.
    */
   async #scheduleStandaloneFinalization(endTime) {
-    if (!this.#standalone || this.#runCompleted || !this.#runStarted) return;
-    if (this.#activeLcRunIds.size > 0) return;
-    const token = ++this.#finalizationToken;
+    if (!this.#standalone || !canScheduleFinalize(this.#lifecycle)) return;
+    const generation = this.#lifecycle.completionGeneration;
     await Promise.resolve();
-    if (token !== this.#finalizationToken) return;
-    if (!this.#standalone || this.#runCompleted || !this.#runStarted) return;
-    if (this.#activeLcRunIds.size > 0) return;
-    const status = this.#sawError ? "error" : "success";
+    if (this.#lifecycle.completionGeneration !== generation) return;
+    if (!this.#standalone || !canScheduleFinalize(this.#lifecycle)) return;
+    const status = this.#lifecycle.terminalError ? "error" : "success";
     await this.#ensureRunCompleted(
       endTime,
       status,
-      status === "error" ? this.#lastErrorMessage : void 0
+      status === "error" ? this.#lifecycle.terminalError?.message : void 0
     );
   }
   async #ensureRunStarted(startTime, attrs) {
-    if (this.#runStarted) return;
-    this.#runStarted = true;
-    this.#runStartTime = startTime;
+    if (!markEnvelopeStarted(this.#lifecycle, startTime)) return;
     await initializeTraceFile(this.#runId, this.#traceDir);
     const metadata = {
       adapter: "langchain",
@@ -575,9 +1071,21 @@ var LangChainTracePersistence = class {
     await this.#write(event);
   }
   async #ensureRunCompleted(endTime, stepStatus, errorMessage) {
-    if (this.#runCompleted || !this.#runStarted) return;
-    this.#runCompleted = true;
-    const startTime = this.#runStartTime ?? endTime;
+    if (!markFinalized(this.#lifecycle)) return;
+    for (const [, syntheticStepId] of this.#syntheticByLabel) {
+      const completed = {
+        schemaVersion: "0.1",
+        event: "step_completed",
+        timestamp: endTime,
+        runId: this.#runId,
+        stepId: syntheticStepId,
+        status: "success",
+        endTime,
+        durationMs: Math.max(0, endTime - (this.#lifecycle.runStartTime ?? endTime))
+      };
+      await this.#write(completed);
+    }
+    const startTime = this.#lifecycle.runStartTime ?? endTime;
     const durationMs = Math.max(0, endTime - startTime);
     const runStatus = stepStatus === "error" ? "error" : "success";
     const event = {
@@ -607,20 +1115,11 @@ var LangChainTracePersistence = class {
 function isRecord2(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-function serializedLabel(s) {
+function serializedLabel2(s) {
   if (typeof s.name === "string" && s.name.trim()) return s.name;
   if (Array.isArray(s.id) && s.id.length > 0) return s.id[s.id.length - 1];
   return s.type;
 }
-function resolveToolDisplayName(tool, runName, metadata) {
-  const fromRun = typeof runName === "string" ? runName.trim() : "";
-  if (fromRun) return fromRun;
-  const metaName = metadata?.toolName;
-  if (typeof metaName === "string" && metaName.trim()) return metaName.trim();
-  const metaTool = metadata?.tool;
-  if (typeof metaTool === "string" && metaTool.trim()) return metaTool.trim();
-  return serializedLabel(tool) ?? "tool";
-}
 function errorShape(err) {
   if (err instanceof Error) {
     return { errorName: err.name, errorMessage: err.message };
@@ -629,6 +1128,11 @@ function errorShape(err) {
 }
 var AgentInspectCallback = class extends BaseCallbackHandler {
   name = "agent-inspect";
+  /**
+   * Ensure LangGraph/LangChain awaits async handler work (persistence) before
+   * invoke/stream settles. Required for deterministic standalone envelopes.
+   */
+  awaitHandlers = true;
   #opts;
   #redactor;
   #persistence;
@@ -639,16 +1143,22 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
   #rootRunId;
   constructor(options = {}) {
     super({});
+    const intent = resolvePersistIntent(options);
     this.#opts = {
       capture: options.capture ?? "metadata-only",
       silent: options.silent ?? false,
       maxPreviewChars: options.maxPreviewChars ?? 200,
-      persist: options.persist ?? false,
       runName: options.runName ?? "langchain-agent",
-      ...options
+      ...options,
+      persist: intent.persist
     };
     this.#redactor = new Redactor({ rules: this.#opts.redact });
-    if (this.#opts.persist) {
+    if (intent.contradictory && !this.#opts.silent) {
+      console.error(
+        "[agent-inspect:langchain] persist:false with traceDir set \u2014 traces stay in-memory; remove traceDir or set persist:true"
+      );
+    }
+    if (intent.persist) {
       this.#persistence = new LangChainTracePersistence({
         runName: this.#opts.runName,
         traceDir: this.#opts.traceDir,
@@ -674,6 +1184,91 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     this.#rootRunId = void 0;
     this.#persistence?.reset();
   }
+  /**
+   * Bounded adapter diagnostics for the current invocation (counts only).
+   * Safe for CLI/MCP summaries — no absolute paths or payloads.
+   *
+   * @experimental
+   */
+  getDiagnostics() {
+    const base = this.#persistence?.getDiagnostics() ?? {
+      lateEventCount: 0,
+      activeRunCount: 0,
+      endedRunCount: 0,
+      pendingRelationshipCount: 0,
+      knownRelationshipCount: 0,
+      syntheticGroupCount: 0,
+      envelopeStarted: false,
+      finalized: false,
+      completionGeneration: 0,
+      hasTerminalError: false
+    };
+    return {
+      ...base,
+      inMemoryEventCount: this.#events.length,
+      deferredPersistStartCount: this.#deferredPersistStart.size
+    };
+  }
+  /**
+   * Drain deferred completion work (microtask finalization).
+   * Idempotent. Failures are isolated and never thrown to user code.
+   *
+   * @experimental Additive finalization API for serverless / unusual callback shapes.
+   */
+  async flush() {
+    try {
+      await this.#persistence?.flush();
+    } catch (err) {
+      if (!this.#opts.silent) {
+        console.error("[agent-inspect:langchain]", err);
+      }
+    }
+  }
+  /**
+   * Complete the standalone envelope when started. Fallback when automatic
+   * completion cannot run (e.g. process shutdown). Idempotent.
+   * Failures are isolated and never thrown to user code.
+   *
+   * @experimental Additive finalization API for serverless / unusual callback shapes.
+   */
+  async finalize(options) {
+    try {
+      await this.#persistence?.finalize(options);
+    } catch (err) {
+      if (!this.#opts.silent) {
+        console.error("[agent-inspect:langchain]", err);
+      }
+    }
+  }
+  /**
+   * `flush()` then `finalize()`. Idempotent. Failures are isolated.
+   *
+   * @experimental Additive finalization API for serverless / unusual callback shapes.
+   */
+  async close() {
+    try {
+      await this.flush();
+      await this.finalize();
+    } catch (err) {
+      if (!this.#opts.silent) {
+        console.error("[agent-inspect:langchain]", err);
+      }
+    }
+  }
+  /**
+   * When persist mode has already finalized an envelope, rotate to a new
+   * invocation before the next start so reused handlers do not mix runs.
+   */
+  #prepareCallbackInvocation() {
+    const persistence = this.#persistence;
+    if (!persistence?.lifecycle.finalized) return;
+    this.#events = [];
+    this.#starts.clear();
+    this.#streamState.clear();
+    this.#deferredPersistStart.clear();
+    this.#rootRunId = void 0;
+    persistence.beginNewInvocation();
+  }
   #streamPreviewLimit() {
     if (this.#opts.capture !== "preview") return 0;
     return this.#opts.maxStreamPreviewChars ?? this.#opts.maxPreviewChars ?? 200;
@@ -768,7 +1363,11 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     if (parentRunId) out.parentRunId = parentRunId;
     if (this.#opts.runName) out.adapterRunName = this.#opts.runName;
     if (runNameArg) out.runName = runNameArg;
-    if (this.#opts.traceDir) out.traceDir = this.#opts.traceDir;
+    if (this.#opts.persist) out.traceStorage = "local";
+    const configuredTraceDir = this.#opts.traceDir?.trim();
+    if (configuredTraceDir && !path.isAbsolute(configuredTraceDir) && !/^[A-Za-z]:[\\/]/.test(configuredTraceDir)) {
+      out.workspaceRelativeTraceDir = configuredTraceDir;
+    }
     const cap = this.#opts.capture;
     if (cap !== "none" && tags?.length) out.tags = [...tags];
     return out;
@@ -831,9 +1430,10 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     });
   }
   async handleChainStart(chain, inputs, runId, runType, tags, metadata, runName, parentRunId, _extra) {
+    this.#prepareCallbackInvocation();
     this.#ensureRoot(runId, parentRunId);
     this.#rememberStart(runId, "CHAIN");
-    const label = serializedLabel(chain) ?? "chain";
+    const label = serializedLabel2(chain) ?? "chain";
     const previews = {};
     if (this.#opts.capture === "preview") previews.inputPreview = inputs;
     const attrs = {
@@ -912,6 +1512,7 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata, runName) {
+    this.#prepareCallbackInvocation();
     this.#ensureRoot(runId, parentRunId);
     this.#rememberStart(runId, "LLM");
     const model = extractModelName(llm);
@@ -944,6 +1545,7 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     await this.#persistLlmStepStart(runId, parentRunId, stepName, "LLM", ts, attrs);
   }
   async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata, runName) {
+    this.#prepareCallbackInvocation();
     this.#ensureRoot(runId, parentRunId);
     this.#rememberStart(runId, "LLM");
     const model = extractModelName(llm);
@@ -1062,21 +1664,22 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     });
     this.#clearStreamState(runId);
   }
-  async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName, _toolCallId) {
+  async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName, toolCallId) {
+    this.#prepareCallbackInvocation();
     this.#ensureRoot(runId, parentRunId);
     this.#rememberStart(runId, "TOOL");
-    const toolName = resolveToolDisplayName(tool, runName, metadata);
+    const identity = resolveToolIdentity(tool, runName, metadata, toolCallId);
     const previews = {};
     if (this.#opts.capture === "preview") previews.inputPreview = input;
     const attrs = {
-      ...this.#baseAttrs(runId, parentRunId, tags, runName),
-      tool: toolName
+      ...this.#baseAttrs(runId, parentRunId, tags, runName)
     };
+    applyToolIdentityAttributes(attrs, identity);
     this.#mergeMetadata(attrs, metadata);
     this.#applyPreview(attrs, previews);
     this.#rememberStartMetadata(runId, attrs);
     const ts = Date.now();
-    const stepName = `tool:${toolName}`;
+    const stepName = `tool:${identity.displayName}`;
     this.#pushEvent({
       eventId: `${runId}:TOOL:start`,
       runId: this.#traceRunId(runId),
@@ -1146,9 +1749,10 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleRetrieverStart(retriever, _query, runId, parentRunId, tags, metadata, name) {
+    this.#prepareCallbackInvocation();
     this.#ensureRoot(runId, parentRunId);
     this.#rememberStart(runId, "RETRIEVER");
-    const rname = name ?? serializedLabel(retriever) ?? "retriever";
+    const rname = name ?? serializedLabel2(retriever) ?? "retriever";
     const attrs = {
       ...this.#baseAttrs(runId, parentRunId, tags, void 0),
       retriever: rname
@@ -1229,6 +1833,7 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleAgentAction(action, runId, parentRunId, tags) {
+    this.#prepareCallbackInvocation();
     this.#ensureRoot(runId, parentRunId);
     const attrs = {
       ...this.#baseAttrs(runId, parentRunId, tags, void 0),