pi-langfuse 1.5.18 → 1.6.0

package/src/handlers/session.ts

@@ -0,0 +1,90 @@
+import { applyCapturePolicy } from "../capture-policy.js";
+import { getRuntime } from "../langfuse.js";
+import { startChildObservation } from "../observation.js";
+import { state } from "../state.js";
+import {
+  extractCostDetails,
+  extractUsage,
+  getCapturePolicy,
+  shapePayload,
+} from "../utils.js";
+
+type RecordLike = Record<string, unknown>;
+
+function namesFromTools(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((tool) => {
+    if (typeof tool === "string") return [tool];
+    if (!tool || typeof tool !== "object") return [];
+    const name = (tool as RecordLike).name;
+    return typeof name === "string" ? [name] : [];
+  });
+}
+
+export async function recordSessionCompaction(event: RecordLike): Promise<void> {
+  const agent = state.agentState;
+  if (state.isTracingDisabled || !agent?.root) return;
+
+  const entry = event.compactionEntry && typeof event.compactionEntry === "object"
+    ? event.compactionEntry as RecordLike
+    : {};
+  const checkpoint = entry.systemMessage && typeof entry.systemMessage === "object"
+    ? entry.systemMessage as RecordLike
+    : undefined;
+  const checkpointTools = namesFromTools(checkpoint?.toolsAdded);
+  const checkpointSections = checkpoint?.sections && typeof checkpoint.sections === "object"
+    ? Object.keys(checkpoint.sections as RecordLike)
+    : [];
+  const captured = applyCapturePolicy(
+    {
+      input: shapePayload({ summary: entry.summary }),
+      metadata: {
+        reason: event.reason,
+        willRetry: event.willRetry,
+        fromExtension: event.fromExtension,
+        compactionEntryId: entry.id,
+        firstKeptEntryId: entry.firstKeptEntryId,
+        tokensBefore: entry.tokensBefore,
+        checkpointSectionNames: checkpointSections,
+        checkpointToolNames: checkpointTools,
+        checkpointToolCount: checkpointTools.length,
+        promptStateHash: agent.promptStateHash,
+        toolStateHash: agent.toolStateHash,
+      },
+    },
+    getCapturePolicy(),
+  );
+
+  try {
+    const parent = agent.activeTurn ?? agent.activeAttempt ?? agent.root;
+    const compaction = await startChildObservation({
+      parent,
+      runtime: getRuntime,
+      name: "session-compaction",
+      body: { input: captured.input, metadata: captured.metadata },
+      asType: "span",
+    });
+
+    if (entry.usage && typeof entry.usage === "object") {
+      const summary = applyCapturePolicy({ output: entry.summary }, getCapturePolicy());
+      const costDetails = extractCostDetails({ usage: entry.usage });
+      const generation = await startChildObservation({
+        parent: compaction,
+        runtime: getRuntime,
+        name: "compaction-summary",
+        body: {
+          output: summary.output,
+          model: state.currentModel || undefined,
+          usageDetails: extractUsage({ usage: entry.usage }),
+          ...(costDetails ? { costDetails } : {}),
+          metadata: { provider: state.currentProvider || undefined },
+        },
+        asType: "generation",
+      });
+      generation.end();
+    }
+    compaction.end();
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to record session compaction", error);
+  }
+}

