@posthog/ai 8.9.2 → 8.10.0

package/dist/adk/index.mjs

@@ -0,0 +1,1265 @@
+import { BasePlugin } from '@google/adk';
+import { v4 } from 'uuid';
+import { toJsonSafeValue, uuidv7 } from '@posthog/core';
+
+var version = "8.10.0";
+
+/** @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);
+}
+
+/** @internal */
+async function captureAiEventImmediate(client, event) {
+  if (isFullAiCaptureEnabled(client) && typeof client.captureAiImmediate === 'function') {
+    await client.captureAiImmediate(event);
+    return;
+  }
+  await client.captureImmediate(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();
+function redactBase64DataUrl(str, mediaType) {
+  return redactor.redact(str, mediaType);
+}
+const sanitize = (data, client) => isFullAiCaptureEnabled(client) ? data : redactor.redact(data);
+const sanitizeGemini = (data, client) => sanitize(data, client);
+
+const TOKEN_PROPERTY_KEYS = new Set(['$ai_input_tokens', '$ai_output_tokens', '$ai_cache_read_input_tokens', '$ai_cache_creation_input_tokens', '$ai_total_tokens', '$ai_reasoning_tokens']);
+
+/**
+ * Whether the caller supplied their own token counts, which override the ones the SDK
+ * derived from the provider response.
+ */
+function hasTokenOverrides(posthogProperties) {
+  return !!posthogProperties && Object.keys(posthogProperties).some(key => TOKEN_PROPERTY_KEYS.has(key));
+}
+function getTokensSource(posthogProperties) {
+  return hasTokenOverrides(posthogProperties) ? 'passthrough' : 'sdk';
+}
+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 buildInlineDataBlock = (mimeType, data) => {
+  if (mimeType.startsWith('audio/')) {
+    return {
+      type: 'audio',
+      mime_type: mimeType,
+      data
+    };
+  }
+  if (mimeType.startsWith('image/')) {
+    return {
+      type: 'image',
+      inline_data: {
+        mime_type: mimeType,
+        data
+      }
+    };
+  }
+  return {
+    type: 'document',
+    inline_data: {
+      mime_type: mimeType,
+      data
+    }
+  };
+};
+const formatInlineDataBlock = (inlineData, client) => {
+  const mimeType = inlineData.mimeType || inlineData.mime_type || 'application/octet-stream';
+  let data = inlineData.data;
+  if (data instanceof Uint8Array) {
+    if (typeof Buffer !== 'undefined') {
+      data = Buffer.from(data).toString('base64');
+    } else {
+      let binary = '';
+      for (let i = 0; i < data.length; i++) {
+        binary += String.fromCharCode(data[i]);
+      }
+      data = btoa(binary);
+    }
+  }
+  data = isFullAiCaptureEnabled(client) ? data : redactBase64DataUrl(data, mimeType);
+  return buildInlineDataBlock(mimeType, String(data ?? ''));
+};
+const formatResponseGemini = (response, client) => {
+  const output = [];
+  if (response.candidates && Array.isArray(response.candidates)) {
+    for (const candidate of response.candidates) {
+      if (candidate.content && candidate.content.parts) {
+        const content = [];
+        for (const part of candidate.content.parts) {
+          if (part.text) {
+            content.push({
+              type: 'text',
+              text: part.text
+            });
+          } else if (part.functionCall) {
+            content.push({
+              type: 'function',
+              function: {
+                name: part.functionCall.name,
+                arguments: part.functionCall.args
+              }
+            });
+          } else if (part.inlineData) {
+            content.push(formatInlineDataBlock(part.inlineData, client));
+          }
+        }
+        if (content.length > 0) {
+          output.push({
+            role: 'assistant',
+            content
+          });
+        }
+      } else if (candidate.text) {
+        output.push({
+          role: 'assistant',
+          content: [{
+            type: 'text',
+            text: candidate.text
+          }]
+        });
+      }
+    }
+  } else if (response.text) {
+    output.push({
+      role: 'assistant',
+      content: [{
+        type: 'text',
+        text: response.text
+      }]
+    });
+  }
+  return output;
+};
+const withPrivacyMode = (client, privacyMode, input) => {
+  return client.privacy_mode || privacyMode ? null : input;
+};
+let AIEvent = /*#__PURE__*/function (AIEvent) {
+  AIEvent["Generation"] = "$ai_generation";
+  AIEvent["Embedding"] = "$ai_embedding";
+  return AIEvent;
+}({});
+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;
+}
+
+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}.`);
+};
+
+/**
+ * Options for `captureAiGeneration`. Mirrors the `$ai_generation` event shape
+ * directly so that any caller — first-party SDK wrappers and external code
+ * alike — produces an identical event.
+ */
+
+/**
+ * Capture an `$ai_generation` (or `$ai_embedding`) event to PostHog.
+ *
+ * This is the canonical primitive that every `@posthog/ai` wrapper
+ * (`withTracing`, `OpenAI`, `Anthropic`, `GoogleGenAI`, …) funnels through, so
+ * external code can use it directly to instrument LLM calls made through
+ * arbitrary clients (Cloudflare Workers AI, custom HTTP, etc.) and get the
+ * same events the SDK wrappers produce.
+ *
+ * When `error` is set, the event is captured as an error. If the error is an
+ * object, it is mutated in place to set `__posthog_previously_captured_error`
+ * so callers can re-throw the original error reference safely.
+ */
+const captureAiGeneration = async (client, options) => {
+  try {
+    if (!client.capture) {
+      return;
+    }
+    warnIfPostHogAiGateway(options.baseURL);
+    const traceId = options.traceId ?? v4();
+    const eventType = options.eventType ?? AIEvent.Generation;
+    const privacyMode = options.privacyMode ?? false;
+    const usage = options.usage ?? {};
+
+    // Check privacy before reading or traversing input/output. Besides avoiding
+    // needless work, this ensures hostile getters/proxies cannot observe a value
+    // that the caller explicitly requested us to redact.
+    const shouldRedact = withPrivacyMode(client, privacyMode, false) === null;
+    const safeInput = shouldRedact ? null : toJsonSafeValue(options.input);
+    const safeOutput = shouldRedact ? null : toJsonSafeValue(options.output);
+    let httpStatus = options.httpStatus;
+    let errorData = {};
+    if (options.error) {
+      if (httpStatus === undefined) {
+        if (typeof options.error === 'object' && 'status' in options.error && typeof options.error.status === 'number') {
+          httpStatus = options.error.status;
+        } else if (typeof options.error === 'object' && 'statusCode' in options.error && typeof options.error.statusCode === 'number') {
+          httpStatus = options.error.statusCode;
+        } else {
+          httpStatus = 500;
+        }
+      }
+      let exceptionId;
+      if (client.options?.enableExceptionAutocapture) {
+        exceptionId = uuidv7();
+        client.captureException(options.error, undefined, {
+          $ai_trace_id: traceId
+        }, exceptionId);
+        if (typeof options.error === 'object') {
+          ;
+          options.error.__posthog_previously_captured_error = true;
+        }
+      }
+      errorData = {
+        $ai_is_error: true,
+        $ai_error: stringifyError(options.error),
+        $exception_event_id: exceptionId
+      };
+    }
+    httpStatus = httpStatus ?? 200;
+
+    // A configured price applies only to a count the provider reported, so a call with no
+    // reported usage sends no cost instead of asserting $0. $ai_total_cost_usd sums the sides
+    // that were priced, which makes it the cost of the known side alone when the other side
+    // went unreported: a lower bound on the true total, not an assertion of it.
+    const costOverrideData = {};
+    if (options.costOverride) {
+      if (usage.inputTokens !== undefined) {
+        costOverrideData.$ai_input_cost_usd = (options.costOverride.inputCost ?? 0) * usage.inputTokens;
+      }
+      if (usage.outputTokens !== undefined) {
+        costOverrideData.$ai_output_cost_usd = (options.costOverride.outputCost ?? 0) * usage.outputTokens;
+      }
+      if (Object.keys(costOverrideData).length > 0) {
+        costOverrideData.$ai_total_cost_usd = (costOverrideData.$ai_input_cost_usd ?? 0) + (costOverrideData.$ai_output_cost_usd ?? 0);
+      }
+    }
+
+    // The caller's own token counts override the SDK-derived ones further down, via the
+    // `options.properties` spread.
+    const tokensOverridden = hasTokenOverrides(options.properties);
+    const additionalTokenValues = {
+      ...(usage.reasoningTokens ? {
+        $ai_reasoning_tokens: usage.reasoningTokens
+      } : {}),
+      ...(usage.cacheReadInputTokens ? {
+        $ai_cache_read_input_tokens: usage.cacheReadInputTokens
+      } : {}),
+      ...(usage.cacheCreationInputTokens ? {
+        $ai_cache_creation_input_tokens: usage.cacheCreationInputTokens
+      } : {}),
+      // Checked against undefined rather than truthiness, because false is the meaningful
+      // value here and a truthiness guard would drop it.
+      //
+      // Dropped entirely when the caller overrides the token counts: the flag describes how
+      // the SDK-derived counts relate to each other, so against passthrough counts it can be
+      // wrong in the expensive direction. Declaring inclusive over counts that are actually
+      // exclusive makes ingestion subtract the cache pool that was never in the input. A
+      // caller who knows their own accounting model can still pass
+      // `$ai_cache_reporting_exclusive` themselves, and that value wins.
+      ...(usage.cacheReportingExclusive !== undefined && !tokensOverridden ? {
+        $ai_cache_reporting_exclusive: usage.cacheReportingExclusive
+      } : {}),
+      ...(usage.webSearchCount ? {
+        $ai_web_search_count: usage.webSearchCount
+      } : {}),
+      ...(usage.rawUsage ? {
+        $ai_usage: usage.rawUsage
+      } : {})
+    };
+    const properties = {
+      $ai_lib: 'posthog-ai',
+      $ai_lib_version: version,
+      $ai_provider: options.providerOverride ?? options.provider,
+      $ai_model: options.modelOverride ?? options.model,
+      $ai_model_parameters: options.modelParameters ?? {},
+      $ai_input: safeInput,
+      $ai_output_choices: safeOutput,
+      $ai_http_status: httpStatus,
+      ...(usage.inputTokens !== undefined ? {
+        $ai_input_tokens: usage.inputTokens
+      } : {}),
+      ...(usage.outputTokens !== undefined ? {
+        $ai_output_tokens: usage.outputTokens
+      } : {}),
+      ...additionalTokenValues,
+      ...(options.latency !== undefined ? {
+        $ai_latency: options.latency
+      } : {}),
+      ...(options.timeToFirstToken !== undefined ? {
+        $ai_time_to_first_token: options.timeToFirstToken
+      } : {}),
+      $ai_trace_id: traceId,
+      ...(options.baseURL === null ? {} : {
+        $ai_base_url: options.baseURL ?? ''
+      }),
+      ...options.properties,
+      $ai_tokens_source: getTokensSource(options.properties),
+      ...(options.distinctId ? {} : {
+        $process_person_profile: false
+      }),
+      ...(options.stopReason ? {
+        $ai_stop_reason: options.stopReason
+      } : {}),
+      ...(options.tools ? {
+        $ai_tools: options.tools
+      } : {}),
+      ...(options.completionId ? {
+        $ai_completion_id: options.completionId
+      } : {}),
+      ...(options.providerMetadata && Object.keys(options.providerMetadata).length > 0 ? {
+        $ai_provider_metadata: options.providerMetadata
+      } : {}),
+      ...errorData,
+      ...costOverrideData
+    };
+    const event = {
+      distinctId: options.distinctId ?? traceId,
+      event: eventType,
+      properties,
+      groups: options.groups
+    };
+    if (options.captureImmediate) {
+      await captureAiEventImmediate(client, event);
+    } else {
+      captureAiEvent(client, event);
+    }
+  } catch (error) {
+    // Telemetry failures must never affect the instrumented provider call.
+    try {
+      options.onError?.(error);
+    } catch {
+      // Error reporting must not affect the instrumented provider call either.
+    }
+    console.warn('[PostHog AI] Failed to capture generation telemetry:', error);
+  }
+};
+
+/** Map Gemini usage metadata to PostHog's provider-agnostic token fields. */
+function mapGeminiUsage(metadata, additionalUsage = {}) {
+  return {
+    inputTokens: metadata?.promptTokenCount ?? 0,
+    outputTokens: metadata?.candidatesTokenCount ?? 0,
+    reasoningTokens: metadata?.thoughtsTokenCount ?? 0,
+    cacheReadInputTokens: metadata?.cachedContentTokenCount ?? 0,
+    // Gemini counts cachedContentTokenCount inside promptTokenCount, so declare
+    // the accounting model rather than leaving ingestion to infer it. Under
+    // explicit context caching the two measurements can differ by a few percent.
+    ...(metadata?.cachedContentTokenCount ? {
+      cacheReportingExclusive: false
+    } : {}),
+    ...additionalUsage,
+    rawUsage: metadata
+  };
+}
+
+/**
+ * Resolver for the PostHog distinct ID. Either a static string, or a function
+ * that derives it from the ADK model callback context (e.g. from
+ * `context.userId`). Return `null`/`undefined` to fall back to the ADK
+ * `userId`, and finally to anonymous (personless) capture keyed by trace ID.
+ */
+
+/** Calls older than this are treated as abandoned rather than evicting live calls by count. */
+const MAX_PENDING_AGE_MS = 60 * 60 * 1000;
+
+/**
+ * A Google ADK (`@google/adk`) `BasePlugin` that captures PostHog AI traces,
+ * agent and tool spans, and a full `$ai_generation` event for every model call.
+ *
+ * Run, agent, and tool callbacks build the trace hierarchy. Model callbacks
+ * record input, output, model, token usage, latency, and finish reason through
+ * the shared {@link captureAiGeneration} primitive so PostHog derives cost from
+ * the model and tokens (never hardcoded here).
+ *
+ * ADK already emits OpenTelemetry `gen_ai.*` spans; this plugin is the
+ * complement for users who capture LLM analytics through the PostHog SDK rather
+ * than an OTEL exporter.
+ *
+ * @example
+ * ```typescript
+ * import { PostHogADKPlugin } from '@posthog/ai/adk'
+ * import { Runner } from '@google/adk'
+ * import { PostHog } from 'posthog-node'
+ *
+ * const phClient = new PostHog('<POSTHOG_API_KEY>')
+ *
+ * const runner = new Runner({
+ *   appName: 'my-app',
+ *   agent,
+ *   sessionService,
+ *   plugins: [new PostHogADKPlugin({ client: phClient, distinctId: 'user@example.com' })],
+ * })
+ * ```
+ */
+class PostHogADKPlugin extends BasePlugin {
+  /** FIFO of in-flight model calls for each invocation branch and agent. */
+  _pending = new Map();
+  _traces = new Map();
+  _pendingAgents = new Map();
+  _pendingTools = new Map();
+  constructor(options) {
+    super('posthog');
+    this._client = options.client;
+    this._distinctId = options.distinctId;
+    this._provider = options.provider ?? 'gemini';
+    this._privacyMode = options.privacyMode ?? false;
+    this._groups = options.groups;
+    this._properties = options.properties ?? {};
+    this._captureImmediate = options.captureImmediate ?? false;
+    this._onError = options.onError;
+  }
+  async beforeRunCallback({
+    invocationContext
+  }) {
+    try {
+      this._evictStalePending();
+      this._traces.set(invocationContext.invocationId, {
+        startTime: Date.now(),
+        spanId: invocationContext.invocationId,
+        name: invocationContext.agent?.name ?? 'ADK invocation',
+        input: invocationContext.userContent,
+        distinctId: this._resolveInvocationDistinctId(invocationContext),
+        sessionId: invocationContext.session?.id
+      });
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async afterRunCallback({
+    invocationContext
+  }) {
+    try {
+      const trace = this._traces.get(invocationContext.invocationId);
+      this._traces.delete(invocationContext.invocationId);
+      this._clearPendingInvocation(invocationContext.invocationId);
+      if (!trace) {
+        return;
+      }
+      await this._captureLifecycleEvent('$ai_trace', trace.distinctId, {
+        $ai_trace_id: invocationContext.invocationId,
+        $ai_span_id: trace.spanId,
+        $ai_span_name: trace.name,
+        $ai_input_state: withPrivacyMode(this._client, this._privacyMode, trace.input),
+        $ai_latency: (Date.now() - trace.startTime) / 1000,
+        ...(trace.sessionId ? {
+          $ai_session_id: trace.sessionId
+        } : {})
+      });
+    } catch (error) {
+      this._handleError(error);
+    }
+  }
+  async beforeAgentCallback({
+    agent,
+    callbackContext
+  }) {
+    try {
+      this._evictStalePending();
+      this._rememberContext(callbackContext);
+      const key = this._pendingKey(callbackContext);
+      const pending = {
+        startTime: Date.now(),
+        spanId: v4(),
+        name: agent.name,
+        input: callbackContext.userContent
+      };
+      const queue = this._pendingAgents.get(key);
+      if (queue) {
+        queue.push(pending);
+      } else {
+        this._pendingAgents.set(key, [pending]);
+      }
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async afterAgentCallback({
+    callbackContext
+  }) {
+    try {
+      const pending = this._takePendingAgent(this._pendingKey(callbackContext));
+      if (pending) {
+        await this._captureLifecycleEvent('$ai_span', this._resolveDistinctId(callbackContext), {
+          $ai_trace_id: callbackContext.invocationId,
+          $ai_span_id: pending.spanId,
+          ...(this._traces.get(callbackContext.invocationId)?.spanId ? {
+            $ai_parent_id: this._traces.get(callbackContext.invocationId)?.spanId
+          } : {}),
+          $ai_span_name: pending.name,
+          $ai_input_state: withPrivacyMode(this._client, this._privacyMode, pending.input),
+          $ai_latency: (Date.now() - pending.startTime) / 1000,
+          ...(callbackContext.sessionId ? {
+            $ai_session_id: callbackContext.sessionId
+          } : {}),
+          ...(callbackContext.agentName ? {
+            $ai_agent_name: callbackContext.agentName
+          } : {})
+        });
+      }
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async beforeModelCallback({
+    callbackContext,
+    llmRequest
+  }) {
+    try {
+      this._evictStalePending();
+      this._rememberContext(callbackContext);
+      const pending = {
+        startTime: Date.now(),
+        spanId: v4(),
+        input: this._formatInput(llmRequest),
+        model: llmRequest.model,
+        modelParameters: extractModelParameters(llmRequest.config),
+        tools: extractTools(llmRequest),
+        streamedOutput: []
+      };
+      const key = this._pendingKey(callbackContext);
+      const queue = this._pending.get(key);
+      if (queue) {
+        queue.push(pending);
+      } else {
+        this._pending.set(key, [pending]);
+      }
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async afterModelCallback({
+    callbackContext,
+    llmResponse
+  }) {
+    try {
+      // Streaming delivers partial responses before the terminal one; the
+      // terminal response carries the full content and usage, so only emit then.
+      if (llmResponse.partial) {
+        return undefined;
+      }
+      const key = this._pendingKey(callbackContext);
+      const pending = this._peekPending(key);
+      if (this._isNonTerminalStreamResponse(llmResponse)) {
+        if (pending) {
+          pending.streamedOutput.push(...this._formatOutput(llmResponse));
+        }
+        return undefined;
+      }
+      const completedPending = this._takePending(key);
+      const error = llmResponse.errorCode ? new Error(llmResponse.errorMessage ?? String(llmResponse.errorCode)) : undefined;
+      const output = error ? [] : this._formatOutput(llmResponse);
+      await this._capture(callbackContext, {
+        pending: completedPending,
+        output: !error && output.length === 0 && completedPending?.streamedOutput.length ? completedPending.streamedOutput : output,
+        model: llmResponse.modelVersion ?? completedPending?.model,
+        usage: llmResponse.usageMetadata,
+        stopReason: llmResponse.finishReason ? String(llmResponse.finishReason) : undefined,
+        error
+      });
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async onModelErrorCallback({
+    callbackContext,
+    llmRequest,
+    error
+  }) {
+    try {
+      const pending = this._takePending(this._pendingKey(callbackContext));
+      await this._capture(callbackContext, {
+        pending: pending ?? {
+          startTime: Date.now(),
+          spanId: v4(),
+          input: this._formatInput(llmRequest),
+          model: llmRequest.model,
+          modelParameters: extractModelParameters(llmRequest.config),
+          tools: extractTools(llmRequest),
+          streamedOutput: []
+        },
+        output: [],
+        model: llmRequest.model,
+        usage: undefined,
+        error
+      });
+    } catch (captureError) {
+      this._handleError(captureError);
+    }
+    return undefined;
+  }
+  async beforeToolCallback({
+    tool,
+    toolArgs,
+    toolContext
+  }) {
+    try {
+      this._evictStalePending();
+      this._rememberContext(toolContext);
+      const key = this._toolKey(toolContext, tool.name);
+      const pending = {
+        startTime: Date.now(),
+        spanId: toolContext.functionCallId ?? v4(),
+        name: tool.name,
+        input: toolArgs
+      };
+      const queue = this._pendingTools.get(key);
+      if (queue) {
+        queue.push(pending);
+      } else {
+        this._pendingTools.set(key, [pending]);
+      }
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async afterToolCallback({
+    tool,
+    toolContext,
+    result
+  }) {
+    try {
+      const pending = this._takePendingTool(this._toolKey(toolContext, tool.name));
+      if (pending) {
+        await this._captureToolSpan(toolContext, pending, result);
+      }
+    } catch (error) {
+      this._handleError(error);
+    }
+    return undefined;
+  }
+  async onToolErrorCallback({
+    tool,
+    toolContext,
+    error
+  }) {
+    try {
+      const pending = this._takePendingTool(this._toolKey(toolContext, tool.name));
+      if (pending) {
+        await this._captureToolSpan(toolContext, pending, undefined, error);
+      }
+    } catch (captureError) {
+      this._handleError(captureError);
+    }
+    return undefined;
+  }
+  async _capture(callbackContext, args) {
+    const {
+      pending,
+      output,
+      model,
+      usage,
+      stopReason,
+      error
+    } = args;
+    const latency = pending ? (Date.now() - pending.startTime) / 1000 : undefined;
+    await captureAiGeneration(this._client, {
+      distinctId: this._resolveDistinctId(callbackContext),
+      traceId: callbackContext.invocationId,
+      model,
+      provider: this._provider,
+      baseURL: null,
+      input: pending?.input ?? [],
+      output,
+      latency,
+      modelParameters: pending?.modelParameters,
+      usage: mapGeminiUsage(usage),
+      stopReason,
+      tools: pending?.tools,
+      groups: this._groups,
+      privacyMode: this._privacyMode,
+      captureImmediate: this._captureImmediate,
+      onError: this._onError,
+      properties: {
+        $ai_framework: 'google-adk',
+        $ai_span_id: pending?.spanId ?? v4(),
+        ...(this._parentSpanId(callbackContext) ? {
+          $ai_parent_id: this._parentSpanId(callbackContext)
+        } : {}),
+        ...(callbackContext.sessionId ? {
+          $ai_session_id: callbackContext.sessionId
+        } : {}),
+        ...(callbackContext.agentName ? {
+          $ai_agent_name: callbackContext.agentName,
+          $ai_span_name: callbackContext.agentName
+        } : {}),
+        ...this._properties
+      },
+      error
+    });
+  }
+  async _captureToolSpan(context, pending, result, error) {
+    await this._captureLifecycleEvent('$ai_span', this._resolveDistinctId(context), {
+      $ai_trace_id: context.invocationId,
+      $ai_span_id: pending.spanId,
+      ...(this._parentSpanId(context) ? {
+        $ai_parent_id: this._parentSpanId(context)
+      } : {}),
+      $ai_span_name: pending.name,
+      $ai_input_state: withPrivacyMode(this._client, this._privacyMode, pending.input),
+      ...(result !== undefined ? {
+        $ai_output_state: withPrivacyMode(this._client, this._privacyMode, result)
+      } : {}),
+      $ai_latency: (Date.now() - pending.startTime) / 1000,
+      ...(context.sessionId ? {
+        $ai_session_id: context.sessionId
+      } : {}),
+      ...(context.agentName ? {
+        $ai_agent_name: context.agentName
+      } : {}),
+      ...(error ? {
+        $ai_is_error: true,
+        $ai_error: stringifyError(error)
+      } : {})
+    });
+  }
+  async _captureLifecycleEvent(event, distinctId, properties) {
+    const message = {
+      distinctId: distinctId ?? String(properties.$ai_trace_id),
+      event,
+      properties: {
+        $ai_lib: 'posthog-ai',
+        $ai_lib_version: version,
+        $ai_framework: 'google-adk',
+        ...properties,
+        ...this._properties,
+        ...(distinctId ? {} : {
+          $process_person_profile: false
+        })
+      },
+      groups: this._groups
+    };
+    if (this._captureImmediate) {
+      await captureAiEventImmediate(this._client, message);
+    } else {
+      captureAiEvent(this._client, message);
+    }
+  }
+  _resolveDistinctId(context) {
+    if (typeof this._distinctId === 'function') {
+      const resolved = this._distinctId(context);
+      if (resolved) {
+        return String(resolved);
+      }
+    } else if (this._distinctId) {
+      return String(this._distinctId);
+    }
+    return context.userId ? String(context.userId) : undefined;
+  }
+  _resolveInvocationDistinctId(context) {
+    if (typeof this._distinctId === 'string' && this._distinctId) {
+      return String(this._distinctId);
+    }
+    return context.userId ? String(context.userId) : undefined;
+  }
+  _rememberContext(context) {
+    const trace = this._traces.get(context.invocationId);
+    if (trace) {
+      trace.distinctId = this._resolveDistinctId(context);
+      trace.sessionId = context.sessionId || trace.sessionId;
+    }
+  }
+  _parentSpanId(context) {
+    return this._pendingAgents.get(this._pendingKey(context))?.[0]?.spanId ?? this._traces.get(context.invocationId)?.spanId;
+  }
+  _pendingKey(context) {
+    return [context.invocationId, context.invocationContext?.branch ?? '', context.agentName].join('\0');
+  }
+  _toolKey(context, toolName) {
+    return [this._pendingKey(context), context.functionCallId ?? '', toolName].join('\0');
+  }
+  _peekPending(key) {
+    return this._pending.get(key)?.[0];
+  }
+  _takePending(key) {
+    const queue = this._pending.get(key);
+    if (!queue || queue.length === 0) {
+      return undefined;
+    }
+    const pending = queue.shift();
+    if (queue.length === 0) {
+      this._pending.delete(key);
+    }
+    return pending;
+  }
+  _takePendingAgent(key) {
+    const queue = this._pendingAgents.get(key);
+    if (!queue || queue.length === 0) {
+      return undefined;
+    }
+    const pending = queue.shift();
+    if (queue.length === 0) {
+      this._pendingAgents.delete(key);
+    }
+    return pending;
+  }
+  _takePendingTool(key) {
+    const queue = this._pendingTools.get(key);
+    if (!queue || queue.length === 0) {
+      return undefined;
+    }
+    const pending = queue.shift();
+    if (queue.length === 0) {
+      this._pendingTools.delete(key);
+    }
+    return pending;
+  }
+  _isNonTerminalStreamResponse(llmResponse) {
+    if (llmResponse.turnComplete === false) {
+      return true;
+    }
+    return llmResponse.partial === false && llmResponse.turnComplete !== true && llmResponse.content !== undefined && llmResponse.finishReason === undefined && llmResponse.errorCode === undefined;
+  }
+  _evictStalePending() {
+    const cutoff = Date.now() - MAX_PENDING_AGE_MS;
+    this._evictStaleQueueEntries(this._pending, cutoff);
+    this._evictStaleQueueEntries(this._pendingAgents, cutoff);
+    this._evictStaleQueueEntries(this._pendingTools, cutoff);
+    for (const [invocationId, trace] of this._traces) {
+      if (trace.startTime < cutoff) {
+        this._traces.delete(invocationId);
+      }
+    }
+  }
+  _evictStaleQueueEntries(queues, cutoff) {
+    for (const [key, queue] of queues) {
+      const active = queue.filter(entry => entry.startTime >= cutoff);
+      if (active.length > 0) {
+        queues.set(key, active);
+      } else {
+        queues.delete(key);
+      }
+    }
+  }
+  _clearPendingInvocation(invocationId) {
+    const prefix = `${invocationId}\0`;
+    for (const key of this._pending.keys()) {
+      if (key.startsWith(prefix)) {
+        this._pending.delete(key);
+      }
+    }
+    for (const key of this._pendingAgents.keys()) {
+      if (key.startsWith(prefix)) {
+        this._pendingAgents.delete(key);
+      }
+    }
+    for (const key of this._pendingTools.keys()) {
+      if (key.startsWith(prefix)) {
+        this._pendingTools.delete(key);
+      }
+    }
+  }
+  _formatInput(llmRequest) {
+    const contents = sanitizeGemini(llmRequest.contents, this._client) ?? [];
+    const messages = Array.isArray(contents) ? contents.map(content => formatContent(content, this._client)) : [];
+    const systemInstruction = extractSystemInstruction(llmRequest);
+    if (systemInstruction && !messages.some(message => message.role === 'system')) {
+      return [{
+        role: 'system',
+        content: systemInstruction
+      }, ...messages];
+    }
+    return messages;
+  }
+  _formatOutput(llmResponse) {
+    // Reuse the Gemini response formatter (text/functionCall/inlineData +
+    // base64 redaction) by adapting the ADK response into a candidates shape.
+    return formatResponseGemini({
+      candidates: llmResponse.content ? [{
+        content: llmResponse.content
+      }] : []
+    }, this._client);
+  }
+  _handleError(error) {
+    try {
+      this._onError?.(error);
+    } catch {
+      // The plugin must never throw into the ADK model flow.
+    }
+  }
+}
+
+/** Map a genai content role to PostHog's convention (`model` -> `assistant`). */
+function mapRole(role) {
+  if (role === 'model') {
+    return 'assistant';
+  }
+  return role ?? 'user';
+}
+function formatContent(content, client) {
+  const parts = Array.isArray(content?.parts) ? content.parts : [];
+  const blocks = [];
+  for (const part of parts) {
+    if (part == null) {
+      continue;
+    }
+    if (part.text) {
+      blocks.push({
+        type: 'text',
+        text: String(part.text)
+      });
+    } else if (part.functionCall) {
+      blocks.push({
+        type: 'function',
+        id: part.functionCall.id,
+        function: {
+          name: part.functionCall.name,
+          arguments: part.functionCall.args ?? {}
+        }
+      });
+    } else if (part.functionResponse) {
+      blocks.push({
+        type: 'text',
+        text: toContentString(part.functionResponse.response ?? part.functionResponse)
+      });
+    } else if (part.inlineData) {
+      blocks.push(formatInlineDataBlock(part.inlineData, client));
+    }
+  }
+  return {
+    role: mapRole(content?.role),
+    content: blocks
+  };
+}
+
+/** Extract the system instruction text from an LlmRequest's config, if any. */
+function extractSystemInstruction(llmRequest) {
+  const systemInstruction = llmRequest.config?.systemInstruction;
+  if (!systemInstruction) {
+    return null;
+  }
+  if (typeof systemInstruction === 'string') {
+    return systemInstruction;
+  }
+  const asObject = systemInstruction;
+  if (typeof asObject.text === 'string') {
+    return asObject.text;
+  }
+  const parts = Array.isArray(asObject.parts) ? asObject.parts : Array.isArray(systemInstruction) ? systemInstruction : [];
+  const textParts = parts.flatMap(part => {
+    if (typeof part === 'string') {
+      return [part];
+    }
+    if (part && typeof part === 'object' && typeof part.text === 'string') {
+      return [part.text];
+    }
+    return [];
+  });
+  return textParts.length > 0 ? textParts.join('') : null;
+}
+const MODEL_PARAM_KEYS = ['temperature', 'topP', 'topK', 'maxOutputTokens', 'candidateCount', 'stopSequences', 'presencePenalty', 'frequencyPenalty', 'seed'];
+function extractModelParameters(config) {
+  const params = {};
+  if (!config || typeof config !== 'object') {
+    return params;
+  }
+  const source = config;
+  for (const key of MODEL_PARAM_KEYS) {
+    if (source[key] !== undefined) {
+      params[key] = source[key];
+    }
+  }
+  return params;
+}
+function extractTools(llmRequest) {
+  const tools = llmRequest.config?.tools;
+  return Array.isArray(tools) && tools.length > 0 ? tools : null;
+}
+
+export { PostHogADKPlugin };
+//# sourceMappingURL=index.mjs.map