pi-langfuse 1.5.16 → 1.5.18

package/README.md

@@ -109,12 +109,38 @@ export LANGFUSE_CAPTURE_TOOL_IO=false
 export LANGFUSE_CAPTURE_SYSTEM_PROMPT=false
 export LANGFUSE_CAPTURE_CWD=false
 export LANGFUSE_CAPTURE_SOURCE_METADATA=false
+export LANGFUSE_CAPTURE_PATHS=false
 ```
 
 Source metadata remains off in every preset unless `LANGFUSE_CAPTURE_SOURCE_METADATA=true` is set explicitly.
+The same holds for absolute paths and `LANGFUSE_CAPTURE_PATHS`.
 
 All captured payloads are redacted before upload. The extension masks common API keys, bearer tokens, passwords, cookies, private keys, Langfuse keys, GitHub/npm/AWS-style tokens, and local absolute paths.
 
+### Absolute paths
+
+By default, local absolute paths (`/Users/...`, `/home/...`, `/tmp/...`, `C:\Users\...`) are
+replaced everywhere with a stable `[PATH_HASH:<12 hex chars>]` digest, so usernames and repository
+names never reach Langfuse. This applies to inputs, outputs, tool I/O, tool error messages, and the
+`cwd` metadata field. Opt in to see real paths in traces:
+
+```bash
+export LANGFUSE_CAPTURE_PATHS=true
+```
+
+Or persist it in `config.json`:
+
+```json
+{ "capture": { "LANGFUSE_CAPTURE_PATHS": "true" } }
+```
+
+Like `LANGFUSE_CAPTURE_SOURCE_METADATA`, this stays off in every privacy preset until it is set
+explicitly, and it only affects paths — secret masking (tokens, keys, cookies, passwords) is always
+on regardless. Note that `LANGFUSE_CAPTURE_CWD=false` is a different control: it drops the `cwd`
+metadata field entirely rather than changing how paths are rendered.
+
+`/langfuse-status` reports the current setting under `Capture: absolute paths`.
+
 ### Payload limits
 
 Before upload, payloads are shaped: strings are truncated and deeply nested or
@@ -149,6 +175,44 @@ export PI_LANGFUSE_MAX_FALLBACK_TOTAL_BYTES=33554432  # whole-payload ceiling, d
 When the accumulated fallback payload exceeds the 32MB ceiling, ingestion is
 skipped with a warning instead of attempting an unrecoverably large upload.
 
+### Reasoning tokens
+
+Pi reports reasoning (thinking) tokens for Anthropic, OpenAI Codex, OpenRouter,
+opencode-go and Qwen. Providers count them inside `output`, and by default the
+extension reports `output` whole, so the reasoning share is not visible in
+Langfuse. Opt in to report it as its own usage bucket:
+
+```bash
+export PI_LANGFUSE_SPLIT_REASONING_TOKENS=true
+```
+
+Or persist it in `config.json`:
+
+```json
+{ "capture": { "PI_LANGFUSE_SPLIT_REASONING_TOKENS": "true" } }
+```
+
+With the split on, a generation that used 37 output tokens of which 10 were
+reasoning is reported as `output: 27` plus `output_reasoning_tokens: 10`. Both
+keys contain `output`, so the Output row in Langfuse still shows 37; only the
+breakdown beneath it gains the reasoning share. Reasoning is clamped to the
+reported `output`, so the buckets always add up to the total.
+
+> **Before enabling — check your model prices.** Langfuse matches prices to
+> usage by exact key, and model definitions you created in your project take
+> precedence over Langfuse's maintained defaults. A custom model priced on
+> `input` and `output` only would cost `output_reasoning_tokens` at zero, so
+> reasoning-heavy generations would look cheaper than they are. Add a price
+> for `output_reasoning_tokens` to every custom reasoning model in
+> **Settings → Models** first, then turn the split on. Langfuse's built-in
+> prices for reasoning models already include it. Providers that report their
+> own cost are unaffected: Langfuse uses the reported cost as-is and does not
+> recompute it from usage.
+
+The split is off by default, so upgrading changes nothing until you enable it.
+Unset `PI_LANGFUSE_SPLIT_REASONING_TOKENS` (or set it to `false`) to go back;
+traces already ingested keep their buckets.
+
 ### Method 3: Persistent `config.json`
 
 Create or update `~/.pi/agent/pi-langfuse/config.json`:
@@ -204,6 +268,7 @@ This command makes a timeout-bounded authenticated request to Langfuse and, if i
 - The trace contains the final assistant output shown in Pi.
 - Tool runs appear as tool observations with arguments, results, and error state.
 - LLM requests appear as generation observations, including usage and cost when the provider exposes them.
+  Reasoning tokens are reported as their own usage bucket when `PI_LANGFUSE_SPLIT_REASONING_TOKENS` is enabled.
 - Trace-level scores include tool counts, tool success rate, and whether the run had errors.
 
 The package also includes a Langfuse CLI skill, so Langfuse data can be queried directly from Pi:

package/README_CN.md

@@ -109,12 +109,36 @@ export LANGFUSE_CAPTURE_TOOL_IO=false
 export LANGFUSE_CAPTURE_SYSTEM_PROMPT=false
 export LANGFUSE_CAPTURE_CWD=false
 export LANGFUSE_CAPTURE_SOURCE_METADATA=false
+export LANGFUSE_CAPTURE_PATHS=false
 ```
 
 所有隐私预设默认都关闭源码元数据；只有显式设置 `LANGFUSE_CAPTURE_SOURCE_METADATA=true` 才会启用。
