@agent-inspect/langchain 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentInspect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,623 @@
+'use strict';
+
+var base = require('@langchain/core/callbacks/base');
+var agentInspect = require('agent-inspect');
+
+// packages/langchain/src/agent-inspect-callback.ts
+
+// packages/langchain/src/metadata.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function num(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    if (Number.isFinite(n)) return n;
+  }
+  return void 0;
+}
+function normalizeTokenShape(raw) {
+  const input = num(raw.promptTokens) ?? num(raw.inputTokens) ?? num(raw.input_tokens) ?? num(raw.prompt_tokens);
+  const output = num(raw.completionTokens) ?? num(raw.outputTokens) ?? num(raw.output_tokens) ?? num(raw.completion_tokens);
+  let total = num(raw.totalTokens) ?? num(raw.total_tokens);
+  if (total === void 0 && input !== void 0 && output !== void 0) {
+    total = input + output;
+  }
+  if (input === void 0 && output === void 0 && total === void 0) {
+    return void 0;
+  }
+  const out = {};
+  if (input !== void 0) out.input = input;
+  if (output !== void 0) out.output = output;
+  if (total !== void 0) out.total = total;
+  return out;
+}
+function extractTokenUsage(output) {
+  try {
+    if (!isRecord(output)) return void 0;
+    const candidates = [
+      isRecord(output.llmOutput) ? output.llmOutput.tokenUsage : void 0,
+      isRecord(output.llmOutput) ? output.llmOutput.estimatedTokenUsage : void 0,
+      output.usage_metadata,
+      isRecord(output.response_metadata) ? output.response_metadata.tokenUsage : void 0,
+      isRecord(output.response_metadata) ? output.response_metadata.token_usage : void 0
+    ];
+    for (const c of candidates) {
+      if (!isRecord(c)) continue;
+      const norm = normalizeTokenShape(c);
+      if (norm) return norm;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readLcKwargs(serializedOrOutput) {
+  if (!isRecord(serializedOrOutput)) return void 0;
+  const lc = serializedOrOutput.lc_kwargs ?? serializedOrOutput.kwargs;
+  return isRecord(lc) ? lc : void 0;
+}
+function extractModelName(serializedOrOutput) {
+  try {
+    const lc = readLcKwargs(serializedOrOutput);
+    const fromLc = lc?.model ?? lc?.modelName ?? lc?.model_name;
+    if (typeof fromLc === "string" && fromLc.trim()) return fromLc;
+    if (isRecord(serializedOrOutput)) {
+      for (const k of ["model", "modelName", "model_name"]) {
+        const v = serializedOrOutput[k];
+        if (typeof v === "string" && v.trim()) return v;
+      }
+      const rm = serializedOrOutput.response_metadata;
+      if (isRecord(rm)) {
+        const m = rm.model_name ?? rm.model;
+        if (typeof m === "string" && m.trim()) return m;
+      }
+      const lo = serializedOrOutput.llmOutput;
+      if (isRecord(lo)) {
+        const m = lo.model_name;
+        if (typeof m === "string" && m.trim()) return m;
+      }
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+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;
+    }
+  }
+}
+var MAX_METADATA_KEYS = 40;
+function toPlainMetadata(value) {
+  try {
+    if (!isRecord(value)) return {};
+    const out = {};
+    let n = 0;
+    for (const [k, v] of Object.entries(value)) {
+      if (n >= MAX_METADATA_KEYS) break;
+      if (typeof v === "function" || typeof v === "symbol") continue;
+      if (v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+        out[k] = v;
+        n++;
+        continue;
+      }
+      if (typeof v === "bigint") {
+        out[k] = v.toString();
+        n++;
+        continue;
+      }
+      if (Array.isArray(v)) {
+        out[k] = `array(${v.length})`;
+        n++;
+        continue;
+      }
+      if (isRecord(v)) {
+        out[k] = "[object]";
+        n++;
+        continue;
+      }
+      out[k] = String(v);
+      n++;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// packages/langchain/src/agent-inspect-callback.ts
+function serializedLabel(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 errorShape(err) {
+  if (err instanceof Error) {
+    return { errorName: err.name, errorMessage: err.message };
+  }
+  return { errorMessage: String(err) };
+}
+var AgentInspectCallback = class extends base.BaseCallbackHandler {
+  name = "agent-inspect";
+  #opts;
+  #redactor;
+  #events = [];
+  #starts = /* @__PURE__ */ new Map();
+  #rootRunId;
+  constructor(options = {}) {
+    super({});
+    this.#opts = {
+      capture: options.capture ?? "metadata-only",
+      silent: options.silent ?? false,
+      maxPreviewChars: options.maxPreviewChars ?? 200,
+      ...options
+    };
+    this.#redactor = new agentInspect.Redactor({ rules: this.#opts.redact });
+  }
+  getEvents() {
+    return this.#events.map((e) => ({
+      ...e,
+      attributes: e.attributes ? { ...e.attributes } : void 0,
+      source: { ...e.source }
+    }));
+  }
+  clear() {
+    this.#events = [];
+    this.#starts.clear();
+    this.#rootRunId = void 0;
+  }
+  #ensureRoot(lcRunId, parentRunId) {
+    if (parentRunId) return;
+    if (!this.#rootRunId) this.#rootRunId = lcRunId;
+  }
+  #traceRunId(lcRunId) {
+    return this.#rootRunId ?? lcRunId;
+  }
+  #durationFor(lcRunId) {
+    const s = this.#starts.get(lcRunId);
+    if (!s) return void 0;
+    return Date.now() - s.ts;
+  }
+  #rememberStart(lcRunId, kind) {
+    this.#starts.set(lcRunId, { ts: Date.now(), kind });
+  }
+  #clearStart(lcRunId) {
+    this.#starts.delete(lcRunId);
+  }
+  #baseAttrs(lcRunId, parentRunId, tags, runNameArg) {
+    const out = {
+      langchainRunId: lcRunId
+    };
+    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;
+    const cap = this.#opts.capture;
+    if (cap !== "none" && tags?.length) out.tags = [...tags];
+    return out;
+  }
+  #mergeMetadata(attrs, metadata) {
+    if (this.#opts.capture === "none" || !metadata) return;
+    attrs.metadata = this.#redactor.redactRecord(toPlainMetadata(metadata));
+  }
+  #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;
+    }
+  }
+  #pushEvent(ev) {
+    try {
+      const attributes = ev.attributes ? this.#redactor.redactRecord({ ...ev.attributes }) : void 0;
+      this.#events.push({ ...ev, attributes });
+    } catch (err) {
+      if (!this.#opts.silent) {
+        console.error("[agent-inspect:langchain]", err);
+      }
+    }
+  }
+  async handleChainStart(chain, inputs, runId, runType, tags, metadata, runName, parentRunId, _extra) {
+    this.#ensureRoot(runId, parentRunId);
+    this.#rememberStart(runId, "CHAIN");
+    const label = serializedLabel(chain) ?? "chain";
+    const previews = {};
+    if (this.#opts.capture === "preview") previews.inputPreview = inputs;
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, runName)
+    };
+    this.#mergeMetadata(attrs, metadata);
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:CHAIN:start`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: `chain:${runName ?? label}`,
+      kind: "CHAIN",
+      timestamp: Date.now(),
+      status: "running",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleChainEnd(outputs, runId, parentRunId, tags, _kwargs) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const previews = {};
+    if (this.#opts.capture === "preview") previews.outputPreview = outputs;
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0)
+    };
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:CHAIN:end`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "chain:end",
+      kind: "CHAIN",
+      timestamp: Date.now(),
+      status: "ok",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleChainError(err, runId, parentRunId, tags, _kwargs) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const { errorName, errorMessage } = errorShape(err);
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      errorName,
+      errorMessage
+    };
+    this.#pushEvent({
+      eventId: `${runId}:CHAIN:error`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "chain:error",
+      kind: "CHAIN",
+      timestamp: Date.now(),
+      status: "error",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, tags, metadata, runName) {
+    this.#ensureRoot(runId, parentRunId);
+    this.#rememberStart(runId, "LLM");
+    const model = extractModelName(llm);
+    const previews = {};
+    if (this.#opts.capture === "preview") {
+      previews.promptPreview = prompts.length === 1 ? prompts[0] : prompts;
+    }
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, runName)
+    };
+    if (model && this.#opts.capture !== "none") attrs.model = model;
+    this.#mergeMetadata(attrs, metadata);
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:LLM:start`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: `llm:${model ?? "llm"}`,
+      kind: "LLM",
+      timestamp: Date.now(),
+      status: "running",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, tags, metadata, runName) {
+    this.#ensureRoot(runId, parentRunId);
+    this.#rememberStart(runId, "LLM");
+    const model = extractModelName(llm);
+    const previews = {};
+    if (this.#opts.capture === "preview") previews.inputPreview = messages;
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, runName)
+    };
+    if (model && this.#opts.capture !== "none") attrs.model = model;
+    this.#mergeMetadata(attrs, metadata);
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:CHAT:start`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: `llm:${model ?? "llm"}`,
+      kind: "LLM",
+      timestamp: Date.now(),
+      status: "running",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleLLMEnd(output, runId, parentRunId, tags, _extraParams) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const tokens = extractTokenUsage(output);
+    const model = extractModelName(output);
+    const previews = {};
+    if (this.#opts.capture === "preview") previews.outputPreview = output;
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0)
+    };
+    if (model && this.#opts.capture !== "none") attrs.model = model;
+    if (tokens && this.#opts.capture !== "none") attrs.tokens = tokens;
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:LLM:end`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: `llm:${model ?? "llm"}`,
+      kind: "LLM",
+      timestamp: Date.now(),
+      status: "ok",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleLLMError(err, runId, parentRunId, tags, _extraParams) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const { errorName, errorMessage } = errorShape(err);
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      errorName,
+      errorMessage
+    };
+    this.#pushEvent({
+      eventId: `${runId}:LLM:error`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "llm:error",
+      kind: "LLM",
+      timestamp: Date.now(),
+      status: "error",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName, _toolCallId) {
+    this.#ensureRoot(runId, parentRunId);
+    this.#rememberStart(runId, "TOOL");
+    const toolName = serializedLabel(tool) ?? "tool";
+    const previews = {};
+    if (this.#opts.capture === "preview") previews.inputPreview = input;
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, runName),
+      tool: toolName
+    };
+    this.#mergeMetadata(attrs, metadata);
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:TOOL:start`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: `tool:${toolName}`,
+      kind: "TOOL",
+      timestamp: Date.now(),
+      status: "running",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleToolEnd(output, runId, parentRunId, tags) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const previews = {};
+    if (this.#opts.capture === "preview") previews.outputPreview = output;
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0)
+    };
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:TOOL:end`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "tool:end",
+      kind: "TOOL",
+      timestamp: Date.now(),
+      status: "ok",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleToolError(err, runId, parentRunId, tags) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const { errorName, errorMessage } = errorShape(err);
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      errorName,
+      errorMessage
+    };
+    this.#pushEvent({
+      eventId: `${runId}:TOOL:error`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "tool:error",
+      kind: "TOOL",
+      timestamp: Date.now(),
+      status: "error",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleRetrieverStart(retriever, _query, runId, parentRunId, tags, metadata, name) {
+    this.#ensureRoot(runId, parentRunId);
+    this.#rememberStart(runId, "RETRIEVER");
+    const rname = name ?? serializedLabel(retriever) ?? "retriever";
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      retriever: rname
+    };
+    this.#mergeMetadata(attrs, metadata);
+    this.#pushEvent({
+      eventId: `${runId}:RETRIEVER:start`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: `retriever:${rname}`,
+      kind: "RETRIEVER",
+      timestamp: Date.now(),
+      status: "running",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleRetrieverEnd(documents, runId, parentRunId, tags) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const previews = {};
+    if (this.#opts.capture === "preview" && documents.length > 0) {
+      previews.documentPreview = documents.slice(0, 3);
+    }
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      documentCount: documents.length
+    };
+    this.#applyPreview(attrs, previews);
+    this.#pushEvent({
+      eventId: `${runId}:RETRIEVER:end`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "retriever:end",
+      kind: "RETRIEVER",
+      timestamp: Date.now(),
+      status: "ok",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleRetrieverError(err, runId, parentRunId, tags) {
+    this.#ensureRoot(runId, parentRunId);
+    const durationMs = this.#durationFor(runId);
+    this.#clearStart(runId);
+    const { errorName, errorMessage } = errorShape(err);
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      errorName,
+      errorMessage
+    };
+    this.#pushEvent({
+      eventId: `${runId}:RETRIEVER:error`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "retriever:error",
+      kind: "RETRIEVER",
+      timestamp: Date.now(),
+      status: "error",
+      durationMs,
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleAgentAction(action, runId, parentRunId, tags) {
+    this.#ensureRoot(runId, parentRunId);
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0),
+      tool: action.tool
+    };
+    if (this.#opts.capture === "preview") {
+      this.#applyPreview(attrs, {
+        toolInputPreview: action.toolInput,
+        logPreview: action.log
+      });
+    }
+    this.#pushEvent({
+      eventId: `${runId}:AGENT:action:${Date.now()}`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "agent:action",
+      kind: "DECISION",
+      timestamp: Date.now(),
+      status: "ok",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+  async handleAgentEnd(finish, runId, parentRunId, tags) {
+    this.#ensureRoot(runId, parentRunId);
+    const attrs = {
+      ...this.#baseAttrs(runId, parentRunId, tags, void 0)
+    };
+    if (this.#opts.capture === "preview") {
+      this.#applyPreview(attrs, {
+        outputPreview: finish.returnValues,
+        logPreview: finish.log
+      });
+    }
+    this.#pushEvent({
+      eventId: `${runId}:AGENT:end:${Date.now()}`,
+      runId: this.#traceRunId(runId),
+      parentId: parentRunId,
+      name: "agent:end",
+      kind: "AGENT",
+      timestamp: Date.now(),
+      status: "ok",
+      attributes: attrs,
+      confidence: "explicit",
+      source: { type: "adapter" }
+    });
+  }
+};
+
+exports.AgentInspectCallback = AgentInspectCallback;
+exports.extractModelName = extractModelName;
+exports.extractTokenUsage = extractTokenUsage;
+exports.safePreview = safePreview;
+exports.toPlainMetadata = toPlainMetadata;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map