@agent-inspect/langchain 6.17.7 → 6.18.0

package/dist/index.d.cts

@@ -32,6 +32,42 @@ type RedactionRule = string | {
     keep?: number;
 };
 
+/** Named redaction presets for trace writing and share-safe exports (v1.3.0+). */
+type RedactionProfile = "local" | "share" | "strict";
+
+/**
+ * Capture policy shared by the official adapters.
+ *
+ * `metadata-only` is the default everywhere and never persists framework
+ * payload content. `preview` opts into bounded, redacted previews.
+ */
+type AdapterCaptureMode = "metadata-only" | "preview";
+/** Stable diagnostic codes emitted by shared preview capture. */
+declare const ADAPTER_CAPTURE_DIAGNOSTIC_CODES: readonly ["AI_CAPTURE_FIELD_UNAVAILABLE", "AI_CAPTURE_PREVIEW_TRUNCATED", "AI_CAPTURE_PREVIEW_REDACTED"];
+type AdapterCaptureDiagnosticCode = (typeof ADAPTER_CAPTURE_DIAGNOSTIC_CODES)[number];
+/** One bounded diagnostic. Never contains preview content or filesystem paths. */
+interface AdapterCaptureDiagnostic {
+    readonly code: AdapterCaptureDiagnosticCode;
+    readonly message: string;
+    /** Persisted attribute name the diagnostic refers to (e.g. `inputPreview`). */
+    readonly field: string;
+    readonly capture: AdapterCaptureMode;
+}
+/** Optional consumer hook for adapter capture diagnostics. */
+type AdapterDiagnosticListener = (diagnostic: AdapterCaptureDiagnostic) => void;
+/** Bounded capture counters for adapter `getDiagnostics()` surfaces. */
+interface AdapterCaptureDiagnostics {
+    readonly capture: AdapterCaptureMode;
+    readonly redactionProfile: RedactionProfile;
+    readonly maxPreviewChars: number;
+    readonly previewFieldsCaptured: number;
+    readonly previewFieldsUnavailable: number;
+    readonly previewFieldsTruncated: number;
+    readonly previewFieldsRedacted: number;
+    readonly lastDiagnosticCode?: AdapterCaptureDiagnosticCode;
+    readonly lastDiagnosticMessage?: string;
+}
+
 type CaptureMode = "none" | "metadata-only" | "preview";
 interface LangChainStreamingOptions {
     /**
@@ -53,6 +89,20 @@ interface AgentInspectCallbackOptions extends LangChainStreamingOptions {
     capture?: CaptureMode;
     redact?: RedactionRule[];
     maxPreviewChars?: number;
+    /**
+     * Redaction profile applied to preview attributes before persistence.
+     * `share` and `strict` also cap `maxPreviewChars`.
+     *
+     * @experimental Effective only when `capture: "preview"`.
+     */
+    redactionProfile?: RedactionProfile;
+    /**
+     * Receives bounded capture diagnostics such as
+     * `AI_CAPTURE_FIELD_UNAVAILABLE`. Listener failures are isolated.
+     *
+     * @experimental
+     */
+    onDiagnostic?: AdapterDiagnosticListener;
     /**
      * Persist callback lifecycle as schemaVersion "0.1" JSONL.
      * When omitted: enabled if `traceDir` is set, otherwise in-memory only.
@@ -106,6 +156,7 @@ declare class AgentInspectCallback extends BaseCallbackHandler {
         hasTerminalError: boolean;
         inMemoryEventCount: number;
         deferredPersistStartCount: number;
+        capture: AdapterCaptureDiagnostics;
     };
     /**
      * Drain deferred completion work (microtask finalization).
@@ -189,7 +240,12 @@ interface TokenUsage {
 declare function extractTokenUsage(output: unknown): TokenUsage | undefined;
 /** Best-effort model name from serialized LLM / chat model or provider metadata. */
 declare function extractModelName(serializedOrOutput: unknown): string | undefined;
-/** Safe truncated string preview for logging-style fields. */
+/**
+ * Safe truncated string preview for logging-style fields.
+ *
+ * Delegates to the shared adapter preview serializer so every official adapter
+ * bounds and escapes preview values identically.
+ */
 declare function safePreview(value: unknown, maxChars: number): string | undefined;
 /** Shallow plain metadata: drops functions/symbols; avoids deep nesting. Never throws. */
 declare function toPlainMetadata(value: unknown): Record<string, unknown>;

package/dist/index.d.ts

@@ -32,6 +32,42 @@ type RedactionRule = string | {
     keep?: number;
 };
 
+/** Named redaction presets for trace writing and share-safe exports (v1.3.0+). */
+type RedactionProfile = "local" | "share" | "strict";
+
+/**
+ * Capture policy shared by the official adapters.
+ *
+ * `metadata-only` is the default everywhere and never persists framework
+ * payload content. `preview` opts into bounded, redacted previews.
+ */
+type AdapterCaptureMode = "metadata-only" | "preview";
+/** Stable diagnostic codes emitted by shared preview capture. */
+declare const ADAPTER_CAPTURE_DIAGNOSTIC_CODES: readonly ["AI_CAPTURE_FIELD_UNAVAILABLE", "AI_CAPTURE_PREVIEW_TRUNCATED", "AI_CAPTURE_PREVIEW_REDACTED"];
+type AdapterCaptureDiagnosticCode = (typeof ADAPTER_CAPTURE_DIAGNOSTIC_CODES)[number];
+/** One bounded diagnostic. Never contains preview content or filesystem paths. */
+interface AdapterCaptureDiagnostic {
+    readonly code: AdapterCaptureDiagnosticCode;
+    readonly message: string;
+    /** Persisted attribute name the diagnostic refers to (e.g. `inputPreview`). */
+    readonly field: string;
+    readonly capture: AdapterCaptureMode;
+}
+/** Optional consumer hook for adapter capture diagnostics. */
+type AdapterDiagnosticListener = (diagnostic: AdapterCaptureDiagnostic) => void;
+/** Bounded capture counters for adapter `getDiagnostics()` surfaces. */
+interface AdapterCaptureDiagnostics {
+    readonly capture: AdapterCaptureMode;
+    readonly redactionProfile: RedactionProfile;
+    readonly maxPreviewChars: number;
+    readonly previewFieldsCaptured: number;
+    readonly previewFieldsUnavailable: number;
+    readonly previewFieldsTruncated: number;
+    readonly previewFieldsRedacted: number;
+    readonly lastDiagnosticCode?: AdapterCaptureDiagnosticCode;
+    readonly lastDiagnosticMessage?: string;
+}
+
 type CaptureMode = "none" | "metadata-only" | "preview";
 interface LangChainStreamingOptions {
     /**
@@ -53,6 +89,20 @@ interface AgentInspectCallbackOptions extends LangChainStreamingOptions {
     capture?: CaptureMode;
     redact?: RedactionRule[];
     maxPreviewChars?: number;
+    /**
+     * Redaction profile applied to preview attributes before persistence.
+     * `share` and `strict` also cap `maxPreviewChars`.
+     *
+     * @experimental Effective only when `capture: "preview"`.
+     */
+    redactionProfile?: RedactionProfile;
+    /**
+     * Receives bounded capture diagnostics such as
+     * `AI_CAPTURE_FIELD_UNAVAILABLE`. Listener failures are isolated.
+     *
+     * @experimental
+     */
+    onDiagnostic?: AdapterDiagnosticListener;
     /**
      * Persist callback lifecycle as schemaVersion "0.1" JSONL.
      * When omitted: enabled if `traceDir` is set, otherwise in-memory only.
@@ -106,6 +156,7 @@ declare class AgentInspectCallback extends BaseCallbackHandler {
         hasTerminalError: boolean;
         inMemoryEventCount: number;
         deferredPersistStartCount: number;
+        capture: AdapterCaptureDiagnostics;
     };
     /**
      * Drain deferred completion work (microtask finalization).
@@ -189,7 +240,12 @@ interface TokenUsage {
 declare function extractTokenUsage(output: unknown): TokenUsage | undefined;
 /** Best-effort model name from serialized LLM / chat model or provider metadata. */
 declare function extractModelName(serializedOrOutput: unknown): string | undefined;
-/** Safe truncated string preview for logging-style fields. */
+/**
+ * Safe truncated string preview for logging-style fields.
+ *
+ * Delegates to the shared adapter preview serializer so every official adapter
+ * bounds and escapes preview values identically.
+ */
 declare function safePreview(value: unknown, maxChars: number): string | undefined;
 /** Shallow plain metadata: drops functions/symbols; avoids deep nesting. Never throws. */
 declare function toPlainMetadata(value: unknown): Record<string, unknown>;

package/dist/index.mjs

@@ -1,11 +1,9 @@
 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 { serializeAdapterPreview, createAdapterPreviewCapture, getCurrentCorrelationMetadata, hasActiveContext, getTraceDirFromContext, resolveTraceDir, getCurrentRunId, createRunId, resolveTraceSafetyOptions, createStepId, initializeTraceFile, prepareTraceEventForDisk, writeTraceEvent } from 'agent-inspect/advanced';
 import { Redactor } from 'agent-inspect/logs';
 
 // packages/langchain/src/agent-inspect-callback.ts
-
-// packages/langchain/src/metadata.ts
 function isRecord(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -85,30 +83,7 @@ function extractModelName(serializedOrOutput) {
   }
 }
 function safePreview(value, maxChars) {
-  try {
-    if (maxChars <= 0) return void 0;
-    const seen = /* @__PURE__ */ new WeakSet();
-    const json = JSON.stringify(value, (_k, v) => {
-      if (typeof v === "bigint") return v.toString();
-      if (typeof v === "function" || typeof v === "symbol") return void 0;
-      if (typeof v === "object" && v !== null) {
-        if (seen.has(v)) return "[Circular]";
-        seen.add(v);
-      }
-      return v;
-    });
-    if (json === void 0) return void 0;
-    if (json.length <= maxChars) return json;
-    return `${json.slice(0, maxChars)}\u2026`;
-  } catch {
-    try {
-      const s = String(value);
-      if (s.length <= maxChars) return s;
-      return `${s.slice(0, maxChars)}\u2026`;
-    } catch {
-      return void 0;
-    }
-  }
+  return serializeAdapterPreview(value, maxChars);
 }
 var MAX_METADATA_KEYS = 40;
 var LANGGRAPH_ALIASES = [
@@ -660,7 +635,8 @@ var LangChainTracePersistence = class {
     this.#runName = options.runName ?? "langchain-agent";
     this.#safety = resolveTraceSafetyOptions({
       redact: options.redact ? { rules: options.redact } : true,
-      maxPreviewLength: options.maxPreviewChars
+      maxPreviewLength: options.maxPreviewChars,
+      ...options.redactionProfile ? { redactionProfile: options.redactionProfile } : {}
     });
     this.#lifecycle = createInvocationState(this.#runId);
   }
@@ -1233,6 +1209,7 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
   awaitHandlers = true;
   #opts;
   #redactor;
+  #capture;
   #persistence;
   #events = [];
   #starts = /* @__PURE__ */ new Map();
@@ -1251,6 +1228,13 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
       persist: intent.persist
     };
     this.#redactor = new Redactor({ rules: this.#opts.redact });
