pi-langfuse 1.5.17 → 1.5.18

package/README.md

@@ -175,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`:
@@ -230,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

@@ -167,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`：
@@ -222,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.17",
+	"version": "1.5.18",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",

package/src/capture-policy.ts

@@ -90,7 +90,12 @@ const FLAG_TO_FIELD = {
   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;
   }

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/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,4 +1,5 @@
 import { getLimits } from "./limits.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";
@@ -422,7 +423,43 @@ function splitCacheWrite(cacheWrite: number, cacheWrite1h: number): Record<strin
   };
 }
 
-export function extractUsage(messageOrEvent: Record<string, unknown>): Record<string, number> | undefined {
+/**
+ * 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
@@ -437,10 +474,13 @@ export function extractUsage(messageOrEvent: Record<string, unknown>): Record<st
   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 ? { [CACHE_READ_KEY]: cacheRead } : {}),
     ...splitCacheWrite(cacheWrite, cacheWrite1h),