@agent-inspect/langchain 1.0.3 → 1.1.0

package/dist/index.cjs

@@ -147,6 +147,217 @@ function toPlainMetadata(value) {
     return {};
   }
 }
+function kindToStepType(kind) {
+  switch (kind) {
+    case "LLM":
+      return "llm";
+    case "TOOL":
+      return "tool";
+    case "DECISION":
+      return "decision";
+    default:
+      return "logic";
+  }
+}
+function toStepMetadata(attrs) {
+  const out = {
+    adapter: "langchain",
+    confidence: "explicit"
+  };
+  for (const [k, v] of Object.entries(attrs)) {
+    out[k] = v;
+  }
+  return out;
+}
+var LangChainTracePersistence = class {
+  #traceDir;
+  #runId;
+  #runName;
+  #standalone;
+  #silent;
+  #safety;
+  #runStarted = false;
+  #runCompleted = false;
+  #runStartTime;
+  #rootLcRunId;
+  #lcToStepId = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    const inContext = agentInspect.hasActiveContext();
+    this.#standalone = !inContext;
+    this.#silent = options.silent ?? false;
+    this.#traceDir = inContext ? agentInspect.getTraceDirFromContext() ?? agentInspect.resolveTraceDir({ dir: options.traceDir }) : agentInspect.resolveTraceDir({ dir: options.traceDir });
+    this.#runId = (inContext ? agentInspect.getCurrentRunId() : void 0) ?? options.runId ?? agentInspect.createRunId();
+    this.#runName = options.runName ?? "langchain-agent";
+    this.#safety = agentInspect.resolveTraceSafetyOptions({
+      redact: options.redact ? { rules: options.redact } : true,
+      maxPreviewLength: options.maxPreviewChars
+    });
+  }
+  get runId() {
+    return this.#runId;
+  }
+  get traceDir() {
+    return this.#traceDir;
+  }
+  reset() {
+    this.#runStarted = false;
+    this.#runCompleted = false;
+    this.#runStartTime = void 0;
+    this.#rootLcRunId = void 0;
+    this.#lcToStepId.clear();
+  }
+  noteRoot(lcRunId, parentRunId) {
+    if (!parentRunId && !this.#rootLcRunId) {
+      this.#rootLcRunId = lcRunId;
+    }
+  }
+  resolveParentId(lcParentRunId) {
+    if (!lcParentRunId) return void 0;
+    return this.#lcToStepId.get(lcParentRunId);
+  }
+  async onStepStart(params) {
+    try {
+      this.noteRoot(params.lcRunId, params.lcParentRunId);
+      if (this.#standalone && !this.#runStarted) {
+        await this.#ensureRunStarted(params.startTime, params.attributes);
+      }
+      const stepId = agentInspect.createStepId();
+      this.#lcToStepId.set(params.lcRunId, stepId);
+      const parentId = this.resolveParentId(params.lcParentRunId);
+      const event = {
+        schemaVersion: "0.1",
+        event: "step_started",
+        timestamp: params.startTime,
+        runId: this.#runId,
+        stepId,
+        ...parentId ? { parentId } : {},
+        name: params.name,
+        type: kindToStepType(params.kind),
+        startTime: params.startTime,
+        metadata: toStepMetadata(params.attributes)
+      };
+      await this.#write(event);
+    } catch (err) {
+      this.#warn(err);
+    }
+  }
+  async onStepEnd(params) {
+    try {
+      const stepId = this.#lcToStepId.get(params.lcRunId);
+      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 event = {
+        schemaVersion: "0.1",
+        event: "step_completed",
+        timestamp: params.endTime,
+        runId: this.#runId,
+        stepId,
+        status: params.status,
+        endTime: params.endTime,
+        durationMs,
+        ...params.status === "error" && params.errorMessage ? { error: { message: params.errorMessage } } : {}
+      };
+      await this.#write(event);
+      if (this.#standalone && !this.#runCompleted && this.#rootLcRunId === params.lcRunId && !params.lcParentRunId) {
+        await this.#ensureRunCompleted(
+          params.endTime,
+          params.status,
+          params.errorMessage
+        );
+      }
+    } catch (err) {
+      this.#warn(err);
+    }
+  }
+  /** Point-in-time adapter events (e.g. agent action) — writes start + completed pair. */
+  async onInstantStep(params) {
+    try {
+      this.noteRoot(params.lcRunId, params.lcParentRunId);
+      if (this.#standalone && !this.#runStarted) {
+        await this.#ensureRunStarted(params.timestamp, params.attributes);
+      }
+      const stepId = agentInspect.createStepId();
+      this.#lcToStepId.set(params.lcRunId, stepId);
+      const parentId = this.resolveParentId(params.lcParentRunId);
+      const started = {
+        schemaVersion: "0.1",
+        event: "step_started",
+        timestamp: params.timestamp,
+        runId: this.#runId,
+        stepId,
+        ...parentId ? { parentId } : {},
+        name: params.name,
+        type: kindToStepType(params.kind),
+        startTime: params.timestamp,
+        metadata: toStepMetadata(params.attributes)
+      };
+      await this.#write(started);
+      const completed = {
+        schemaVersion: "0.1",
+        event: "step_completed",
+        timestamp: params.timestamp,
+        runId: this.#runId,
+        stepId,
+        status: params.status,
+        endTime: params.timestamp,
+        durationMs: 0,
+        ...params.status === "error" && params.errorMessage ? { error: { message: params.errorMessage } } : {}
+      };
+      await this.#write(completed);
+    } catch (err) {
+      this.#warn(err);
+    }
+  }
+  async #ensureRunStarted(startTime, attrs) {
+    if (this.#runStarted) return;
+    this.#runStarted = true;
+    this.#runStartTime = startTime;
+    await agentInspect.initializeTraceFile(this.#runId, this.#traceDir);
+    const metadata = {
+      adapter: "langchain",
+      confidence: "explicit"
+    };
+    if (attrs.langchainRunId) metadata.langchainRunId = attrs.langchainRunId;
+    if (attrs.adapterRunName) metadata.adapterRunName = attrs.adapterRunName;
+    const event = {
+      schemaVersion: "0.1",
+      event: "run_started",
+      timestamp: startTime,
+      runId: this.#runId,
+      name: this.#runName,
+      startTime,
+      metadata
+    };
+    await this.#write(event);
+  }
+  async #ensureRunCompleted(endTime, stepStatus, errorMessage) {
+    if (this.#runCompleted || !this.#runStarted) return;
+    this.#runCompleted = true;
+    const startTime = this.#runStartTime ?? endTime;
+    const durationMs = Math.max(0, endTime - startTime);
+    const runStatus = stepStatus === "error" ? "error" : "success";
+    const event = {
+      schemaVersion: "0.1",
+      event: "run_completed",
+      timestamp: endTime,
+      runId: this.#runId,
+      status: runStatus,
+      endTime,
+      durationMs,
+      ...runStatus === "error" && errorMessage ? { error: { message: errorMessage } } : {}
+    };
+    await this.#write(event);
+  }
+  async #write(event) {
+    const safe = agentInspect.prepareTraceEventForDisk(event, this.#safety);
+    await agentInspect.writeTraceEvent(safe, this.#traceDir);
+  }
+  #warn(err) {
+    if (!this.#silent) {
+      console.error("[agent-inspect:langchain]", err);
+    }
+  }
+};
 
 // packages/langchain/src/agent-inspect-callback.ts
 function serializedLabel(s) {
@@ -164,6 +375,7 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
   name = "agent-inspect";
   #opts;
   #redactor;
+  #persistence;
   #events = [];
   #starts = /* @__PURE__ */ new Map();
   #rootRunId;
@@ -173,9 +385,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       capture: options.capture ?? "metadata-only",
       silent: options.silent ?? false,
       maxPreviewChars: options.maxPreviewChars ?? 200,
+      persist: options.persist ?? false,
+      runName: options.runName ?? "langchain-agent",
       ...options
     };
     this.#redactor = new agentInspect.Redactor({ rules: this.#opts.redact });