+绝对路径与 `LANGFUSE_CAPTURE_PATHS` 同理。
 
 所有被采集的负载在上传前仍会脱敏。扩展会隐藏常见 API key、Bearer token、密码、Cookie、私钥、Langfuse key、GitHub/npm/AWS 风格 token，并对本地绝对路径做 hash。
 
+### 绝对路径
+
+默认情况下，本地绝对路径（`/Users/...`、`/home/...`、`/tmp/...`、`C:\Users\...`）会在所有位置被替换为
+稳定的 `[PATH_HASH:<12 位十六进制>]` 摘要，因此用户名和仓库名不会进入 Langfuse。该规则作用于输入、输出、
+工具 I/O、工具错误信息以及 `cwd` 元数据字段。若希望在 trace 中看到真实路径，需要显式开启：
+
+```bash
+export LANGFUSE_CAPTURE_PATHS=true
+```
+
+也可以持久化到 `config.json`：
+
+```json
+{ "capture": { "LANGFUSE_CAPTURE_PATHS": "true" } }
+```
+
+与 `LANGFUSE_CAPTURE_SOURCE_METADATA` 一样，它在所有隐私预设中默认关闭，且只影响路径；密钥脱敏（token、key、
+Cookie、密码）始终生效。注意 `LANGFUSE_CAPTURE_CWD=false` 是另一个控制项——它会直接丢弃 `cwd` 元数据字段，
+而不是改变路径的呈现方式。
+
+`/langfuse-status` 会在 `Capture: absolute paths` 下显示当前设置。
+
 ### 负载上限
 
 上传前会对负载做整形：字符串会被截断，过深或过宽的结构会被裁剪。这些上限让 trace 保持精简，同时保护
@@ -143,6 +167,33 @@ export PI_LANGFUSE_MAX_FALLBACK_TOTAL_BYTES=33554432  # 整体负载上限，默
 
 当累积的回退负载超过 32MB 上限时，会跳过摄取并给出告警，而不是尝试一次注定失败的超大上传。
 