package/src/handlers/system-state.ts

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+
+import { applyCapturePolicy } from "../capture-policy.js";
+import { getRuntime } from "../langfuse.js";
+import { startChildObservation } from "../observation.js";
+import { getSessionRunState, state } from "../state.js";
+import { getCapturePolicy, shapePayload } from "../utils.js";
+
+type RecordLike = Record<string, unknown>;
+
+function fingerprint(value: string): string {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function toolName(tool: unknown): string | undefined {
+  if (typeof tool === "string") return tool;
+  if (!tool || typeof tool !== "object") return undefined;
+  const name = (tool as RecordLike).name;
+  return typeof name === "string" && name ? name : undefined;
+}
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort();
+}
+
+function readNewSystemMessages(ctx: any): Array<{ entryId: string; message: RecordLike }> {
+  const session = getSessionRunState();
+  let branch: unknown;
+  try {
+    branch = ctx?.sessionManager?.getBranch?.();
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(branch)) return [];
+
+  const messages: Array<{ entryId: string; message: RecordLike }> = [];
+  for (const rawEntry of branch) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const entry = rawEntry as RecordLike;
+    const message = entry.message;
+    if (entry.type !== "message" || !message || typeof message !== "object") continue;
+    if ((message as RecordLike).role !== "system") continue;
+    const entryId = typeof entry.id === "string" ? entry.id : "";
+    if (!entryId || session.seenSystemEntryIds.has(entryId)) continue;
+    session.seenSystemEntryIds.add(entryId);
+    messages.push({ entryId, message: message as RecordLike });
+  }
+  return messages;
+}
+
+/** Mark restored transcript state as already seen so the first trace emits one snapshot, not the full history. */
+export function initializeSystemStateTracking(ctx: any): void {
+  const session = getSessionRunState();
+  try {
+    const branch = ctx?.sessionManager?.getBranch?.();
+    if (!Array.isArray(branch)) return;
+    for (const rawEntry of branch) {
+      if (!rawEntry || typeof rawEntry !== "object") continue;
+      const entry = rawEntry as RecordLike;
+      const message = entry.message;
+      if (
+        entry.type === "message" &&
+        typeof entry.id === "string" &&
+        message &&
+        typeof message === "object" &&
+        (message as RecordLike).role === "system"
+      ) {
+        session.seenSystemEntryIds.add(entry.id);
+      }
+    }
+  } catch {
+    // Session history is optional in SDK/headless hosts.
+  }
+}
+
+export async function recordSystemState(ctx: any, activeTools: string[]): Promise<void> {
+  const agent = state.agentState;
+  if (state.isTracingDisabled || !agent?.root) return;
+
+  let prompt = "";
+  try {
+    prompt = String((await ctx?.getSystemPrompt?.()) ?? "");
+  } catch {
+    // The tool state is still useful when a host cannot expose the rendered prompt.
+  }
+
+  const tools = sortedUnique(activeTools);
+  const promptStateHash = prompt ? fingerprint(prompt) : undefined;
+  const toolStateHash = fingerprint(JSON.stringify(tools));
+  const session = getSessionRunState();
+  const systemMessages = readNewSystemMessages(ctx);
+
+  const transcriptToolsAdded: string[] = [];
+  const transcriptToolsRemoved: string[] = [];
+  const sectionsChanged = new Set<string>();
+  const sectionsRemoved = new Set<string>();
+  const entryIds: string[] = [];
+  for (const { entryId, message } of systemMessages) {
+    entryIds.push(entryId);
+    const sections = message.sections;
+    if (sections && typeof sections === "object" && !Array.isArray(sections)) {
+      for (const [name, value] of Object.entries(sections as RecordLike)) {
+        (value === null ? sectionsRemoved : sectionsChanged).add(name);
+      }
+    }
+    if (Array.isArray(message.toolsAdded)) {
+      for (const tool of message.toolsAdded) {
+        const name = toolName(tool);
+        if (name) transcriptToolsAdded.push(name);
+      }
+    }
+    if (Array.isArray(message.toolsRemoved)) {
+      for (const tool of message.toolsRemoved) {
+        const name = toolName(tool);
+        if (name) transcriptToolsRemoved.push(name);
+      }
+    }
+  }
+
+  const previousTools = new Set(session.lastActiveTools);
+  const currentTools = new Set(tools);
+  const toolsAdded = sortedUnique([
+    ...tools.filter((name) => !previousTools.has(name)),
+    ...transcriptToolsAdded,
+  ]);
+  const toolsRemoved = sortedUnique([
+    ...session.lastActiveTools.filter((name) => !currentTools.has(name)),
+    ...transcriptToolsRemoved,
+  ]);
+  const promptChanged = session.lastPromptStateHash !== promptStateHash;
+  const toolsChanged = session.lastToolStateHash !== toolStateHash;
+  const isInitial = session.lastPromptStateHash === undefined && session.lastToolStateHash === undefined;
+  const changed = isInitial || promptChanged || toolsChanged || systemMessages.length > 0;
+  if (changed) session.systemStateSequence++;
+
+  const capturePolicy = getCapturePolicy();
+  const rawSystemUpdate = systemMessages.length > 0
+    ? systemMessages.map(({ entryId, message }) => ({ entryId, ...message }))
+    : { role: "system", content: prompt };
+  const captured = applyCapturePolicy(
+    {
+      systemPrompt: shapePayload(rawSystemUpdate),
+      metadata: {
+        stateSequence: session.systemStateSequence,
+        changeKind: isInitial ? "initial" : changed ? "updated" : "unchanged",
+        source: systemMessages.length > 0 ? "transcript" : "effective-snapshot",
+        transcriptEntryIds: entryIds,
+        promptStateHash,
+        toolStateHash,
+        promptChars: prompt.length,
+        activeToolCount: tools.length,
+        activeTools: tools,
+        toolsAdded,
+        toolsRemoved,
+        sectionsChanged: sortedUnique(sectionsChanged),
+        sectionsRemoved: sortedUnique(sectionsRemoved),
+      },
+    },
+    capturePolicy,
+  );
+
+  try {
+    const observation = await startChildObservation({
+      parent: agent.activeAttempt ?? agent.root,
+      runtime: getRuntime,
+      name: "system-state",
+      body: {
+        input: captured.systemPrompt,
+        metadata: captured.metadata,
+      },
+      asType: "event",
+    });
+    observation.end();
+  } catch (error) {
+    console.warn("📊 Langfuse: Failed to record system state", error);
+  }
+
+  if (changed) agent.systemStateChangeCount = (agent.systemStateChangeCount ?? 0) + 1;
+  agent.promptStateHash = promptStateHash;
+  agent.toolStateHash = toolStateHash;
+  agent.systemStateSequence = session.systemStateSequence;
+  agent.activeToolCount = tools.length;
+  session.lastPromptStateHash = promptStateHash;
+  session.lastToolStateHash = toolStateHash;
+  session.lastActiveTools = tools;
+}