+    this.#capture = createAdapterPreviewCapture({
+      capture: this.#opts.capture === "preview" ? "preview" : "metadata-only",
+      redactionProfile: this.#opts.redactionProfile,
+      maxPreviewChars: this.#opts.maxPreviewChars,
+      redact: this.#opts.redact,
+      onDiagnostic: this.#opts.onDiagnostic
+    });
     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"
@@ -1263,7 +1247,8 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
         runId: this.#opts.runId,
         redact: this.#opts.redact,
         silent: this.#opts.silent,
-        maxPreviewChars: this.#opts.maxPreviewChars
+        maxPreviewChars: this.#capture.maxPreviewChars,
+        redactionProfile: this.#opts.redactionProfile
       });
     }
   }
@@ -1306,7 +1291,8 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     return {
       ...base,
       inMemoryEventCount: this.#events.length,
-      deferredPersistStartCount: this.#deferredPersistStart.size
+      deferredPersistStartCount: this.#deferredPersistStart.size,
+      capture: this.#capture.getDiagnostics()
     };
   }
   /**
@@ -1370,8 +1356,8 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     persistence.beginNewInvocation();
   }
   #streamPreviewLimit() {
-    if (this.#opts.capture !== "preview") return 0;
-    return this.#opts.maxStreamPreviewChars ?? this.#opts.maxPreviewChars ?? 200;
+    if (!this.#capture.previewEnabled) return 0;
+    return this.#opts.maxStreamPreviewChars ?? this.#capture.maxPreviewChars;
   }
   #attachStreamMetadata(attrs, lcRunId) {
     const meta = streamMetadataFromState(this.#streamState.get(lcRunId), {
@@ -1479,12 +1465,7 @@ var AgentInspectCallback = class extends BaseCallbackHandler {
     if (langGraph) attrs.langGraph = this.#redactor.redactRecord(langGraph);
   }
   #applyPreview(attrs, previews) {
-    if (this.#opts.capture !== "preview") return;
-    const max = this.#opts.maxPreviewChars;
-    for (const [k, v] of Object.entries(previews)) {
-      const p = safePreview(v, max);
-      if (p !== void 0) attrs[k] = p;
-    }
+    this.#capture.applyPreviewFields(attrs, previews);
   }
   #pushEvent(ev) {
     try {