+### 推理（reasoning）token
+
+Pi 会为 Anthropic、OpenAI Codex、OpenRouter、opencode-go 和 Qwen 上报推理（thinking）token。提供商将其计入
+`output`，扩展默认也原样上报整个 `output`，因此在 Langfuse 中看不到推理部分的占比。可显式开启，将其作为独立用量桶上报：
+
+```bash
+export PI_LANGFUSE_SPLIT_REASONING_TOKENS=true
+```
+
+也可以持久化到 `config.json`：
+
+```json
+{ "capture": { "PI_LANGFUSE_SPLIT_REASONING_TOKENS": "true" } }
+```
+
+开启后，一次消耗 37 个输出 token（其中 10 个为推理）的生成会上报为 `output: 27` 加
+`output_reasoning_tokens: 10`。两个键都包含 `output`，所以 Langfuse 的 Output 行仍显示 37，只是其下的明细多出推理占比。
+推理数会被限制在上报的 `output` 范围内，因此各桶之和始终等于总量。
+
+> **开启前请先检查模型价格。** Langfuse 按键名精确匹配用量与价格，且你在项目中自定义的模型定义优先于 Langfuse 维护的
+> 默认值。若自定义模型只定义了 `input` 和 `output` 价格，`output_reasoning_tokens` 会按零计价，推理密集的生成会显得比实际便宜。
+> 请先在 **Settings → Models** 中为每个自定义推理模型补上 `output_reasoning_tokens` 的价格，再开启拆分。Langfuse 内置的
+> 推理模型价格已包含该键。自行上报成本的提供商不受影响：Langfuse 会直接使用上报的成本，不会再根据用量重新计算。
+
+该拆分默认关闭，升级后在你显式开启之前不会有任何变化。取消设置 `PI_LANGFUSE_SPLIT_REASONING_TOKENS`（或设为 `false`）即可回退；
+已摄取的 trace 保留其原有用量桶。
+
 ### 方式 3：持久化 `config.json`
 
 创建或更新 `~/.pi/agent/pi-langfuse/config.json`：
@@ -198,6 +249,7 @@ pi list
 - trace 中会包含 Pi 实际显示的最终助手回复。
 - 工具执行会以工具观察节点展示参数、结果和错误状态。
 - 模型请求会以生成观察节点展示；如果提供商暴露相关信息，还会包含用量和成本。
+  开启 `PI_LANGFUSE_SPLIT_REASONING_TOKENS` 后，推理 token 会作为独立用量桶上报。
 - trace 级别会记录工具调用次数、工具成功率和是否出现错误。
 
 此包还包含一个内置 Langfuse 技能，可直接在 Pi 中查询 Langfuse 数据：

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.5.16",
+	"version": "1.5.18",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",

package/src/capture-policy.ts

