@posthog/ai 8.8.1 → 8.9.0

package/dist/langchain/middleware/index.mjs

@@ -0,0 +1,1271 @@
+import { ToolMessage, AIMessage } from '@langchain/core/messages';
+import { convertToOpenAITool } from '@langchain/core/utils/function_calling';
+import { extendInteropZodObject } from '@langchain/core/utils/types';
+import { createMiddleware } from 'langchain';
+import { v7 } from 'uuid';
+import { z } from 'zod';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+
+// Type guards for safer type checking
+
+const isObject = value => {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+};
+
+/** @internal */
+
+/** @internal */
+
+/** @internal */
+function isFullAiCaptureEnabled(client) {
+  return client?.enableFullAiCapture === true;
+}
+
+/** @internal */
+function captureAiEvent(client, event) {
+  if (isFullAiCaptureEnabled(client) && typeof client.captureAi === 'function') {
+    client.captureAi(event);
+    return;
+  }
+  client.capture(event);
+}
+
+const DATA_URL_PREFIX_RE = /^data:([^;,\s]+)(?:;[^;,\s]+)*;base64,/i;
+const BASE64_ALPHABET_RE = /^[A-Za-z0-9+/_=-]+$/;
+class Base64Recognizer {
+  recognize(value, minLength) {
+    const dataUrl = DATA_URL_PREFIX_RE.exec(value);
+    if (dataUrl) return {
+      kind: 'data-url',
+      mediaType: dataUrl[1]
+    };
+    if (value.length < minLength) return {
+      kind: 'none'
+    };
+    const confidencePrefix = value.slice(0, minLength);
+    if (BASE64_ALPHABET_RE.test(confidencePrefix)) {
+      return {
+        kind: 'raw'
+      };
+    } else {
+      return {
+        kind: 'none'
+      };
+    }
+  }
+}
+
+const MIME_HINT_KEYS = ['mediaType', 'media_type', 'mimeType', 'mime_type'];
+const STRONG_CONTEXT_KEYS = new Set(['data', 'file_data', 'fileData', 'image_url', 'imageUrl', 'video_url', 'videoUrl', 'audio', 'audio_data', 'audioData', 'inline_data', 'inlineData', 'source', 'result']);
+const STRONG_CONTEXT_TYPES = new Set(['image', 'image_url', 'input_image', 'audio', 'input_audio', 'video', 'video_url', 'file', 'input_file', 'document', 'media', 'file-data']);
+const FILE_FAMILY_TYPES = new Set(['file', 'input_file', 'document', 'media', 'file-data']);
+const KNOWN_AUDIO_FORMATS = new Set(['wav', 'mp3', 'ogg', 'flac', 'm4a', 'aac', 'webm']);
+class MediaTypeContext {
+  static EMPTY = new MediaTypeContext(undefined, undefined);
+  constructor(parent, key, explicitMediaType) {
+    this.parent = parent;
+    this.key = key;
+    this.explicitMediaType = explicitMediaType;
+  }
+  inferMediaType() {
+    return this.inferFromSiblingMime() ?? this.inferFromSiblingFormat() ?? this.inferFromParentType() ?? this.inferFromKey();
+  }
+  inferFromSiblingMime() {
+    if (this.explicitMediaType) return this.explicitMediaType;
+    if (!this.parent) return undefined;
+    for (const hint of MIME_HINT_KEYS) {
+      const v = this.parent[hint];
+      if (typeof v === 'string') return v;
+    }
+    return undefined;
+  }
+  inferFromSiblingFormat() {
+    if (!this.parent) return undefined;
+    const fmt = this.parent.format;
+    if (typeof fmt === 'string' && KNOWN_AUDIO_FORMATS.has(fmt.toLowerCase())) {
+      return `audio/${fmt.toLowerCase()}`;
+    }
+    return undefined;
+  }
+  inferFromParentType() {
+    if (!this.parent) return undefined;
+    const t = this.parent.type;
+    if (typeof t !== 'string') return undefined;
+    if (t === 'image' || t === 'image_url' || t === 'input_image') return 'image';
+    if (t === 'audio' || t === 'input_audio') return 'audio';
+    if (t === 'video' || t === 'video_url') return 'video';
+    if (FILE_FAMILY_TYPES.has(t)) return 'application/octet-stream';
+    return undefined;
+  }
+  inferFromKey() {
+    if (!this.key) return undefined;
+    const key = this.key.toLowerCase();
+    if (key.includes('audio')) return 'audio';
+    if (key.includes('video')) return 'video';
+    if (key.includes('image')) return 'image';
+    if (key.includes('file') || key.includes('document')) return 'application/octet-stream';
+    return undefined;
+  }
+  hasExplicitBinaryMediaType() {
+    if (!this.explicitMediaType && (!this.parent || !this.key || !STRONG_CONTEXT_KEYS.has(this.key))) return false;
+    const mediaType = this.inferFromSiblingMime();
+    return mediaType !== undefined && !mediaType.toLowerCase().startsWith('text/');
+  }
+  signalsBinary() {
+    if (this.explicitMediaType) return true;
+    if (this.parent) {
+      for (const hint of MIME_HINT_KEYS) {
+        if (typeof this.parent[hint] === 'string') return true;
+      }
+      const fmt = this.parent.format;
+      if (typeof fmt === 'string' && KNOWN_AUDIO_FORMATS.has(fmt.toLowerCase())) return true;
+      const t = this.parent.type;
+      if (typeof t === 'string' && STRONG_CONTEXT_TYPES.has(t)) return true;
+    }
+    if (this.key && STRONG_CONTEXT_KEYS.has(this.key)) return true;
+    return false;
+  }
+}
+
+const STRONG_CONTEXT_MIN_LENGTH = 64;
+const WEAK_CONTEXT_MIN_LENGTH = 1024;
+class BinaryContentRedactor {
+  visited = new WeakSet();
+  constructor(recognizer = new Base64Recognizer()) {
+    this.recognizer = recognizer;
+  }
+  redact(value, mediaType) {
+    this.visited = new WeakSet();
+    return this.walk(value, mediaType ? new MediaTypeContext(undefined, undefined, mediaType) : MediaTypeContext.EMPTY);
+  }
+  walk(value, ctx) {
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'string') return this.redactString(value, ctx);
+    if (typeof value !== 'object') return value;
+
+    // Buffer extends Uint8Array, so this branch catches both.
+    if (typeof Uint8Array !== 'undefined' && value instanceof Uint8Array) {
+      return this.placeholderFor(ctx.inferMediaType());
+    }
+    if (this.visited.has(value)) return null;
+    this.visited.add(value);
+    if (Array.isArray(value)) {
+      return value.map(item => this.walk(item, ctx));
+    }
+    const obj = value;
+    const out = {};
+    for (const k of Object.keys(obj)) {
+      out[k] = this.walk(obj[k], new MediaTypeContext(obj, k));
+    }
+    return out;
+  }
+  redactString(value, ctx) {
+    const hasExplicitBinaryMediaType = ctx.hasExplicitBinaryMediaType();
+    const recognitionValue = hasExplicitBinaryMediaType ? value.replace(/[\r\n]/g, '') : value;
+    const minLength = hasExplicitBinaryMediaType ? Math.min(recognitionValue.length, STRONG_CONTEXT_MIN_LENGTH) : ctx.signalsBinary() ? STRONG_CONTEXT_MIN_LENGTH : WEAK_CONTEXT_MIN_LENGTH;
+    const recognition = this.recognizer.recognize(recognitionValue, minLength);
+    switch (recognition.kind) {
+      case 'data-url':
+        return this.placeholderFor(recognition.mediaType);
+      case 'raw':
+        return this.placeholderFor(ctx.inferMediaType());
+      case 'none':
+        return value;
+    }
+  }
+  placeholderFor(mediaType) {
+    if (!mediaType) return '[base64 redacted]';
+    if (mediaType === 'application/octet-stream') return '[base64 file redacted]';
+    return `[base64 ${mediaType} redacted]`;
+  }
+}
+
+const redactor = new BinaryContentRedactor();
+const sanitize = (data, client) => isFullAiCaptureEnabled(client) ? data : redactor.redact(data);
+const sanitizeLangChain = (data, client) => sanitize(data, client);
+
+const STRING_FORMAT = 'utf8';
+
+// Reused across calls to avoid per-invocation allocation; truncate() runs
+// hundreds of times for prompts with many parts.
+new TextEncoder();
+new TextDecoder(STRING_FORMAT, {
+  fatal: false
+});
+
+/**
+ * Safely converts content to a string, preserving structure for objects/arrays.
+ * - If content is already a string, returns it as-is
+ * - If content is an object or array, stringifies it with JSON.stringify to preserve structure
+ * - Otherwise, converts to string with String()
+ *
+ * This prevents the "[object Object]" bug when objects are naively converted to strings.
+ *
+ * @param content - The content to convert to a string
+ * @returns A string representation that preserves structure for complex types
+ */
+function toContentString(content) {
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (content !== undefined && content !== null && typeof content === 'object') {
+    try {
+      return JSON.stringify(content);
+    } catch {
+      // Fallback for circular refs, BigInt, or objects with throwing toJSON
+      return String(content);
+    }
+  }
+  return String(content);
+}
+const getModelParams = (params, responseServiceTier) => {
+  if (!params) {
+    return {};
+  }
+  const modelParams = {};
+  const paramKeys = ['temperature', 'max_tokens', 'max_completion_tokens', 'top_p', 'frequency_penalty', 'presence_penalty', 'n', 'stop', 'stream', 'streaming', 'language', 'response_format', 'timestamp_granularities', 'service_tier'];
+  for (const key of paramKeys) {
+    if (key in params && params[key] !== undefined) {
+      modelParams[key] = params[key];
+    }
+  }
+  return modelParams;
+};
+const withPrivacyMode = (client, privacyMode, input) => {
+  return client.privacy_mode || privacyMode ? null : input;
+};
+function sanitizeValues(obj) {
+  if (obj === undefined || obj === null) {
+    return obj;
+  }
+  const jsonSafe = JSON.parse(JSON.stringify(obj));
+  if (typeof jsonSafe === 'string') {
+    // Sanitize lone surrogates by round-tripping through UTF-8
+    return new TextDecoder().decode(new TextEncoder().encode(jsonSafe));
+  } else if (Array.isArray(jsonSafe)) {
+    return jsonSafe.map(sanitizeValues);
+  } else if (jsonSafe && typeof jsonSafe === 'object') {
+    return Object.fromEntries(Object.entries(jsonSafe).map(([k, v]) => [k, sanitizeValues(v)]));
+  }
+  return jsonSafe;
+}
+
+var version = "8.9.0";
+
+const DEFAULT_MAX_DEPTH = 3;
+const MAX_STACK_LINES = 20;
+function serializeError(value, depth = DEFAULT_MAX_DEPTH) {
+  if (depth < 0 || value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (value instanceof Error) {
+    const out = {
+      name: value.name,
+      message: value.message,
+      stack: truncateStack(value.stack)
+    };
+    for (const key of Object.keys(value)) {
+      out[key] = serializeError(value[key], depth - 1);
+    }
+    if (value.cause !== undefined) {
+      out.cause = serializeError(value.cause, depth - 1);
+    }
+    return out;
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => serializeError(item, depth - 1));
+  }
+  return value;
+}
+function stringifyError(error) {
+  try {
+    return JSON.stringify(sanitizeValues(serializeError(error)));
+  } catch {
+    if (error instanceof Error) {
+      return JSON.stringify({
+        name: error.name,
+        message: error.message
+      });
+    }
+    return JSON.stringify({
+      message: String(error)
+    });
+  }
+}
+function truncateStack(stack) {
+  if (!stack) {
+    return stack;
+  }
+  const lines = stack.split('\n');
+  if (lines.length <= MAX_STACK_LINES) {
+    return stack;
+  }
+  return [...lines.slice(0, MAX_STACK_LINES), '... (truncated)'].join('\n');
+}
+
+// Warn when a wrapper's base_url points at the PostHog AI Gateway: the gateway
+// emits its own $ai_generation, so each call would be captured (and, for billable
+// products, billed) twice. We only warn — the wrapper's event carries data the
+// gateway never sees (groups, custom properties, trace hierarchy).
+
+// Keep in sync with the gateway's deployed hosts (see services/llm-gateway in the
+// main repo). gateway.us.posthog.com is live today; the rest are listed ahead of
+// any traffic moving to them.
+const POSTHOG_AI_GATEWAY_HOSTS = ['gateway.posthog.com', 'gateway.us.posthog.com', 'gateway.eu.posthog.com', 'ai-gateway.us.posthog.com', 'ai-gateway.eu.posthog.com'];
+
+// Swap for the dedicated AI Gateway page once it ships.
+const GATEWAY_DOCS_URL = 'https://posthog.com/docs/ai-observability';
+const extractHost = baseURL => {
+  try {
+    // Tolerate bare hosts that omit a scheme, e.g. "gateway.us.posthog.com/v1".
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(baseURL);
+    return new URL(hasScheme ? baseURL : `https://${baseURL}`).hostname.toLowerCase();
+  } catch {
+    return undefined;
+  }
+};
+const isPostHogAiGatewayUrl = baseURL => {
+  if (!baseURL) {
+    return false;
+  }
+  const host = extractHost(baseURL);
+  return host !== undefined && POSTHOG_AI_GATEWAY_HOSTS.includes(host);
+};
+
+// Warns on every gateway call by design: the misconfiguration is impossible to
+// miss that way, and a doubled bill is worse than noisy logs.
+const warnIfPostHogAiGateway = baseURL => {
+  if (!isPostHogAiGatewayUrl(baseURL)) {
+    return;
+  }
+  console.warn('[PostHog] The PostHog AI wrapper is pointed at the PostHog AI Gateway. ' + 'Both capture $ai_generation, so every call is double-counted and double-billed. ' + `Use one or the other — see ${GATEWAY_DOCS_URL}.`);
+};
+
+// Mirror LangGraph's isGraphBubbleUp guard without adding LangGraph as a dependency. Every
+// LangGraph control-flow exception (GraphInterrupt, NodeInterrupt, ParentCommand, GraphDrained,
+// and future subclasses) exposes a prototype getter `is_bubble_up` that returns true, which the
+// LangGraph runtime itself uses to distinguish control flow from real failures. The getter reads
+// as undefined on ordinary Errors and works across duplicated LangGraph package copies.
+const isLangGraphControlFlow = error => error.is_bubble_up === true;
+
+/** A run may either be a Span or a Generation */
+
+/** Storage for run metadata */
+
+class LangChainCallbackHandler extends BaseCallbackHandler {
+  name = 'PosthogCallbackHandler';
+  runs = {};
+  parentTree = {};
+  constructor(options) {
+    if (!options.client) {
+      throw new Error('PostHog client is required');
+    }
+    super();
+    this.client = options.client;
+    this.distinctId = options.distinctId;
+    this.traceId = options.traceId;
+    this.properties = options.properties || {};
+    this.privacyMode = options.privacyMode || false;
+    this.groups = options.groups || {};
+    this.debug = options.debug || false;
+  }
+
+  // ===== CALLBACK METHODS =====
+
+  handleChainStart(chain, inputs, runId, parentRunId, tags, metadata, _runType, runName, extra) {
+    this._logDebugEvent('on_chain_start', runId, parentRunId, {
+      inputs,
+      tags
+    });
+    this._setParentOfRun(runId, parentRunId);
+    this._setTraceOrSpanMetadata(chain, inputs, runId, parentRunId, metadata, tags, runName);
+    if (typeof extra?.posthogStartTime === 'number' && Number.isFinite(extra.posthogStartTime)) {
+      this.runs[runId].startTime = extra.posthogStartTime;
+    }
+  }
+  handleChainEnd(outputs, runId, parentRunId, tags, _kwargs) {
+    this._logAndPopTraceOrSpan('on_chain_end', runId, parentRunId, {
+      outputs,
+      tags
+    }, outputs);
+  }
+  handleChainError(error, runId, parentRunId, tags, _kwargs) {
+    this._logAndPopTraceOrSpan('on_chain_error', runId, parentRunId, {
+      error,
+      tags
+    }, error);
+  }
+  handleChatModelStart(serialized, messages, runId, parentRunId, extraParams, tags, metadata, runName) {
+    this._logDebugEvent('on_chat_model_start', runId, parentRunId, {
+      messages,
+      tags
+    });
+    this._setParentOfRun(runId, parentRunId);
+    // Flatten the two-dimensional messages and convert each message to a plain object
+    const input = messages.flat().map(m => this._convertMessageToDict(m));
+    this._setLLMMetadata(serialized, runId, input, metadata, extraParams, runName);
+  }
+  handleLLMStart(serialized, prompts, runId, parentRunId, extraParams, tags, metadata, runName) {
+    this._logDebugEvent('on_llm_start', runId, parentRunId, {
+      prompts,
+      tags
+    });
+    this._setParentOfRun(runId, parentRunId);
+    this._setLLMMetadata(serialized, runId, prompts, metadata, extraParams, runName);
+  }
+  handleLLMEnd(output, runId, parentRunId, tags, _extraParams) {
+    this._logAndPopGeneration('on_llm_end', runId, parentRunId, {
+      output,
+      tags
+    }, output);
+  }
+  handleLLMError(err, runId, parentRunId, tags, _extraParams) {
+    this._logAndPopGeneration('on_llm_error', runId, parentRunId, {
+      err,
+      tags
+    }, err);
+  }
+  handleToolStart(tool, input, runId, parentRunId, tags, metadata, runName) {
+    this._logAndSetTraceOrSpan('on_tool_start', tool, input, runId, parentRunId, {
+      input,
+      tags
+    }, tags, metadata, runName);
+  }
+  handleToolEnd(output, runId, parentRunId, tags) {
+    this._logAndPopTraceOrSpan('on_tool_end', runId, parentRunId, {
+      output,
+      tags
+    }, output);
+  }
+  handleToolError(err, runId, parentRunId, tags) {
+    this._logAndPopTraceOrSpan('on_tool_error', runId, parentRunId, {
+      err,
+      tags
+    }, err);
+  }
+  handleRetrieverStart(retriever, query, runId, parentRunId, tags, metadata, name) {
+    this._logAndSetTraceOrSpan('on_retriever_start', retriever, query, runId, parentRunId, {
+      query,
+      tags
+    }, tags, metadata, name);
+  }
+  handleRetrieverEnd(documents, runId, parentRunId, tags) {
+    this._logAndPopTraceOrSpan('on_retriever_end', runId, parentRunId, {
+      documents,
+      tags
+    }, documents);
+  }
+  handleRetrieverError(err, runId, parentRunId, tags) {
+    this._logAndPopTraceOrSpan('on_retriever_error', runId, parentRunId, {
+      err,
+      tags
+    }, err);
+  }
+  handleAgentAction(action, runId, parentRunId, tags) {
+    this._logDebugEvent('on_agent_action', runId, parentRunId, {
+      action,
+      tags
+    });
+    this._setParentOfRun(runId, parentRunId);
+    this._setTraceOrSpanMetadata(null, action, runId, parentRunId);
+  }
+  handleAgentEnd(action, runId, parentRunId, tags) {
+    this._logDebugEvent('on_agent_finish', runId, parentRunId, {
+      action,
+      tags
+    });
+    this._popRunAndCaptureTraceOrSpan(runId, parentRunId, action);
+  }
+
+  // ===== PRIVATE HELPERS =====
+
+  _logAndSetTraceOrSpan(eventName, serialized, input, runId, parentRunId, debugPayload, tags, metadata, runName) {
+    this._logDebugEvent(eventName, runId, parentRunId, debugPayload);
+    this._setParentOfRun(runId, parentRunId);
+    this._setTraceOrSpanMetadata(serialized, input, runId, parentRunId, metadata, tags, runName);
+  }
+  _logAndPopTraceOrSpan(eventName, runId, parentRunId, debugPayload, result) {
+    this._logDebugEvent(eventName, runId, parentRunId, debugPayload);
+    this._popRunAndCaptureTraceOrSpan(runId, parentRunId, result);
+  }
+  _logAndPopGeneration(eventName, runId, parentRunId, debugPayload, result) {
+    this._logDebugEvent(eventName, runId, parentRunId, debugPayload);
+    this._popRunAndCaptureGeneration(runId, parentRunId, result);
+  }
+  _setParentOfRun(runId, parentRunId) {
+    if (parentRunId) {
+      this.parentTree[runId] = parentRunId;
+    }
+  }
+  _popParentOfRun(runId) {
+    delete this.parentTree[runId];
+  }
+  _findRootRun(runId) {
+    let id = runId;
+    while (this.parentTree[id]) {
+      id = this.parentTree[id];
+    }
+    return id;
+  }
+  _setTraceOrSpanMetadata(serialized, input, runId, parentRunId, ...args) {
+    // Use default names if not provided: if this is a top-level run, we mark it as a trace, otherwise as a span.
+    const defaultName = parentRunId ? 'span' : 'trace';
+    const runName = this._getLangchainRunName(serialized, ...args) || defaultName;
+    this.runs[runId] = {
+      name: runName,
+      input,
+      startTime: Date.now()
+    };
+  }
+  _setLLMMetadata(serialized, runId, messages, metadata, extraParams, runName) {
+    const runNameFound = this._getLangchainRunName(serialized, {
+      extraParams,
+      runName
+    }) || 'generation';
+    const generation = {
+      name: runNameFound,
+      input: sanitizeLangChain(messages, this.client),
+      startTime: Date.now()
+    };
+    if (extraParams) {
+      generation.modelParams = getModelParams(extraParams.invocation_params);
+      if (extraParams.invocation_params && extraParams.invocation_params.tools) {
+        generation.tools = extraParams.invocation_params.tools;
+      }
+    }
+    if (metadata) {
+      if (metadata.ls_model_name) {
+        generation.model = metadata.ls_model_name;
+      }
+      if (metadata.ls_provider) {
+        generation.provider = metadata.ls_provider;
+      }
+    }
+    if (serialized && 'kwargs' in serialized && serialized.kwargs.openai_api_base) {
+      generation.baseUrl = serialized.kwargs.openai_api_base;
+    }
+    this.runs[runId] = generation;
+  }
+  _popRunMetadata(runId) {
+    const endTime = Date.now();
+    const run = this.runs[runId];
+    if (!run) {
+      console.warn(`No run metadata found for run ${runId}`);
+      return undefined;
+    }
+    run.endTime = endTime;
+    delete this.runs[runId];
+    return run;
+  }
+  _getTraceId(runId) {
+    return this.traceId ? String(this.traceId) : this._findRootRun(runId);
+  }
+  _getParentRunId(traceId, _runId, parentRunId) {
+    // Replace the parent-run if not found in our stored parent tree.
+    if (parentRunId && !this.parentTree[parentRunId]) {
+      return traceId;
+    }
+    return parentRunId;
+  }
+  _safeCapture(message) {
+    try {
+      captureAiEvent(this.client, message);
+    } catch {
+      // Telemetry delivery must never affect the LangChain callback lifecycle.
+    }
+  }
+  _popRunAndCaptureTraceOrSpan(runId, parentRunId, outputs) {
+    const traceId = this._getTraceId(runId);
+    const isSpan = Boolean(parentRunId || this.parentTree[runId]);
+    this._popParentOfRun(runId);
+    const run = this._popRunMetadata(runId);
+    if (!run) {
+      return;
+    }
+    if ('modelParams' in run) {
+      console.warn(`Run ${runId} is a generation, but attempted to be captured as a trace/span.`);
+      return;
+    }
+    const actualParentRunId = this._getParentRunId(traceId, runId, parentRunId);
+    this._captureTraceOrSpan(traceId, runId, run, outputs, isSpan, actualParentRunId);
+  }
+  _captureTraceOrSpan(traceId, runId, run, outputs, isSpan, parentRunId) {
+    const eventName = isSpan ? '$ai_span' : '$ai_trace';
+    const latency = run.endTime ? (run.endTime - run.startTime) / 1000 : 0;
+    const eventProperties = {
+      $ai_lib: 'posthog-ai',
+      $ai_lib_version: version,
+      $ai_trace_id: traceId,
+      $ai_input_state: withPrivacyMode(this.client, this.privacyMode, sanitizeLangChain(run.input, this.client)),
+      $ai_latency: latency,
+      $ai_span_name: run.name,
+      $ai_span_id: runId,
+      $ai_framework: 'langchain'
+    };
+    if (parentRunId) {
+      eventProperties['$ai_parent_id'] = parentRunId;
+    }
+    Object.assign(eventProperties, this.properties);
+    if (!this.distinctId) {
+      eventProperties['$process_person_profile'] = false;
+    }
+    if (outputs instanceof Error) {
+      if (isLangGraphControlFlow(outputs)) {
+        // GraphInterrupt carries the pending interrupts (e.g. the question posed to a human).
+        // Surface them under the same `__interrupt__` key LangGraph hands back to the caller,
+        // so an interrupted span stays distinguishable from a node that returned nothing.
+        const interrupts = outputs.interrupts;
+        if (interrupts !== undefined) {
+          eventProperties['$ai_output_state'] = withPrivacyMode(this.client, this.privacyMode, sanitizeLangChain({
+            __interrupt__: interrupts
+          }, this.client));
+        }
+      } else {
+        eventProperties['$ai_error'] = stringifyError(outputs);
+        eventProperties['$ai_is_error'] = true;
+      }
+    } else if (outputs !== undefined) {
+      eventProperties['$ai_output_state'] = withPrivacyMode(this.client, this.privacyMode, sanitizeLangChain(outputs, this.client));
+    }
+    this._safeCapture({
+      distinctId: this.distinctId ? this.distinctId.toString() : runId,
+      event: eventName,
+      properties: eventProperties,
+      groups: this.groups
+    });
+  }
+  _popRunAndCaptureGeneration(runId, parentRunId, response) {
+    const traceId = this._getTraceId(runId);
+    this._popParentOfRun(runId);
+    const run = this._popRunMetadata(runId);
+    if (!run || typeof run !== 'object' || !('modelParams' in run)) {
+      console.warn(`Run ${runId} is not a generation, but attempted to be captured as such.`);
+      return;
+    }
+    const actualParentRunId = this._getParentRunId(traceId, runId, parentRunId);
+    this._captureGeneration(traceId, runId, run, response, actualParentRunId);
+  }
+  _captureGeneration(traceId, runId, run, output, parentRunId) {
+    const latency = run.endTime ? (run.endTime - run.startTime) / 1000 : 0;
+    warnIfPostHogAiGateway(run.baseUrl);
+    const eventProperties = {
+      $ai_lib: 'posthog-ai',
+      $ai_lib_version: version,
+      $ai_trace_id: traceId,
+      $ai_span_id: runId,
+      $ai_span_name: run.name,
+      $ai_provider: run.provider,
+      $ai_model: run.model,
+      $ai_model_parameters: run.modelParams,
+      $ai_input: withPrivacyMode(this.client, this.privacyMode, run.input),
+      $ai_http_status: 200,
+      $ai_latency: latency,
+      $ai_base_url: run.baseUrl,
+      $ai_framework: 'langchain'
+    };
+    if (parentRunId) {
+      eventProperties['$ai_parent_id'] = parentRunId;
+    }
+    if (run.tools) {
+      eventProperties['$ai_tools'] = run.tools;
+    }
+    if (output instanceof Error) {
+      eventProperties['$ai_http_status'] = output.status || 500;
+      eventProperties['$ai_error'] = stringifyError(output);
+      eventProperties['$ai_is_error'] = true;
+    } else {
+      // Handle token usage
+      const [inputTokens, outputTokens, additionalTokenData] = this.parseUsage(output, run.provider, run.model);
+      eventProperties['$ai_input_tokens'] = inputTokens;
+      eventProperties['$ai_output_tokens'] = outputTokens;
+
+      // Add additional token data to properties
+      if (additionalTokenData.cacheReadInputTokens) {
+        eventProperties['$ai_cache_read_input_tokens'] = additionalTokenData.cacheReadInputTokens;
+      }
+      if (additionalTokenData.cacheWriteInputTokens) {
+        eventProperties['$ai_cache_creation_input_tokens'] = additionalTokenData.cacheWriteInputTokens;
+      }
+      if (additionalTokenData.cacheWrite5mInputTokens !== undefined && additionalTokenData.cacheWrite1hInputTokens !== undefined) {
+        eventProperties['$ai_cache_creation_5m_input_tokens'] = additionalTokenData.cacheWrite5mInputTokens;
+        eventProperties['$ai_cache_creation_1h_input_tokens'] = additionalTokenData.cacheWrite1hInputTokens;
+      }
+      if (additionalTokenData.reasoningTokens) {
+        eventProperties['$ai_reasoning_tokens'] = additionalTokenData.reasoningTokens;
+      }
+      if (additionalTokenData.webSearchCount !== undefined) {
+        eventProperties['$ai_web_search_count'] = additionalTokenData.webSearchCount;
+      }
+
+      // Extract stop reason from generation info
+      const stopReason = this._extractStopReason(output);
+      if (stopReason) {
+        eventProperties['$ai_stop_reason'] = stopReason;
+      }
+
+      // Handle generations/completions
+      let completions;
+      if (output.generations && Array.isArray(output.generations)) {
+        const lastGeneration = output.generations[output.generations.length - 1];
+        if (Array.isArray(lastGeneration) && lastGeneration.length > 0) {
+          // Check if this is a ChatGeneration by looking at the first item
+          const isChatGeneration = 'message' in lastGeneration[0] && lastGeneration[0].message;
+          if (isChatGeneration) {
+            // For ChatGeneration, convert messages to dict format
+            completions = lastGeneration.map(gen => {
+              return this._convertMessageToDict(gen.message);
+            });
+          } else {
+            // For non-ChatGeneration, extract raw response
+            completions = lastGeneration.map(gen => {
+              return this._extractRawResponse(gen);
+            });
+          }
+        }
+      }
+      if (completions) {
+        eventProperties['$ai_output_choices'] = withPrivacyMode(this.client, this.privacyMode, completions);
+      }
+    }
+    Object.assign(eventProperties, this.properties);
+    if (!this.distinctId) {
+      eventProperties['$process_person_profile'] = false;
+    }
+    this._safeCapture({
+      distinctId: this.distinctId ? this.distinctId.toString() : traceId,
+      event: '$ai_generation',
+      properties: eventProperties,
+      groups: this.groups
+    });
+  }
+  _logDebugEvent(eventName, runId, parentRunId, extra) {
+    if (this.debug) {
+      console.log(`Event: ${eventName}, runId: ${runId}, parentRunId: ${parentRunId}, extra:`, extra);
+    }
+  }
+  _getLangchainRunName(serialized, ...args) {
+    if (args && args.length > 0) {
+      for (const arg of args) {
+        // LangChain hands runName through as a bare string, not wrapped in an object
+        if (typeof arg === 'string' && arg) {
+          return arg;
+        }
+        if (arg && typeof arg === 'object') {
+          if (arg.name) {
+            return arg.name;
+          }
+          if (arg.runName) {
+            return arg.runName;
+          }
+        }
+      }
+    }
+    if (serialized && serialized.name) {
+      return serialized.name;
+    }
+    if (serialized && serialized.id) {
+      return Array.isArray(serialized.id) ? serialized.id[serialized.id.length - 1] : serialized.id;
+    }
+    return undefined;
+  }
+  _convertLcToolCallsToOai(toolCalls) {
+    return toolCalls.map(toolCall => ({
+      type: 'function',
+      id: toolCall.id,
+      function: {
+        name: toolCall.name,
+        arguments: JSON.stringify(toolCall.args)
+      }
+    }));
+  }
+  _extractRawResponse(generation) {
+    // Extract the response from the last response of the LLM call
+    // We return the text of the response if not empty
+    if (generation.text != null && generation.text.trim() !== '') {
+      return generation.text.trim();
+    } else if (generation.message) {
+      // Additional kwargs contains the response in case of tool usage
+      return generation.message.additional_kwargs || generation.message.additionalKwargs || {};
+    } else {
+      // Not tool usage, some LLM responses can be simply empty
+      return '';
+    }
+  }
+  _convertMessageToDict(message) {
+    let messageDict = {};
+    const messageType = message.getType();
+    switch (messageType) {
+      case 'human':
+        messageDict = {
+          role: 'user',
+          content: message.content
+        };
+        break;
+      case 'ai':
+        messageDict = {
+          role: 'assistant',
+          content: message.content
+        };
+        if (message.tool_calls) {
+          messageDict.tool_calls = this._convertLcToolCallsToOai(message.tool_calls);
+        }
+        break;
+      case 'system':
+        messageDict = {
+          role: 'system',
+          content: message.content
+        };
+        break;
+      case 'tool':
+        messageDict = {
+          role: 'tool',
+          content: message.content
+        };
+        break;
+      case 'function':
+        messageDict = {
+          role: 'function',
+          content: message.content
+        };
+        break;
+      default:
+        messageDict = {
+          role: messageType,
+          content: toContentString(message.content)
+        };
+        break;
+    }
+    if (message.additional_kwargs) {
+      messageDict = {
+        ...messageDict,
+        ...message.additional_kwargs
+      };
+    }
+
+    // Sanitize the message content to redact base64 images
+    return sanitizeLangChain(messageDict, this.client);
+  }
+  _extractStopReason(output) {
+    if (!output.generations || !Array.isArray(output.generations)) {
+      return undefined;
+    }
+    const lastGeneration = output.generations[output.generations.length - 1];
+    if (!Array.isArray(lastGeneration) || lastGeneration.length === 0) {
+      return undefined;
+    }
+    const gen = lastGeneration[0];
+    const messageResponseMetadata = gen.message?.response_metadata;
+    const generationResponseMetadata = gen.generationInfo?.response_metadata;
+    const stopReason = messageResponseMetadata?.finish_reason || messageResponseMetadata?.stop_reason || gen.generationInfo?.finish_reason || generationResponseMetadata?.stop_reason || generationResponseMetadata?.finish_reason || gen.generationInfo?.stop_reason;
+    return stopReason != null ? String(stopReason) : undefined;
+  }
+  _extractCacheCreationTtlBreakdown(cacheCreation, aggregateValues) {
+    if (!isObject(cacheCreation)) {
+      return undefined;
+    }
+    const {
+      ephemeral_5m_input_tokens: cache5m,
+      ephemeral_1h_input_tokens: cache1h
+    } = cacheCreation;
+    const providedValues = [cache5m, cache1h].filter(value => value != null);
+    if (providedValues.length === 0 || !providedValues.every(value => typeof value === 'number' && Number.isFinite(value) && value >= 0)) {
+      return undefined;
+    }
+    const breakdown = [typeof cache5m === 'number' ? cache5m : 0, typeof cache1h === 'number' ? cache1h : 0];
+    const total = breakdown[0] + breakdown[1];
+    const validAggregates = aggregateValues.filter(value => typeof value === 'number' && Number.isFinite(value) && value >= 0);
+    return total > 0 && !validAggregates.some(aggregate => aggregate !== total) ? breakdown : undefined;
+  }
+  _extractBedrockCacheCreationTtlBreakdown(cacheDetails, aggregateValues) {
+    if (!Array.isArray(cacheDetails)) {
+      return undefined;
+    }
+    let cache5m = 0;
+    let cache1h = 0;
+    for (const detail of cacheDetails) {
+      if (!isObject(detail)) {
+        continue;
+      }
+      const ttl = typeof detail.ttl === 'string' ? detail.ttl.toLowerCase() : undefined;
+      const inputTokens = detail.inputTokens;
+      if (ttl !== '5m' && ttl !== 't5m' && ttl !== '1h' && ttl !== 't1h' || typeof inputTokens !== 'number' || !Number.isFinite(inputTokens) || inputTokens < 0) {
+        continue;
+      }
+      if (ttl === '5m' || ttl === 't5m') {
+        cache5m += inputTokens;
+      } else {
+        cache1h += inputTokens;
+      }
+    }
+    const total = cache5m + cache1h;
+    const validAggregates = aggregateValues.filter(value => typeof value === 'number' && Number.isFinite(value) && value >= 0);
+    if (total === 0 || validAggregates.some(aggregate => aggregate !== total)) {
+      return undefined;
+    }
+    return [cache5m, cache1h];
+  }
+  _parseUsageModel(usage, provider, model, inputIncludesCacheTokens = true, rawUsage) {
+    const conversionList = [['promptTokens', 'input'], ['completionTokens', 'output'], ['input_tokens', 'input'], ['output_tokens', 'output'], ['prompt_token_count', 'input'], ['candidates_token_count', 'output'], ['inputTokenCount', 'input'], ['outputTokenCount', 'output'], ['input_token_count', 'input'], ['generated_token_count', 'output']];
+    const parsedUsage = conversionList.reduce((acc, [modelKey, typeKey]) => {
+      const value = usage[modelKey];
+      if (value != null) {
+        const finalCount = Array.isArray(value) ? value.reduce((sum, tokenCount) => sum + tokenCount, 0) : value;
+        acc[typeKey] = finalCount;
+      }
+      return acc;
+    }, {
+      input: 0,
+      output: 0
+    });
+
+    // Extract additional token details like cached tokens and reasoning tokens
+    const additionalTokenData = {};
+
+    // Check for cached tokens in various formats
+    if (usage.prompt_tokens_details?.cached_tokens != null) {
+      additionalTokenData.cacheReadInputTokens = usage.prompt_tokens_details.cached_tokens;
+    } else if (usage.input_token_details?.cache_read != null) {
+      additionalTokenData.cacheReadInputTokens = usage.input_token_details.cache_read;
+    } else if (usage.cachedPromptTokens != null) {
+      additionalTokenData.cacheReadInputTokens = usage.cachedPromptTokens;
+    } else if (usage.cache_read_input_tokens != null) {
+      additionalTokenData.cacheReadInputTokens = usage.cache_read_input_tokens;
+    }
+
+    // Check for cache write/creation tokens in various formats
+    if (usage.cache_creation_input_tokens != null) {
+      additionalTokenData.cacheWriteInputTokens = usage.cache_creation_input_tokens;
+    } else if (usage.input_token_details?.cache_creation != null) {
+      additionalTokenData.cacheWriteInputTokens = usage.input_token_details.cache_creation;
+    }
+    const directCacheCreationAggregates = [usage.cache_creation_input_tokens, usage.input_token_details?.cache_creation, usage.cacheWriteInputTokens, rawUsage?.cache_creation_input_tokens, rawUsage?.input_token_details?.cache_creation, rawUsage?.cacheWriteInputTokens, additionalTokenData.cacheWriteInputTokens];
+    const cacheCreationTtl = this._extractCacheCreationTtlBreakdown(usage.cache_creation, directCacheCreationAggregates) ?? this._extractCacheCreationTtlBreakdown(rawUsage?.cache_creation, directCacheCreationAggregates) ?? this._extractBedrockCacheCreationTtlBreakdown(usage.cacheDetails, [usage.cacheWriteInputTokens, additionalTokenData.cacheWriteInputTokens]) ?? this._extractBedrockCacheCreationTtlBreakdown(rawUsage?.cacheDetails, [rawUsage?.cacheWriteInputTokens, additionalTokenData.cacheWriteInputTokens]);
+    if (cacheCreationTtl) {
+      const [cacheWrite5mInputTokens, cacheWrite1hInputTokens] = cacheCreationTtl;
+      additionalTokenData.cacheWrite5mInputTokens = cacheWrite5mInputTokens;
+      additionalTokenData.cacheWrite1hInputTokens = cacheWrite1hInputTokens;
+      additionalTokenData.cacheWriteInputTokens = cacheWrite5mInputTokens + cacheWrite1hInputTokens;
+    }
+
+    // Check for reasoning tokens in various formats
+    if (usage.completion_tokens_details?.reasoning_tokens != null) {
+      additionalTokenData.reasoningTokens = usage.completion_tokens_details.reasoning_tokens;
+    } else if (usage.output_token_details?.reasoning != null) {
+      additionalTokenData.reasoningTokens = usage.output_token_details.reasoning;
+    } else if (usage.reasoningTokens != null) {
+      additionalTokenData.reasoningTokens = usage.reasoningTokens;
+    }
+
+    // Extract web search counts from various provider formats
+    let webSearchCount;
+
+    // Priority 1: Exact Count
+    // Check Anthropic format (server_tool_use.web_search_requests)
+    if (usage.server_tool_use?.web_search_requests !== undefined) {
+      webSearchCount = usage.server_tool_use.web_search_requests;
+    }
+    // Priority 2: Binary Detection (1 or 0)
+    // Check for citations array (Perplexity)
+    else if (usage.citations && Array.isArray(usage.citations) && usage.citations.length > 0) {
+      webSearchCount = 1;
+    }
+    // Check for search_results array (Perplexity via OpenRouter)
+    else if (usage.search_results && Array.isArray(usage.search_results) && usage.search_results.length > 0) {
+      webSearchCount = 1;
+    }
+    // Check for search_context_size (Perplexity via OpenRouter)
+    else if (usage.search_context_size) {
+      webSearchCount = 1;
+    }
+    // Check for annotations with url_citation type
+    else if (usage.annotations && Array.isArray(usage.annotations)) {
+      const hasUrlCitation = usage.annotations.some(ann => {
+        return ann && typeof ann === 'object' && 'type' in ann && ann.type === 'url_citation';
+      });
+      if (hasUrlCitation) {
+        webSearchCount = 1;
+      }
+    }
+    // Check Gemini format (grounding metadata - binary 0 or 1)
+    else if (usage.grounding_metadata?.grounding_support !== undefined || usage.grounding_metadata?.web_search_queries !== undefined) {
+      webSearchCount = 1;
+    }
+    if (webSearchCount !== undefined) {
+      additionalTokenData.webSearchCount = webSearchCount;
+    }
+
+    // For Anthropic providers, LangChain reports input_tokens as the sum of all input tokens.
+    // Our cost calculation expects them to be separate for Anthropic, so we subtract cache tokens.
+    // Both cache_read and cache_write tokens should be subtracted since Anthropic's raw API
+    // reports input_tokens as tokens NOT read from or used to create a cache.
+    // For other providers (OpenAI, etc.), input_tokens already excludes cache tokens as expected.
+    // Match logic consistent with plugin-server: exact match on provider OR substring match on model
+    let isAnthropic = false;
+    if (provider && provider.toLowerCase() === 'anthropic') {
+      isAnthropic = true;
+    } else if (model && model.toLowerCase().includes('anthropic')) {
+      isAnthropic = true;
+    }
+    if (isAnthropic && inputIncludesCacheTokens && parsedUsage.input) {
+      const cacheTokens = (additionalTokenData.cacheReadInputTokens || 0) + (additionalTokenData.cacheWriteInputTokens || 0);
+      if (cacheTokens > 0) {
+        parsedUsage.input = Math.max(parsedUsage.input - cacheTokens, 0);
+      }
+    }
+    return [parsedUsage.input, parsedUsage.output, additionalTokenData];
+  }
+  parseUsage(response, provider, model) {
+    const isNonEmptyUsage = usage => isObject(usage) && Object.keys(usage).length > 0;
+    const firstNonEmptyUsage = (...candidates) => candidates.find(isNonEmptyUsage);
+    let normalizedGenerationUsage;
+    let rawGenerationUsage;
+    let fallbackGenerationUsage;
+    for (const generation of response.generations ?? []) {
+      for (const genChunk of generation) {
+        const generationInfo = genChunk.generationInfo ?? {};
+        const message = 'message' in genChunk ? genChunk.message : undefined;
+        const messageUsage = message && typeof message === 'object' && 'usage_metadata' in message ? message.usage_metadata : undefined;
+        normalizedGenerationUsage = firstNonEmptyUsage(normalizedGenerationUsage, messageUsage, generationInfo.usage_metadata);
+        const messageResponseMetadata = message && typeof message === 'object' && 'response_metadata' in message && isObject(message.response_metadata) ? message.response_metadata : undefined;
+        const generationResponseMetadata = isObject(generationInfo.response_metadata) ? generationInfo.response_metadata : undefined;
+        const messageStreamMetadata = isObject(messageResponseMetadata?.metadata) ? messageResponseMetadata.metadata : undefined;
+        const generationStreamMetadata = isObject(generationResponseMetadata?.metadata) ? generationResponseMetadata.metadata : undefined;
+        rawGenerationUsage = firstNonEmptyUsage(rawGenerationUsage, messageResponseMetadata?.usage, messageStreamMetadata?.usage, generationResponseMetadata?.usage, generationStreamMetadata?.usage);
+        fallbackGenerationUsage = firstNonEmptyUsage(fallbackGenerationUsage, messageResponseMetadata?.['amazon-bedrock-invocationMetrics'], generationResponseMetadata?.['amazon-bedrock-invocationMetrics'], generationInfo.usage_metadata);
+      }
+    }
+    const isAnthropic = provider?.toLowerCase() === 'anthropic' || model?.toLowerCase().includes('anthropic') === true;
+    if (isAnthropic && isNonEmptyUsage(normalizedGenerationUsage)) {
+      return this._parseUsageModel(normalizedGenerationUsage, provider, model, true, rawGenerationUsage);
+    }
+    const llmUsageKeys = ['token_usage', 'usage', 'tokenUsage'];
+    if (response.llmOutput != null) {
+      for (const key of llmUsageKeys) {
+        const llmUsage = response.llmOutput[key];
+        if (!isNonEmptyUsage(llmUsage)) {
+          continue;
+        }
+        return this._parseUsageModel(llmUsage, provider, model, key !== 'usage', llmUsage);
+      }
+    }
+    if (isNonEmptyUsage(normalizedGenerationUsage)) {
+      return this._parseUsageModel(normalizedGenerationUsage, provider, model, true, rawGenerationUsage);
+    }
+    if (isNonEmptyUsage(rawGenerationUsage)) {
+      return this._parseUsageModel(rawGenerationUsage, provider, model, false, rawGenerationUsage);
+    }
+    if (isNonEmptyUsage(fallbackGenerationUsage)) {
+      return this._parseUsageModel(fallbackGenerationUsage, provider, model);
+    }
+    return [0, 0, {}];
+  }
+}
+
+const postHogStateSchema = z.object({
+  _posthogRunId: z.string().optional(),
+  _posthogStartTime: z.number().optional(),
+  _posthogInput: z.record(z.string(), z.unknown()).optional()
+});
+class LangChainMiddlewareCallbackHandler extends LangChainCallbackHandler {
+  _getParentRunId(_traceId, _runId, parentRunId) {
+    return parentRunId;
+  }
+}
+const withoutPostHogState = state => {
+  const {
+    _posthogRunId: _,
+    _posthogStartTime: __,
+    _posthogInput: ___,
+    ...rest
+  } = state;
+  return rest;
+};
+const getRunId = state => state._posthogRunId ?? v7();
+const stringify = value => {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return '';
+    }
+  }
+};
+const toError = error => error instanceof Error ? error : new Error(stringify(error));
+const safely = callback => {
+  try {
+    callback();
+  } catch {
+    // Telemetry must never affect the LangChain middleware lifecycle.
+  }
+};
+const serializeModel = model => {
+  if (model && typeof model === 'object' && 'toJSON' in model && typeof model.toJSON === 'function') {
+    try {
+      return model.toJSON();
+    } catch {
+      // Fall back to a minimal LangChain serialization below.
+    }
+  }
+  return {
+    lc: 1,
+    type: 'constructor',
+    id: ['langchain', 'chat_models', 'unknown'],
+    kwargs: {}
+  };
+};
+const toModelOptions = modelSettings => {
+  if (!isObject(modelSettings)) {
+    return {};
+  }
+  try {
+    return {
+      ...modelSettings
+    };
+  } catch {
+    return {};
+  }
+};
+const getModelMetadata = (model, modelSettings) => {
+  if (model && typeof model === 'object' && 'getLsParams' in model && typeof model.getLsParams === 'function') {
+    try {
+      return model.getLsParams(toModelOptions(modelSettings));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+};
+const getModelInvocationParams = (model, modelSettings) => {
+  const options = toModelOptions(modelSettings);
+  if (model && typeof model === 'object' && 'invocationParams' in model && typeof model.invocationParams === 'function') {
+    try {
+      const params = model.invocationParams(options);
+      if (isObject(params)) {
+        return {
+          ...options,
+          ...params
+        };
+      }
+    } catch {
+      // Preserve the bind-time settings when the model cannot expose invocation parameters.
+    }
+  }
+  return options;
+};
+const normalizeTools = tools => {
+  return tools.map(tool => {
+    try {
+      return convertToOpenAITool(tool);
+    } catch {
+      return tool;
+    }
+  });
+};
+const toLLMResult = response => {
+  if (!AIMessage.isInstance(response)) {
+    return {
+      generations: []
+    };
+  }
+  const generation = {
+    text: toContentString(response.content),
+    message: response
+  };
+  return {
+    generations: [[generation]]
+  };
+};
+
+/** Options shared with the LangChain callback integration. */
+
+/**
+ * Creates PostHog AI observability middleware for LangChain v1 agents.
+ *
+ * Use either this middleware or `LangChainCallbackHandler`, not both, to avoid
+ * capturing the same model and tool calls twice.
+ *
+ * LangChain only invokes `afterAgent` for completed runs. A terminal agent
+ * failure still captures the failed model or tool call, but not a root trace.
+ */
+const createPostHogMiddleware = options => {
+  const {
+    stateSchema,
+    ...callbackOptions
+  } = options;
+  const callback = new LangChainMiddlewareCallbackHandler(callbackOptions);
+  const middlewareStateSchema = stateSchema ? extendInteropZodObject(stateSchema, postHogStateSchema.shape) : postHogStateSchema;
+  return createMiddleware({
+    name: 'PostHogMiddleware',
+    stateSchema: middlewareStateSchema,
+    beforeAgent: state => {
+      return {
+        _posthogRunId: v7(),
+        _posthogStartTime: Date.now(),
+        _posthogInput: withoutPostHogState(state)
+      };
+    },
+    afterAgent: state => {
+      safely(() => {
+        const runId = getRunId(state);
+        callback.handleChainStart({
+          lc: 1,
+          type: 'constructor',
+          id: ['langchain', 'agents', 'PostHogMiddleware'],
+          kwargs: {}
+        }, state._posthogInput ?? withoutPostHogState(state), runId, undefined, undefined, undefined, undefined, 'LangChain Agent', {
+          posthogStartTime: state._posthogStartTime
+        });
+        callback.handleChainEnd(withoutPostHogState(state), runId);
+      });
+    },
+    wrapModelCall: async (request, handler) => {
+      const runId = v7();
+      const parentRunId = getRunId(request.state);
+      const messages = request.systemMessage.text === '' ? request.messages : [request.systemMessage, ...request.messages];
+      const invocationParams = {
+        ...getModelInvocationParams(request.model, request.modelSettings),
+        tools: normalizeTools(request.tools)
+      };
+      safely(() => callback.handleChatModelStart(serializeModel(request.model), [messages], runId, parentRunId, {
+        invocation_params: invocationParams
+      }, undefined, getModelMetadata(request.model, request.modelSettings)));
+      try {
+        const response = await handler(request);
+        safely(() => callback.handleLLMEnd(toLLMResult(response), runId, parentRunId));
+        return response;
+      } catch (error) {
+        safely(() => callback.handleLLMError(toError(error), runId));
+        throw error;
+      }
+    },
+    wrapToolCall: async (request, handler) => {
+      const runId = v7();
+      const parentRunId = getRunId(request.state);
+      const toolName = String(request.tool?.name ?? request.toolCall.name);
+      const serializedTool = {
+        lc: 1,
+        type: 'constructor',
+        id: ['langchain', 'tools', toolName],
+        kwargs: {}
+      };
+      safely(() => callback.handleToolStart(serializedTool, stringify(request.toolCall.args), runId, parentRunId, undefined, undefined, toolName));
+      try {
+        const result = await handler(request);
+        if (ToolMessage.isInstance(result) && result.status === 'error') {
+          safely(() => callback.handleToolError(new Error(toContentString(result.content)), runId, parentRunId));
+        } else {
+          safely(() => callback.handleToolEnd(result, runId, parentRunId));
+        }
+        return result;
+      } catch (error) {
+        safely(() => callback.handleToolError(toError(error), runId));
+        throw error;
+      }
+    }
+  });
+};
+
+export { createPostHogMiddleware };
+//# sourceMappingURL=index.mjs.map