@agent-inspect/langchain 1.0.3 → 1.3.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-import { Redactor } from 'agent-inspect';
+import { Redactor, getCurrentCorrelationMetadata, hasActiveContext, getTraceDirFromContext, resolveTraceDir, getCurrentRunId, createRunId, resolveTraceSafetyOptions, createStepId, initializeTraceFile, prepareTraceEventForDisk, writeTraceEvent } from 'agent-inspect';
 
 // packages/langchain/src/agent-inspect-callback.ts
 
@@ -146,6 +146,300 @@ function toPlainMetadata(value) {
   }
 }
 
+// packages/langchain/src/streaming-metadata.ts
+function createLlmStreamState() {
+  return {
+    chunkCount: 0,
+    streamedCharCount: 0,
+    previewChars: "",
+    previewTruncated: false
+  };
+}
+function recordLlmStreamToken(state, token, now, maxPreviewChars) {
+  state.chunkCount += 1;
+  if (state.firstChunkAt === void 0) {
+    state.firstChunkAt = now;
+  }
+  state.lastChunkAt = now;
+  if (typeof token === "string" && token.length > 0) {
+    state.streamedCharCount += token.length;
+    if (maxPreviewChars > 0) {
+      const remaining = maxPreviewChars - state.previewChars.length;
+      if (remaining > 0) {
+        const slice = token.slice(0, remaining);
+        state.previewChars += slice;
+        if (token.length > remaining) {
+          state.previewTruncated = true;
+        }
+      } else {
+        state.previewTruncated = true;
+      }
+    }
+  }
+}
+function streamMetadataFromState(state, options) {
+  if (!state || state.chunkCount === 0) {
+    return void 0;
+  }
+  const out = {
+    stream: true,
+    chunkCount: state.chunkCount,
+    streamedCharCount: state.streamedCharCount
+  };
+  if (state.firstChunkAt !== void 0) {
+    out.firstChunkAt = state.firstChunkAt;
+  }
+  if (state.lastChunkAt !== void 0) {
+    out.lastChunkAt = state.lastChunkAt;
+  }
+  if (state.firstChunkAt !== void 0 && state.lastChunkAt !== void 0 && state.lastChunkAt >= state.firstChunkAt) {
+    out.streamDurationMs = state.lastChunkAt - state.firstChunkAt;
+  }
+  if (state.previewTruncated) {
+    out.previewTruncated = true;
+  }
+  if (options.capturePreview && state.previewChars.length > 0) {
+    const preview = state.previewChars.length <= options.maxPreviewChars ? state.previewChars : `${state.previewChars.slice(0, options.maxPreviewChars)}\u2026`;
+    out.streamPreview = preview;
+    if (state.previewChars.length > options.maxPreviewChars) {
+      out.previewTruncated = true;
+    }
+  }
+  return out;
+}
+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 = 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();
+    this.#runName = options.runName ?? "langchain-agent";
+    this.#safety = 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 = 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 {
+      let stepId = this.#lcToStepId.get(params.lcRunId);
+      if (!stepId && params.completionAttributes) {
+        stepId = createStepId();
+        this.#lcToStepId.set(params.lcRunId, stepId);
+        const parentId = this.resolveParentId(params.lcParentRunId);
+        const startTime = params.endTime - (params.durationMs ?? 0);
+        const started = {
+          schemaVersion: "0.1",
+          event: "step_started",
+          timestamp: startTime,
+          runId: this.#runId,
+          stepId,
+          ...parentId ? { parentId } : {},
+          name: String(params.completionAttributes.name ?? "llm:llm"),
+          type: kindToStepType(
+            params.completionAttributes.kind ?? "LLM"
+          ),
+          startTime,
+          metadata: toStepMetadata(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 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 = 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 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 = prepareTraceEventForDisk(event, this.#safety);
+    await 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) {
   if (typeof s.name === "string" && s.name.trim()) return s.name;
@@ -162,8 +456,11 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
   name = "agent-inspect";
   #opts;
   #redactor;
+  #persistence;
   #events = [];
   #starts = /* @__PURE__ */ new Map();
+  #streamState = /* @__PURE__ */ new Map();
+  #deferredPersistStart = /* @__PURE__ */ new Map();
   #rootRunId;
   constructor(options = {}) {
     super({});
@@ -171,9 +468,21 @@ var AgentInspectCallback = class extends 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 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) => ({
@@ -185,7 +494,70 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
   clear() {
     this.#events = [];
     this.#starts.clear();
+    this.#streamState.clear();
+    this.#deferredPersistStart.clear();
     this.#rootRunId = void 0;
+    this.#persistence?.reset();
+  }
+  #streamPreviewLimit() {
+    if (this.#opts.capture !== "preview") return 0;
+    return this.#opts.maxStreamPreviewChars ?? this.#opts.maxPreviewChars ?? 200;
+  }
+  #attachStreamMetadata(attrs, lcRunId) {
+    const meta = streamMetadataFromState(this.#streamState.get(lcRunId), {
+      capturePreview: this.#opts.capture === "preview",
+      maxPreviewChars: this.#streamPreviewLimit()
+    });
+    if (meta) {
+      Object.assign(attrs, meta);
+    }
+  }
+  #clearStreamState(lcRunId) {
+    this.#streamState.delete(lcRunId);
+    this.#deferredPersistStart.delete(lcRunId);
+  }
+  #mergeCorrelation(attrs) {
+    if (this.#opts.capture === "none") return;
+    try {
+      const corr = getCurrentCorrelationMetadata();
+      if (!corr) return;
+      for (const [key, value] of Object.entries(corr)) {
+        if (typeof value === "string" && value.length > 0) {
+          attrs[key] = value;
+        }
+      }
+    } catch {
+    }
+  }
+  async #persistLlmStepStart(lcRunId, lcParentRunId, name, kind, startTime, attributes) {
+    if (this.#opts.stream && this.#opts.persist) {
+      this.#deferredPersistStart.set(lcRunId, {
+        lcParentRunId,
+        name,
+        kind,
+        startTime,
+        attributes: { ...attributes }
+      });
+      return;
+    }
+    await this.#persistStepStart(lcRunId, lcParentRunId, name, kind, attributes, startTime);
+  }
+  async #flushDeferredPersistStart(lcRunId, completionAttributes) {
+    const pending = this.#deferredPersistStart.get(lcRunId);
+    if (!pending || !this.#opts.persist) return;
+    const merged = {
+      ...pending.attributes,
+      ...completionAttributes
+    };
+    await this.#persistStepStart(
+      lcRunId,
+      pending.lcParentRunId,
+      pending.name,
+      pending.kind,
+      merged,
+      pending.startTime
+    );
+    this.#deferredPersistStart.delete(lcRunId);
   }
   #ensureRoot(lcRunId, parentRunId) {
     if (parentRunId) return;