@@ -1,4 +1,4 @@
-import { hashPath, redactValue } from "./redaction.js";
+import { hashPath, redactValue, type RedactOptions } from "./redaction.js";
 
 export interface CapturePolicy {
   readonly captureInputs: boolean;
@@ -7,6 +7,17 @@ export interface CapturePolicy {
   readonly captureSystemPrompt: boolean;
   readonly captureCwd: boolean;
   readonly captureSourceMetadata: boolean;
+  /**
+   * Capture local absolute paths verbatim. Off in every preset, like
+   * `captureSourceMetadata`: paths are replaced with `[PATH_HASH:...]` unless
+   * `LANGFUSE_CAPTURE_PATHS` opts in explicitly.
+   */
+  readonly capturePaths: boolean;
+}
+
+/** Redaction options implied by a policy, so path rendering follows the same switch everywhere. */
+export function redactOptionsFor(policy: CapturePolicy): Partial<RedactOptions> {
+  return { redactPaths: !policy.capturePaths };
 }
 
 export type PrivacyPreset = "metadata-only" | "prompts-only" | "conversations" | "full-debug";
@@ -38,6 +49,7 @@ const PRESETS: Record<PrivacyPreset, CapturePolicy> = {
     captureSystemPrompt: false,
     captureCwd: false,
     captureSourceMetadata: false,
+    capturePaths: false,
   },
   "prompts-only": {
     captureInputs: true,
@@ -46,6 +58,7 @@ const PRESETS: Record<PrivacyPreset, CapturePolicy> = {
     captureSystemPrompt: false,
     captureCwd: false,
     captureSourceMetadata: false,
+    capturePaths: false,
   },
   conversations: {
     captureInputs: true,
@@ -54,6 +67,7 @@ const PRESETS: Record<PrivacyPreset, CapturePolicy> = {
     captureSystemPrompt: false,
     captureCwd: false,
     captureSourceMetadata: false,
+    capturePaths: false,
   },
   "full-debug": {
     captureInputs: true,
@@ -62,6 +76,7 @@ const PRESETS: Record<PrivacyPreset, CapturePolicy> = {
     captureSystemPrompt: true,
     captureCwd: true,
     captureSourceMetadata: false,
+    capturePaths: false,
   },
 };
 
@@ -72,9 +87,15 @@ const FLAG_TO_FIELD = {
   LANGFUSE_CAPTURE_SYSTEM_PROMPT: "captureSystemPrompt",
   LANGFUSE_CAPTURE_CWD: "captureCwd",
   LANGFUSE_CAPTURE_SOURCE_METADATA: "captureSourceMetadata",
+  LANGFUSE_CAPTURE_PATHS: "capturePaths",
 } as const;
 
-function parseFlag(value: string | undefined): boolean | undefined {
+/**
+ * Parse a boolean env flag. `1/true/yes/on` and `0/false/no/off` are
+ * case-insensitive; anything else (including unset) is `undefined` so the
+ * caller keeps its default.
+ */
+export function parseFlag(value: string | undefined): boolean | undefined {
   if (value === undefined) {
     return undefined;
   }
@@ -109,18 +130,20 @@ function redactMetadata(metadata: Record<string, unknown> | undefined, policy: C
     return undefined;
   }
 
+  const redactOptions = redactOptionsFor(policy);
   const output: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(metadata)) {
     if (key === "cwd") {
       if (!policy.captureCwd) {
         continue;
       }
-      output[key] = typeof value === "string" && /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value)
-        ? hashPath(value)
-        : redactValue(value);
+      output[key] =
+        !policy.capturePaths && typeof value === "string" && /^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(value)
+          ? hashPath(value)
+          : redactValue(value, redactOptions);
       continue;
     }
-    output[key] = redactValue(value);
+    output[key] = redactValue(value, redactOptions);
   }
   return Object.keys(output).length > 0 ? output : undefined;
 }
@@ -129,24 +152,25 @@ export function applyCapturePolicy(
   payload: RawTelemetryPayload,
   policy: CapturePolicy = createCapturePolicy(),
 ): CapturedTelemetryPayload {
+  const redactOptions = redactOptionsFor(policy);
   const captured: CapturedTelemetryPayload = {
     metadata: redactMetadata(payload.metadata, policy),
   };
 
   if (policy.captureInputs && "input" in payload) {
-    captured.input = redactValue(payload.input);
+    captured.input = redactValue(payload.input, redactOptions);
   }
   if (policy.captureOutputs && "output" in payload) {
-    captured.output = redactValue(payload.output);
+    captured.output = redactValue(payload.output, redactOptions);
   }
   if (policy.captureToolIo && "toolInput" in payload) {
-    captured.toolInput = redactValue(payload.toolInput);
+    captured.toolInput = redactValue(payload.toolInput, redactOptions);
   }
   if (policy.captureToolIo && "toolOutput" in payload) {
-    captured.toolOutput = redactValue(payload.toolOutput);
+    captured.toolOutput = redactValue(payload.toolOutput, redactOptions);
   }
   if (policy.captureSystemPrompt && "systemPrompt" in payload) {
-    captured.systemPrompt = redactValue(payload.systemPrompt);
+    captured.systemPrompt = redactValue(payload.systemPrompt, redactOptions);
   }
 
   return captured;

package/src/commands.ts

@@ -75,7 +75,7 @@ function isPrivacyPreset(value: string | undefined): value is PrivacyPreset {
 }
 
 function inferPreset(policy: CapturePolicy): PrivacyPreset | "custom" {
-  const entries: Array<[PrivacyPreset, Omit<CapturePolicy, "captureSourceMetadata">]> = [
+  const entries: Array<[PrivacyPreset, Omit<CapturePolicy, "captureSourceMetadata" | "capturePaths">]> = [
     [
       "metadata-only",
       {
@@ -140,6 +140,7 @@ function describePolicy(policy: CapturePolicy) {
     `captureSystemPrompt: ${policy.captureSystemPrompt}`,
     `captureCwd: ${policy.captureCwd}`,
     `captureSourceMetadata: ${policy.captureSourceMetadata}`,
+    `capturePaths: ${policy.capturePaths}`,
   ].join("\n");
 }
 
@@ -218,6 +219,7 @@ function formatStatus(configPath: string, env: Record<string, string | undefined
     `  tool IO: ${flag(policy.captureToolIo)}`,
     `  system prompt: ${flag(policy.captureSystemPrompt)}`,
     `  cwd: ${flag(policy.captureCwd)}`,
+    `  absolute paths: ${flag(policy.capturePaths)}`,
     `Active run: ${hasActiveAgentObservation() ? "yes" : "no"}`,
     `Last error: ${lastErrorSummary()}`,
   ].join("\n");

package/src/config.ts

@@ -6,6 +6,7 @@ import { state } from "./state.js";
 import { forceShutdownRuntime } from "./langfuse.js";
 import { createCapturePolicy, type EnvLike } from "./capture-policy.js";
 import { createPayloadLimits } from "./limits.js";
+import { createUsageOptions } from "./usage-options.js";
 
 export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.env as EnvLike): Config | null {
   if (existsSync(path)) {
@@ -24,6 +25,7 @@ export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.en
           host: config.host || DEFAULT_LANGFUSE_HOST,
           capturePolicy: createCapturePolicy(captureSource),
           limits: createPayloadLimits(env),
+          usage: createUsageOptions(captureSource),
         };
       }
     } catch (e) {
@@ -47,6 +49,7 @@ export function loadConfigFromEnv(env: EnvLike = process.env as EnvLike): Config
     host: env.LANGFUSE_BASE_URL || env.LANGFUSE_HOST || DEFAULT_LANGFUSE_HOST,
     capturePolicy: createCapturePolicy(env),
     limits: createPayloadLimits(env),
+    usage: createUsageOptions(env),
   };
 }
 

package/src/handlers/tool.ts

@@ -12,7 +12,7 @@ import {
   getCapturePolicy,
   getLimits,
 } from "../utils.js";
-import { applyCapturePolicy } from "../capture-policy.js";
+import { applyCapturePolicy, redactOptionsFor } from "../capture-policy.js";
 import { redactString } from "../redaction.js";
 
 export async function startToolObservation(event: Record<string, unknown>) {
@@ -87,6 +87,7 @@ export async function finishToolObservation(event: Record<string, unknown>) {
     event;
 
   try {
+    const policy = getCapturePolicy();
     const shapedOutput = shapePayload(output, { maxString: getLimits().maxToolPayload });
     const captured = applyCapturePolicy(
       {
@@ -97,7 +98,7 @@ export async function finishToolObservation(event: Record<string, unknown>) {
           isError,
         },
       },
-      getCapturePolicy(),
+      policy,
     );
     const outputBytes = estimatePayloadBytes(captured.toolOutput, getLimits().maxToolPayload);
     const durationMs = Math.max(0, Date.now() - activeTool.startedAt);
@@ -106,7 +107,9 @@ export async function finishToolObservation(event: Record<string, unknown>) {
       .update({
         output: captured.toolOutput,
         level: isError ? "ERROR" : "DEFAULT",
-        statusMessage: isError ? redactString(truncate(String(event.error ?? output), 1_000)) : undefined,
+        statusMessage: isError
+          ? redactString(truncate(String(event.error ?? output), 1_000), redactOptionsFor(policy))
+          : undefined,
         metadata: {
           ...(captured.metadata ?? {}),
           durationMs,

package/src/redaction.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { getLimits } from "./limits.js";
+import { state } from "./state.js";
 
 export const REDACTED = "[REDACTED_SECRET]";
 
@@ -8,8 +9,16 @@ export interface RedactOptions {
   maxArrayItems: number;
   maxObjectKeys: number;
   maxStringLength: number;
+  /** When false, absolute filesystem paths are emitted verbatim instead of `[PATH_HASH:...]`. */
+  redactPaths: boolean;
 }
 
+/**
+ * Fallback for callers that do not pass the resolved capture policy. Mirrors
+ * `getLimits()` by reading the session config, and defaults to redacting so a
+ * missing policy can never widen disclosure. Callers that hold a policy should
+ * pass `redactOptionsFor(policy)` instead of relying on this.
+ */
 function defaultOptions(): RedactOptions {
   const limits = getLimits();
   return {
@@ -17,6 +26,7 @@ function defaultOptions(): RedactOptions {
     maxArrayItems: limits.maxArrayItems,
     maxObjectKeys: limits.maxObjectKeys,
     maxStringLength: limits.maxString,
+    redactPaths: !(state.config?.capturePolicy?.capturePaths ?? false),
   };
 }
 
@@ -41,16 +51,20 @@ function truncate(value: string, maxStringLength: number): string {
 
 export function redactString(value: string, options: Partial<RedactOptions> = {}): string {
   const merged = { ...defaultOptions(), ...options };
-  const truncated = truncate(value, merged.maxStringLength);
-  return truncated
+  const secretsRedacted = truncate(value, merged.maxStringLength)
     .replace(PRIVATE_KEY_RE, REDACTED)
     .replace(BEARER_RE, REDACTED)
     .replace(KNOWN_TOKEN_RE, REDACTED)
-    .replace(SECRET_ASSIGNMENT_RE, (_match, key: string) => `${key}=${REDACTED}`)
-    .replace(ABSOLUTE_PATH_RE, (path: string) => {
-      const envSuffix = path.match(/([/\\]\.env(?:\.[A-Za-z0-9_-]+)?)$/)?.[1];
-      return `${hashPath(envSuffix ? path.slice(0, -envSuffix.length) : path)}${envSuffix ?? ""}`;
-    });
+    .replace(SECRET_ASSIGNMENT_RE, (_match, key: string) => `${key}=${REDACTED}`);
+
+  if (!merged.redactPaths) {
+    return secretsRedacted;
+  }
+
+  return secretsRedacted.replace(ABSOLUTE_PATH_RE, (path: string) => {
+    const envSuffix = path.match(/([/\\]\.env(?:\.[A-Za-z0-9_-]+)?)$/)?.[1];
+    return `${hashPath(envSuffix ? path.slice(0, -envSuffix.length) : path)}${envSuffix ?? ""}`;
+  });
 }
 
 function visit(value: unknown, options: RedactOptions, depth: number, seen: WeakSet<object>): unknown {

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { CapturePolicy } from "./capture-policy.js";
 import type { PayloadLimits } from "./limits.js";
+import type { UsageOptions } from "./usage-options.js";
 
 export interface Config {
   publicKey: string;
@@ -7,6 +8,7 @@ export interface Config {
   host: string;
   capturePolicy?: CapturePolicy;
   limits?: PayloadLimits;
+  usage?: UsageOptions;
 }
 
 export interface LangfuseObservation {

package/src/usage-options.ts

@@ -0,0 +1,41 @@
+import { parseFlag, type EnvLike } from "./capture-policy.js";
+import { state } from "./state.js";
+
+/**
+ * Switches that change how token usage is reported to Langfuse. Resolved once
+ * from the environment (and the persisted `capture` block, which is merged
+ * into it) when config loads; consumers read the resolved values through
+ * `getUsageOptions()`.
+ */
+export interface UsageOptions {
+  /**
+   * Report reasoning tokens as `output_reasoning_tokens` and narrow `output`
+   * to the non-reasoning remainder. Off by default because Langfuse prices
+   * usage by exact key and a custom model definition priced on `output`
+   * alone would cost the reasoning share at zero once it moved to its own key.
+   */
+  readonly splitReasoningTokens: boolean;
+}
+
+export const DEFAULT_USAGE_OPTIONS: UsageOptions = {
+  splitReasoningTokens: false,
+};
+
+/**
+ * Resolve usage options from the environment. Namespaced `PI_LANGFUSE_*` like
+ * the payload limits: this is extension behaviour, not a Langfuse server knob.
+ */
+export function createUsageOptions(env: EnvLike = process.env as EnvLike): UsageOptions {
+  return {
+    splitReasoningTokens:
+      parseFlag(env.PI_LANGFUSE_SPLIT_REASONING_TOKENS) ?? DEFAULT_USAGE_OPTIONS.splitReasoningTokens,
+  };
+}
+
+/**
+ * Resolved usage options for the current session: the config-loaded values
+ * when a config is active, otherwise a fresh resolve from the environment.
+ */
+export function getUsageOptions(): UsageOptions {
+  return state.config?.usage ?? createUsageOptions();
+}

package/src/utils.ts

@@ -1,5 +1,6 @@
 import { getLimits } from "./limits.js";
-import { createCapturePolicy, type CapturePolicy } from "./capture-policy.js";
+import { getUsageOptions, type UsageOptions } from "./usage-options.js";
+import { createCapturePolicy, redactOptionsFor, type CapturePolicy } from "./capture-policy.js";
 import { redactValue } from "./redaction.js";
 import { state } from "./state.js";
 
@@ -140,6 +141,7 @@ export function shapePayload(
   return options.redact === false
     ? shaped
     : redactValue(shaped, {
+        ...redactOptionsFor(getCapturePolicy()),
         maxDepth: depth,
         maxStringLength: maxString,
         maxArrayItems,
@@ -369,7 +371,95 @@ export function getMessageFromEvent(event: Record<string, unknown>): Record<stri
   return undefined;
 }
 
-export function extractUsage(messageOrEvent: Record<string, unknown>): Record<string, number> | undefined {
+/**
+ * Langfuse buckets usage and cost details by substring match on the key name:
+ * `input` rolls up into the Input row of the breakdown, `output` into Output,
+ * and anything matching neither falls into the catch-all Other row. Camel-cased
+ * `cacheWrite` lands in Other, so cache is reported outside the Input bucket it
+ * belongs to and never reaches Langfuse's own price table, which resolves
+ * usage types by exact key match (`price.usageType === key`) and therefore
+ * cannot price cache for providers that do not report cost themselves.
+ *
+ * These are the key names Langfuse documents for Anthropic-style caching.
+ * Pi reports `input` exclusive of cached tokens, so the buckets stay
+ * non-overlapping and nothing is double counted. Emitting both spellings would
+ * be worse than either: the canonical key would be counted in Input and the
+ * camel-cased duplicate again in Other.
+ */
+const CACHE_READ_KEY = "cache_read_input_tokens";
+const CACHE_WRITE_KEY = "cache_creation_input_tokens";
+
+/**
+ * Anthropic prices one-hour cache writes at a different rate from the default
+ * five-minute ones, and Langfuse mirrors that with two TTL-specific usage keys.
+ * Pi reports the total under `cacheWrite` and the hour-TTL share of it under
+ * `cacheWrite1h`, so the two Langfuse buckets are `cacheWrite - cacheWrite1h`
+ * and `cacheWrite1h`. Both keys contain `input`, so the Input row of the
+ * breakdown is unchanged; only the price lookup differs.
+ */
+const CACHE_WRITE_5M_KEY = "input_cache_creation_5m";
+const CACHE_WRITE_1H_KEY = "input_cache_creation_1h";
+
+/**
+ * Pi emits `cacheWrite1h: 0` on every Anthropic-family response, so a zero
+ * carries no TTL information. Only a non-zero hour-TTL figure is a real
+ * breakdown; everything else stays on the TTL-agnostic key so dashboards and
+ * custom model prices keyed on it keep working.
+ */
+function splitCacheWrite(cacheWrite: number, cacheWrite1h: number): Record<string, number> {
+  if (!cacheWrite) {
+    return {};
+  }
+
+  const longWrite = Math.min(Math.max(cacheWrite1h, 0), cacheWrite);
+  if (!longWrite) {
+    return { [CACHE_WRITE_KEY]: cacheWrite };
+  }
+
+  const shortWrite = cacheWrite - longWrite;
+  return {
+    ...(shortWrite ? { [CACHE_WRITE_5M_KEY]: shortWrite } : {}),
+    [CACHE_WRITE_1H_KEY]: longWrite,
+  };
+}
+
+/**
+ * Reasoning tokens are a subset of the completion, not a sibling of it: every
+ * provider Pi reports them for counts them inside `output`. Emitting them as an
+ * extra bucket alone would therefore inflate Output usage, so `output` is
+ * narrowed to the non-reasoning remainder first — the same conversion Langfuse
+ * applies to Gemini thought tokens in `OtelIngestionProcessor`. Both keys
+ * contain `output`, so Langfuse re-aggregates them into an unchanged Output row.
+ *
+ * Reasoning is clamped to the reported `output` so an inconsistent provider
+ * count cannot drive `output` negative or make the buckets stop summing to
+ * `total`.
+ *
+ * The split is opt-in (`PI_LANGFUSE_SPLIT_REASONING_TOKENS`). Langfuse prices
+ * usage by exact key and user-defined model prices shadow the maintained
+ * defaults, so a custom model priced on `output` alone would silently cost the
+ * reasoning share at zero the moment it moved to its own key. Off by default,
+ * `output` stays whole and reasoning is not reported, exactly as before.
+ */
+const REASONING_KEY = "output_reasoning_tokens";
+
+function splitReasoning(output: number, reasoning: number, enabled: boolean): Record<string, number> {
+  if (!enabled) {
+    return { output };
+  }
+
+  const bounded = Math.min(Math.max(reasoning, 0), output);
+  if (!bounded) {
+    return { output };
+  }
+
+  return { output: output - bounded, [REASONING_KEY]: bounded };
+}
+
+export function extractUsage(
+  messageOrEvent: Record<string, unknown>,
+  options: UsageOptions = getUsageOptions(),
+): Record<string, number> | undefined {
   const usage = (messageOrEvent.usage ??
     (messageOrEvent.message && typeof messageOrEvent.message === "object"
       ? (messageOrEvent.message as Record<string, unknown>).usage
@@ -383,13 +473,17 @@ export function extractUsage(messageOrEvent: Record<string, unknown>): Record<st
   const total = Number(usage.total ?? usage.totalTokens ?? usage.total_tokens ?? input + output);
   const cacheRead = Number(usage.cacheRead ?? usage.cache_read ?? usage.cachedTokens ?? 0);
   const cacheWrite = Number(usage.cacheWrite ?? usage.cache_write ?? 0);
+  const cacheWrite1h = Number(usage.cacheWrite1h ?? usage.cache_write_1h ?? 0);
+  const reasoning = Number(
+    usage.reasoning ?? usage.reasoningTokens ?? usage.reasoning_tokens ?? usage.thoughtsTokenCount ?? 0,
+  );
 
   return {
     input,
-    output,
+    ...splitReasoning(output, reasoning, options.splitReasoningTokens),
     total,
-    ...(cacheRead ? { cacheRead } : {}),
-    ...(cacheWrite ? { cacheWrite } : {}),
+    ...(cacheRead ? { [CACHE_READ_KEY]: cacheRead } : {}),
+    ...splitCacheWrite(cacheWrite, cacheWrite1h),
   };
 }
 
@@ -405,12 +499,23 @@ export function extractCostDetails(messageOrEvent: Record<string, unknown>): Rec
 
   const input = Number(cost.input ?? cost.inputCost ?? 0);
   const output = Number(cost.output ?? cost.outputCost ?? 0);
-  const total = Number(cost.total ?? cost.totalCost ?? input + output);
-  if (input === 0 && output === 0 && total === 0) {
+  const cacheRead = Number(cost.cacheRead ?? cost.cache_read ?? 0);
+  // Pi has no per-TTL cost figure: `cost.cacheWrite` already prices the
+  // five-minute and one-hour shares at their own rates and sums them, so the
+  // cost side stays on the aggregate key even when usage is split by TTL.
+  const cacheWrite = Number(cost.cacheWrite ?? cost.cache_write ?? 0);
+  const total = Number(cost.total ?? cost.totalCost ?? input + output + cacheRead + cacheWrite);
+  if (input === 0 && output === 0 && cacheRead === 0 && cacheWrite === 0 && total === 0) {
     return undefined;
   }
 
-  return { input, output, total };
+  return {
+    input,
+    output,
+    total,
+    ...(cacheRead ? { [CACHE_READ_KEY]: cacheRead } : {}),
+    ...(cacheWrite ? { [CACHE_WRITE_KEY]: cacheWrite } : {}),
+  };
 }
 
 export function extractResponseMetadata(event: Record<string, unknown>): Record<string, unknown> {