+    if (this.#opts.persist) {
+      this.#persistence = new LangChainTracePersistence({
+        runName: this.#opts.runName,
+        traceDir: this.#opts.traceDir,
+        runId: this.#opts.runId,
+        redact: this.#opts.redact,
+        silent: this.#opts.silent,
+        maxPreviewChars: this.#opts.maxPreviewChars
+      });
+    }
   }
   getEvents() {
     return this.#events.map((e) => ({
@@ -188,6 +412,7 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
     this.#events = [];
     this.#starts.clear();
     this.#rootRunId = void 0;
+    this.#persistence?.reset();
   }
   #ensureRoot(lcRunId, parentRunId) {
     if (parentRunId) return;
@@ -241,6 +466,38 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       }
     }
   }
+  async #persistStepStart(lcRunId, lcParentRunId, name, kind, attrs, startTime) {
+    await this.#persistence?.onStepStart({
+      lcRunId,
+      lcParentRunId,
+      name,
+      kind,
+      startTime,
+      attributes: attrs
+    });
+  }
+  async #persistStepEnd(lcRunId, lcParentRunId, status, endTime, durationMs, errorMessage) {
+    await this.#persistence?.onStepEnd({
+      lcRunId,
+      lcParentRunId,
+      endTime,
+      durationMs,
+      status,
+      errorMessage
+    });
+  }
+  async #persistInstant(lcRunId, lcParentRunId, name, kind, attrs, status, errorMessage) {
+    await this.#persistence?.onInstantStep({
+      lcRunId,
+      lcParentRunId,
+      name,
+      kind,
+      timestamp: Date.now(),
+      attributes: attrs,
+      status,
+      errorMessage
+    });
+  }
   async handleChainStart(chain, inputs, runId, runType, tags, metadata, runName, parentRunId, _extra) {
     this.#ensureRoot(runId, parentRunId);
     this.#rememberStart(runId, "CHAIN");
@@ -252,18 +509,20 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
     };
     this.#mergeMetadata(attrs, metadata);
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:CHAIN:start`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: `chain:${runName ?? label}`,
       kind: "CHAIN",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "running",
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepStart(runId, parentRunId, `chain:${runName ?? label}`, "CHAIN", attrs, ts);
   }
   async handleChainEnd(outputs, runId, parentRunId, tags, _kwargs) {
     this.#ensureRoot(runId, parentRunId);
@@ -275,19 +534,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       ...this.#baseAttrs(runId, parentRunId, tags, void 0)
     };
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:CHAIN:end`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "chain:end",
       kind: "CHAIN",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "ok",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "success", ts, durationMs);
   }
   async handleChainError(err, runId, parentRunId, tags, _kwargs) {
     this.#ensureRoot(runId, parentRunId);
@@ -299,19 +560,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       errorName,
       errorMessage
     };
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:CHAIN:error`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "chain:error",
       kind: "CHAIN",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "error",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata, runName) {
     this.#ensureRoot(runId, parentRunId);
@@ -327,18 +590,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
     if (model && this.#opts.capture !== "none") attrs.model = model;
     this.#mergeMetadata(attrs, metadata);
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
+    const stepName = `llm:${model ?? "llm"}`;
     this.#pushEvent({
       eventId: `${runId}:LLM:start`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
-      name: `llm:${model ?? "llm"}`,
+      name: stepName,
       kind: "LLM",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "running",
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepStart(runId, parentRunId, stepName, "LLM", attrs, ts);
   }
   async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata, runName) {
     this.#ensureRoot(runId, parentRunId);
@@ -352,18 +618,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
     if (model && this.#opts.capture !== "none") attrs.model = model;
     this.#mergeMetadata(attrs, metadata);
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
+    const stepName = `llm:${model ?? "llm"}`;
     this.#pushEvent({
       eventId: `${runId}:CHAT:start`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
-      name: `llm:${model ?? "llm"}`,
+      name: stepName,
       kind: "LLM",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "running",
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepStart(runId, parentRunId, stepName, "LLM", attrs, ts);
   }
   async handleLLMEnd(output, runId, parentRunId, tags, _extraParams) {
     this.#ensureRoot(runId, parentRunId);
@@ -379,19 +648,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
     if (model && this.#opts.capture !== "none") attrs.model = model;
     if (tokens && this.#opts.capture !== "none") attrs.tokens = tokens;
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:LLM:end`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: `llm:${model ?? "llm"}`,
       kind: "LLM",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "ok",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "success", ts, durationMs);
   }
   async handleLLMError(err, runId, parentRunId, tags, _extraParams) {
     this.#ensureRoot(runId, parentRunId);
@@ -403,19 +674,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       errorName,
       errorMessage
     };
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:LLM:error`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "llm:error",
       kind: "LLM",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "error",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName, _toolCallId) {
     this.#ensureRoot(runId, parentRunId);
@@ -429,18 +702,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
     };
     this.#mergeMetadata(attrs, metadata);
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
+    const stepName = `tool:${toolName}`;
     this.#pushEvent({
       eventId: `${runId}:TOOL:start`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
-      name: `tool:${toolName}`,
+      name: stepName,
       kind: "TOOL",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "running",
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepStart(runId, parentRunId, stepName, "TOOL", attrs, ts);
   }
   async handleToolEnd(output, runId, parentRunId, tags) {
     this.#ensureRoot(runId, parentRunId);
@@ -452,19 +728,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       ...this.#baseAttrs(runId, parentRunId, tags, void 0)
     };
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:TOOL:end`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "tool:end",
       kind: "TOOL",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "ok",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "success", ts, durationMs);
   }
   async handleToolError(err, runId, parentRunId, tags) {
     this.#ensureRoot(runId, parentRunId);
@@ -476,19 +754,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       errorName,
       errorMessage
     };
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:TOOL:error`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "tool:error",
       kind: "TOOL",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "error",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleRetrieverStart(retriever, _query, runId, parentRunId, tags, metadata, name) {
     this.#ensureRoot(runId, parentRunId);
@@ -499,18 +779,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       retriever: rname
     };
     this.#mergeMetadata(attrs, metadata);
+    const ts = Date.now();
+    const stepName = `retriever:${rname}`;
     this.#pushEvent({
       eventId: `${runId}:RETRIEVER:start`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
-      name: `retriever:${rname}`,
+      name: stepName,
       kind: "RETRIEVER",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "running",
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepStart(runId, parentRunId, stepName, "RETRIEVER", attrs, ts);
   }
   async handleRetrieverEnd(documents, runId, parentRunId, tags) {
     this.#ensureRoot(runId, parentRunId);
@@ -525,19 +808,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       documentCount: documents.length
     };
     this.#applyPreview(attrs, previews);
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:RETRIEVER:end`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "retriever:end",
       kind: "RETRIEVER",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "ok",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "success", ts, durationMs);
   }
   async handleRetrieverError(err, runId, parentRunId, tags) {
     this.#ensureRoot(runId, parentRunId);
@@ -549,19 +834,21 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       errorName,
       errorMessage
     };
+    const ts = Date.now();
     this.#pushEvent({
       eventId: `${runId}:RETRIEVER:error`,
       runId: this.#traceRunId(runId),
       parentId: parentRunId,
       name: "retriever:error",
       kind: "RETRIEVER",
-      timestamp: Date.now(),
+      timestamp: ts,
       status: "error",
       durationMs,
       attributes: attrs,
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage);
   }
   async handleAgentAction(action, runId, parentRunId, tags) {
     this.#ensureRoot(runId, parentRunId);
@@ -587,6 +874,7 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistInstant(runId, parentRunId, "agent:action", "DECISION", attrs, "success");
   }
   async handleAgentEnd(finish, runId, parentRunId, tags) {
     this.#ensureRoot(runId, parentRunId);
@@ -611,6 +899,7 @@ var AgentInspectCallback = class extends base.BaseCallbackHandler {
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistInstant(runId, parentRunId, "agent:end", "AGENT", attrs, "success");
   }
 };