package/src/handlers/tool.ts

@@ -37,7 +37,7 @@ export async function startToolObservation(event: Record<string, unknown>) {
       getCapturePolicy(),
     );
     const inputBytes = estimatePayloadBytes(captured.toolInput, getLimits().maxToolPayload);
-    const parent = state.agentState.activeTurn ?? state.agentState.root;
+    const parent = state.agentState.activeTurn ?? state.agentState.activeAttempt ?? state.agentState.root;
     const tool = await startChildObservation({
       parent,
       runtime: getRuntime,

package/src/handlers/turn.ts

@@ -25,7 +25,7 @@ export async function startTurnObservation(event: Record<string, unknown>) {
       getCapturePolicy(),
     );
     const observation = await startChildObservation({
-      parent: state.agentState.root,
+      parent: state.agentState.activeAttempt ?? state.agentState.root,
       runtime: getRuntime,
       name: "turn",
       body: {

package/src/langfuse.ts

@@ -463,25 +463,73 @@ function observationType(asType?: string): FallbackObservationType {
  * `LangfuseSpanProcessor.onStart(span, parentContext)`, reading them from the
  * OTel context that was active when the span was created. `propagateAttributes`
  * only seeds that context for the duration of its callback, so a child created
- * later — from a separate event handler, outside the callback — is written with
- * an empty `session.id`.
+ * later — from a separate event handler, outside the callback — is written
+ * without `session.id`, `langfuse.trace.name`, or `langfuse.trace.metadata.*`.
  *
- * That is invisible in the legacy data model, where the session lives on the
- * trace, but Langfuse v4 stores `session_id` per event row and aggregates a
- * session with `WHERE session_id != ''`. Unstamped children drop out of
- * `sumMap(cost_details)` and `sumMap(usage_details)`, which is why such
- * sessions report their trace count correctly but no cost and no usage at all.
+ * That is invisible in the legacy data model, where those live on the trace,
+ * but Langfuse v4 stores them per event row and filters and aggregates over
+ * those rows: a session is `WHERE session_id != ''`, and cost by trace name
+ * matches `trace_name` on the generation itself. Unstamped children drop out
+ * of `sumMap(cost_details)` and `sumMap(usage_details)`, which is why such
+ * sessions and trace-name filters report a correct trace count but no cost
+ * and no usage at all.
  *
- * Re-entering the propagated context for every child keeps the whole tree in
- * the session. The id is read back off the parent span rather than from
- * `state.currentSessionId`, so a child created outside an active session scope
- * still inherits whatever its parent was actually stamped with.
+ * Re-entering the propagated context for every child keeps the whole tree
+ * queryable. The attributes are read back off the parent span rather than
+ * from state, so a child created outside an active session scope still
+ * inherits whatever its parent was actually stamped with, and grandchildren
+ * inherit transitively.
+ *
+ * The re-entry runs on the OTel root context, not the ambient one.
+ * `propagateAttributes` starts from `context.active()`, merges `metadata`
+ * and `tags` with whatever that context already carries, and stamps the
+ * active span if there is one. Any attributes propagated by the caller —
+ * another instrumentation, a foreign `propagateAttributes` scope — would
+ * otherwise leak into the child or onto an unrelated span. The parent is
+ * still explicit: `observation.startObservation` passes the parent span
+ * context to the child, so a clean ambient context changes nothing else.
  */
-const OTEL_SESSION_ID_ATTRIBUTE = "session.id";
+type PropagatedAttributes = Parameters<LangfuseRuntime["propagateAttributes"]>[0];
+
+const PROPAGATED_STRING_ATTRIBUTES = {
+  sessionId: "session.id",
+  userId: "user.id",
+  traceName: "langfuse.trace.name",
+  version: "langfuse.version",
+} as const;
+const OTEL_TRACE_TAGS_ATTRIBUTE = "langfuse.trace.tags";
+const OTEL_TRACE_METADATA_PREFIX = "langfuse.trace.metadata.";
+
+function readPropagatedAttributes(observation: any): PropagatedAttributes {
+  const attributes: Record<string, unknown> = observation?.otelSpan?.attributes ?? {};
+  const propagated: PropagatedAttributes = {};
+
+  for (const [key, attribute] of Object.entries(PROPAGATED_STRING_ATTRIBUTES)) {
+    const value = attributes[attribute];
+    if (typeof value === "string" && value) {
+      propagated[key as keyof typeof PROPAGATED_STRING_ATTRIBUTES] = value;
+    }
+  }
+
+  const tags = attributes[OTEL_TRACE_TAGS_ATTRIBUTE];
+  if (Array.isArray(tags)) {
+    const validTags = tags.filter((tag): tag is string => typeof tag === "string" && tag.length > 0);
+    if (validTags.length > 0) {
+      propagated.tags = validTags;
+    }
+  }
 
-function readSessionId(observation: any): string | undefined {
-  const value = observation?.otelSpan?.attributes?.[OTEL_SESSION_ID_ATTRIBUTE];
-  return typeof value === "string" && value ? value : undefined;
+  const metadata: Record<string, string> = {};
+  for (const [key, value] of Object.entries(attributes)) {
+    if (key.startsWith(OTEL_TRACE_METADATA_PREFIX) && typeof value === "string") {
+      metadata[key.slice(OTEL_TRACE_METADATA_PREFIX.length)] = value;
+    }
+  }
+  if (Object.keys(metadata).length > 0) {
+    propagated.metadata = metadata;
+  }
+
+  return propagated;
 }
 
 function wrapObservation(
@@ -543,12 +591,19 @@ function wrapObservation(
       return observation.end();
     },
     startObservation(childName: string, childBody?: Record<string, unknown>, options?: { asType?: string }) {
-      const inheritedSessionId = readSessionId(observation) ?? state.currentSessionId ?? undefined;
+      const inherited = readPropagatedAttributes(observation);
+      const fallbackSessionId = state.currentSessionId?.slice(0, 200);
+      if (!inherited.sessionId && fallbackSessionId) {
+        inherited.sessionId = fallbackSessionId;
+      }
       const propagate = runtime?.propagateAttributes;
       const createChild = () => observation.startObservation(childName, childBody, options);
-      const child = inheritedSessionId && propagate
-        ? propagate({ sessionId: inheritedSessionId.slice(0, 200) }, createChild)
-        : createChild();
+      const createInheritingChild = propagate && Object.keys(inherited).length > 0
+        ? () => propagate(inherited, createChild)
+        : createChild;
+      const child = runtime?.withRootContext
+        ? runtime.withRootContext(createInheritingChild)
+        : createInheritingChild();
       return wrapObservation(child, store, childName, childBody, options?.asType, id);
     },
     setTraceIO(traceBody?: { input?: unknown; output?: unknown }) {
@@ -777,7 +832,7 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
     const [
       { BasicTracerProvider },
       { resources },
-      { context },
+      { context, ROOT_CONTEXT },
       { AsyncHooksContextManager },
       { LangfuseSpanProcessor },
       tracing,
@@ -822,6 +877,7 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
           return wrapObservation(observation, restFallback, name, body, options?.asType);
         }) as unknown as LangfuseRuntime["startObservation"],
         propagateAttributes: tracing.propagateAttributes as unknown as LangfuseRuntime["propagateAttributes"],
+        withRootContext: (fn) => context.with(ROOT_CONTEXT, fn),
         scoreClient: new LangfuseClient({
           publicKey: state.config.publicKey,
           secretKey: state.config.secretKey,

package/src/observation.ts

@@ -11,7 +11,7 @@ export async function startChildObservation({
   runtime: () => Promise<LangfuseRuntime>;
   name: string;
   body?: ObservationUpdate;
-  asType: "generation" | "tool" | "span";
+  asType: "event" | "generation" | "tool" | "span";
 }): Promise<LangfuseObservation> {
   if (parent.startObservation) {
     return parent.startObservation(name, body, { asType });

package/src/state.ts

@@ -10,6 +10,12 @@ export interface SessionRunState {
   turnCount: number;
   tracingDisabled: boolean;
   setupAttemptedThisSession: boolean;
+  lastPromptStateHash?: string;
+  lastToolStateHash?: string;
+  lastActiveTools: string[];
+  systemStateSequence: number;
+  seenSystemEntryIds: Set<string>;
+  seenUsageEntryIds: Set<string>;
 }
 
 const DEFAULT_SESSION_ID = "__pi_langfuse_default_session__";
@@ -27,6 +33,10 @@ function createSessionRunState(): SessionRunState {
     turnCount: 0,
     tracingDisabled: false,
     setupAttemptedThisSession: false,
+    lastActiveTools: [],
+    systemStateSequence: 0,
+    seenSystemEntryIds: new Set(),
+    seenUsageEntryIds: new Set(),
   };
 }
 
@@ -130,11 +140,16 @@ export const state = {
 
 export function resetRunState(sessionId = getActiveSessionId()) {
   const normalizedSessionId = normalizeSessionId(sessionId);
-  const setupAttemptedThisSession =
-    state.sessionStates.get(normalizedSessionId)?.setupAttemptedThisSession ?? false;
+  const previous = state.sessionStates.get(normalizedSessionId);
   state.sessionStates.set(normalizedSessionId, {
     ...createSessionRunState(),
-    setupAttemptedThisSession,
+    setupAttemptedThisSession: previous?.setupAttemptedThisSession ?? false,
+    lastPromptStateHash: previous?.lastPromptStateHash,
+    lastToolStateHash: previous?.lastToolStateHash,
+    lastActiveTools: previous?.lastActiveTools ?? [],
+    systemStateSequence: previous?.systemStateSequence ?? 0,
+    seenSystemEntryIds: previous?.seenSystemEntryIds ?? new Set(),
+    seenUsageEntryIds: previous?.seenUsageEntryIds ?? new Set(),
   });
 }
 

package/src/types.ts

@@ -19,7 +19,7 @@ export interface LangfuseObservation {
   startObservation?(
     name: string,
     body?: ObservationUpdate,
-    options?: { asType?: "agent" | "generation" | "tool" | "span" },
+    options?: { asType?: "agent" | "event" | "generation" | "tool" | "span" },
   ): LangfuseObservation;
   setTraceIO?(body?: { input?: unknown; output?: unknown }): void;
 }
@@ -82,17 +82,25 @@ export interface LangfuseRuntime {
   startObservation: (
     name: string,
     body?: ObservationUpdate,
-    options?: { asType?: "agent" | "generation" | "tool" | "span" },
+    options?: { asType?: "agent" | "event" | "generation" | "tool" | "span" },
   ) => LangfuseObservation;
   propagateAttributes: (
     params: {
       sessionId?: string;
+      userId?: string;
       traceName?: string;
+      version?: string;
       metadata?: Record<string, string>;
       tags?: string[];
     },
     fn: () => LangfuseObservation,
   ) => LangfuseObservation;
+  /**
+   * Runs `fn` on the OTel root context, so the observations it creates take
+   * their propagated attributes only from what is passed explicitly and not
+   * from whatever the caller's ambient context happens to carry.
+   */
+  withRootContext?: <T>(fn: () => T) => T;
   scoreClient: LangfuseScoreClient;
   spanProcessor?: { forceFlush?: () => Promise<void>; shutdown?: () => Promise<void> };
   tracerProvider?: { forceFlush?: () => Promise<void>; shutdown?: () => Promise<void> };
@@ -128,6 +136,7 @@ export interface ToolState {
 
 export interface AgentState {
   root?: LangfuseObservation;
+  activeAttempt?: LangfuseObservation;
   activeTurn?: LangfuseObservation;
   traceId?: string;
   promptInput?: unknown;
@@ -139,4 +148,14 @@ export interface AgentState {
   latestAssistantOutput?: unknown;
   sourceMetadata?: Record<string, unknown>;
   providerMetadataByRequest: Map<string, Record<string, unknown>>;
+  attemptCount: number;
+  lastAgentEndEvent?: Record<string, unknown>;
+  promptStateHash?: string;
+  toolStateHash?: string;
+  systemStateSequence?: number;
+  activeToolCount?: number;
+  systemStateChangeCount: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  uncachedInputTokens: number;
 }

package/src/utils.ts

@@ -334,6 +334,55 @@ export function getProviderPayload(event: Record<string, unknown>): unknown {
   return event.request ?? event.payload ?? event.body ?? event.providerPayload ?? event.messages ?? event;
 }
 
+export type ToolUpdateTransport =
+  | "anthropic-native"
+  | "openai-additional-tools"
+  | "openai-tool-search"
+  | "mid-conversation-system"
+  | "collapsed-leading-system";
+
+/** Classify the provider payload observed by this hook rather than guessing from the model name alone. */
+export function inferToolUpdateTransport(payload: unknown, hasPriorSystemState: boolean): ToolUpdateTransport | undefined {
+  let sawToolChangeBlock = false;
+  let sawAdditionalTools = false;
+  let sawToolSearch = false;
+  let sawTopLevelTools = false;
+  let sawMidConversationSystem = false;
+  let visited = 0;
+
+  const walk = (value: unknown, key?: string) => {
+    if (++visited > 2_000 || value === null || value === undefined) return;
+    if (key === "additional_tools") sawAdditionalTools = true;
+    if (key === "tools") sawTopLevelTools = true;
+    if (key === "tool_search" || key === "tool_search_output") sawToolSearch = true;
+    if (typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      let sawNonSystem = false;
+      for (const item of value) {
+        if (item && typeof item === "object" && !Array.isArray(item)) {
+          const role = (item as Record<string, unknown>).role;
+          if (role === "system" && sawNonSystem) sawMidConversationSystem = true;
+          if (role && role !== "system") sawNonSystem = true;
+        }
+        walk(item);
+      }
+      return;
+    }
+    const record = value as Record<string, unknown>;
+    const type = record.type;
+    if (type === "tool_addition" || type === "tool_removal") sawToolChangeBlock = true;
+    for (const [childKey, child] of Object.entries(record)) walk(child, childKey);
+  };
+
+  walk(payload);
+  if (sawToolChangeBlock) return "anthropic-native";
+  if (sawAdditionalTools) return "openai-additional-tools";
+  if (sawToolSearch) return "openai-tool-search";
+  if (sawMidConversationSystem) return "mid-conversation-system";
+  if (hasPriorSystemState && sawTopLevelTools) return "collapsed-leading-system";
+  return undefined;
+}
+
 export function extractModelParameters(payload: unknown): Record<string, string | number> | undefined {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
     return undefined;
@@ -487,6 +536,32 @@ export function extractUsage(
   };
 }
 
+export function extractCacheMetrics(messageOrEvent: Record<string, unknown>): {
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  uncachedInputTokens: number;
+  cacheHitRatio?: number;
+} | undefined {
+  const usage = (messageOrEvent.usage ??
+    (messageOrEvent.message && typeof messageOrEvent.message === "object"
+      ? (messageOrEvent.message as Record<string, unknown>).usage
+      : undefined)) as Record<string, unknown> | undefined;
+  if (!usage || typeof usage !== "object") return undefined;
+
+  const uncachedInputTokens = Number(
+    usage.input ?? usage.inputTokens ?? usage.prompt_tokens ?? usage.promptTokens ?? 0,
+  );
+  const cacheReadTokens = Number(usage.cacheRead ?? usage.cache_read ?? usage.cachedTokens ?? 0);
+  const cacheWriteTokens = Number(usage.cacheWrite ?? usage.cache_write ?? 0);
+  const denominator = uncachedInputTokens + cacheReadTokens;
+  return {
+    cacheReadTokens,
+    cacheWriteTokens,
+    uncachedInputTokens,
+    ...(denominator > 0 ? { cacheHitRatio: cacheReadTokens / denominator } : {}),
+  };
+}
+
 export function extractCostDetails(messageOrEvent: Record<string, unknown>): Record<string, number> | undefined {
   const usage = (messageOrEvent.usage ??
     (messageOrEvent.message && typeof messageOrEvent.message === "object"

package/types/langfuse-runtime-shims.d.ts

@@ -1,49 +0,0 @@
-declare module "@opentelemetry/sdk-trace-base" {
-  export class BasicTracerProvider {
-    constructor(options?: { resource?: unknown; spanProcessors?: unknown[] });
-    forceFlush?(): Promise<void>;
-    shutdown?(): Promise<void>;
-  }
-}
-
-declare module "@langfuse/otel" {
-  export class LangfuseSpanProcessor {
-    constructor(options: {
-      publicKey: string;
-      secretKey: string;
-      baseUrl: string;
-    });
-    forceFlush?(): Promise<void>;
-    shutdown?(): Promise<void>;
-  }
-}
-
-declare module "@langfuse/tracing" {
-  export function setLangfuseTracerProvider(provider: unknown): void;
-
-  export function startObservation(
-    name: string,
-    body?: Record<string, unknown>,
-    options?: { asType?: string },
-  ): unknown;
-
-  export function propagateAttributes<T>(
-    params: {
-      sessionId?: string;
-      traceName?: string;
-      metadata?: Record<string, string>;
-      tags?: string[];
-    },
-    fn: () => T,
-  ): T;
-}
-
-declare module "@langfuse/client" {
-  export class LangfuseClient {
-    constructor(options: {
-      publicKey: string;
-      secretKey: string;
-      baseUrl: string;
-    });
-  }
-}