@@ -239,6 +611,39 @@ var AgentInspectCallback = class extends 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, completionAttributes) {
+    await this.#persistence?.onStepEnd({
+      lcRunId,
+      lcParentRunId,
+      endTime,
+      durationMs,
+      status,
+      errorMessage,
+      completionAttributes
+    });
+  }
+  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");
@@ -250,18 +655,20 @@ var AgentInspectCallback = class extends 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);
@@ -273,19 +680,21 @@ var AgentInspectCallback = class extends 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);
@@ -297,19 +706,21 @@ var AgentInspectCallback = class extends 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);
@@ -324,19 +735,23 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     };
     if (model && this.#opts.capture !== "none") attrs.model = model;
     this.#mergeMetadata(attrs, metadata);
+    this.#mergeCorrelation(attrs);
     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.#persistLlmStepStart(runId, parentRunId, stepName, "LLM", ts, attrs);
   }
   async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata, runName) {
     this.#ensureRoot(runId, parentRunId);
@@ -349,19 +764,38 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     };
     if (model && this.#opts.capture !== "none") attrs.model = model;
     this.#mergeMetadata(attrs, metadata);
+    this.#mergeCorrelation(attrs);
     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.#persistLlmStepStart(runId, parentRunId, stepName, "LLM", ts, attrs);
+  }
+  handleLLMNewToken(token, _idx, runId, _parentRunId, _tags, _fields) {
+    try {
+      if (!this.#opts.stream) return;
+      let state = this.#streamState.get(runId);
+      if (!state) {
+        state = createLlmStreamState();
+        this.#streamState.set(runId, state);
+      }
+      recordLlmStreamToken(state, token, Date.now(), this.#streamPreviewLimit());
+    } catch (err) {
+      if (!this.#opts.silent) {
+        console.error("[agent-inspect:langchain]", err);
+      }
+    }
   }
   async handleLLMEnd(output, runId, parentRunId, tags, _extraParams) {
     this.#ensureRoot(runId, parentRunId);
@@ -376,20 +810,30 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     };
     if (model && this.#opts.capture !== "none") attrs.model = model;
     if (tokens && this.#opts.capture !== "none") attrs.tokens = tokens;
+    this.#attachStreamMetadata(attrs, runId);
+    this.#mergeCorrelation(attrs);
     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.#flushDeferredPersistStart(runId, attrs);
+    await this.#persistStepEnd(runId, parentRunId, "success", ts, durationMs, void 0, {
+      ...attrs,
+      name: `llm:${model ?? "llm"}`,
+      kind: "LLM"
+    });
+    this.#clearStreamState(runId);
   }
   async handleLLMError(err, runId, parentRunId, tags, _extraParams) {
     this.#ensureRoot(runId, parentRunId);
@@ -401,19 +845,29 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
       errorName,
       errorMessage
     };
+    this.#attachStreamMetadata(attrs, runId);
+    this.#mergeCorrelation(attrs);
+    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.#flushDeferredPersistStart(runId, attrs);
+    await this.#persistStepEnd(runId, parentRunId, "error", ts, durationMs, errorMessage, {
+      ...attrs,
+      name: "llm:error",
+      kind: "LLM"
+    });
+    this.#clearStreamState(runId);
   }
   async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName, _toolCallId) {
     this.#ensureRoot(runId, parentRunId);
@@ -427,18 +881,21 @@ var AgentInspectCallback = class extends 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);
@@ -450,19 +907,21 @@ var AgentInspectCallback = class extends 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);
@@ -474,19 +933,21 @@ var AgentInspectCallback = class extends 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);
@@ -497,18 +958,21 @@ var AgentInspectCallback = class extends 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);
@@ -523,19 +987,21 @@ var AgentInspectCallback = class extends 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);
@@ -547,19 +1013,21 @@ var AgentInspectCallback = class extends 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);
@@ -585,6 +1053,7 @@ var AgentInspectCallback = class extends 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);
@@ -609,6 +1078,7 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
       confidence: "explicit",
       source: { type: "adapter" }
     });
+    await this.#persistInstant(runId, parentRunId, "agent:end", "AGENT", attrs, "success");
   }
 };