pi-langfuse 1.6.0 → 1.6.1

package/README.md

@@ -34,6 +34,7 @@ Langfuse observability extension for [Pi Coding Agent](https://github.com/earend
    - Langfuse public key, starting with `pk-lf-...`
    - Langfuse secret key, starting with `sk-lf-...`
    - Langfuse host, defaulting to `https://cloud.langfuse.com`
+   - Optional Langfuse user ID for per-user usage and cost aggregation
 
 3. Run Pi normally:
 
@@ -63,7 +64,7 @@ To inspect the active configuration without exposing secrets:
 /langfuse-status
 ```
 
-The status command reports the config source, host, masked public key, capture policy, active-run state, config path, and last runtime error.
+The status command reports the config source, host, masked public key, whether a user ID is configured, capture policy, active-run state, config path, and last runtime error. It never prints the user ID itself.
 
 ### Method 2: Environment variables
 
@@ -73,9 +74,11 @@ Set these before starting Pi:
 export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
 export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
 export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # optional; LANGFUSE_HOST is also supported
+export LANGFUSE_USER_ID="user-123"                     # optional; max 200 characters
 ```
 
 Saved config takes precedence. Environment variables are only used when `~/.pi/agent/pi-langfuse/config.json` is missing or incomplete.
+If saved credentials exist but `userId` is absent, `LANGFUSE_USER_ID` is still used. An explicitly saved `userId` takes precedence.
 
 For short-lived SDK hosts, set the bounded final score-delivery attempt during shutdown:
 
@@ -222,10 +225,13 @@ Create or update `~/.pi/agent/pi-langfuse/config.json`:
   "publicKey": "pk-lf-xxxx",
   "secretKey": "sk-lf-xxxx",
   "host": "https://cloud.langfuse.com",
+  "userId": "user-123",
   "privacyPreset": "conversations"
 }
 ```
 
+`userId` is optional, explicit-only, and limited to 200 characters. The extension does not infer it from the local operating-system account. When configured, it is propagated to every observation in the trace so Langfuse can provide per-user filtering and cost aggregation.
+
 Fine-grained capture flags can also be persisted:
 
 ```json

package/README_CN.md

@@ -34,6 +34,7 @@
    - Langfuse 公钥，以 `pk-lf-...` 开头
    - Langfuse 密钥，以 `sk-lf-...` 开头
    - Langfuse 主机地址，默认 `https://cloud.langfuse.com`
+   - 可选的 Langfuse 用户 ID，用于按用户汇总用量和成本
 
 3. 正常运行 Pi：
 
@@ -63,7 +64,7 @@ Langfuse API 密钥可在 **Langfuse Cloud** -> **Settings** -> **API Keys** 中
 /langfuse-status
 ```
 
-状态命令会显示配置来源、主机地址、脱敏后的公钥、采集策略、是否有活跃运行、配置文件路径，以及最近一次运行时错误。
+状态命令会显示配置来源、主机地址、脱敏后的公钥、是否已配置用户 ID、采集策略、是否有活跃运行、配置文件路径，以及最近一次运行时错误，但不会输出用户 ID 本身。
 
 ### 方式 2：环境变量
 
@@ -73,9 +74,11 @@ Langfuse API 密钥可在 **Langfuse Cloud** -> **Settings** -> **API Keys** 中
 export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
 export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
 export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # 可选；也支持 LANGFUSE_HOST
+export LANGFUSE_USER_ID="user-123"                     # 可选；最长 200 个字符
 ```
 
 保存的配置优先级更高。只有当 `~/.pi/agent/pi-langfuse/config.json` 缺失或不完整时，扩展才会使用环境变量。
+如果已保存凭据但没有 `userId`，仍会读取 `LANGFUSE_USER_ID`；显式保存的 `userId` 优先级更高。
 
 对于短生命周期的 SDK 宿主，可设置关闭时最终分数发送尝试的上限：
 
@@ -203,10 +206,13 @@ export PI_LANGFUSE_SPLIT_REASONING_TOKENS=true
   "publicKey": "pk-lf-xxxx",
   "secretKey": "sk-lf-xxxx",
   "host": "https://cloud.langfuse.com",
+  "userId": "user-123",
   "privacyPreset": "conversations"
 }
 ```
 
+`userId` 是可选的显式配置，最长 200 个字符。扩展不会从本机操作系统账户推断该值。配置后，它会传播到 trace 中的每个 observation，以支持 Langfuse 按用户筛选并汇总成本。
+
 也可以持久化细粒度采集开关：
 
 ```json

package/package.json

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

package/src/commands.ts

@@ -211,6 +211,7 @@ function formatStatus(configPath: string, env: Record<string, string | undefined
     `Source: ${configSource(env, configPath)}`,
     `Host: ${safeConfig?.host ?? config.host}`,
     `Public key: ${safeConfig?.publicKey ?? "[REDACTED_SECRET]"}`,
+    `User ID: ${config.userId ? "configured" : "not set"}`,
     `Config file: ${configPath}`,
     `Privacy preset: ${inferPreset(policy)}`,
     "Capture:",

package/src/config.ts

@@ -8,6 +8,16 @@ import { createCapturePolicy, type EnvLike } from "./capture-policy.js";
 import { createPayloadLimits } from "./limits.js";
 import { createUsageOptions } from "./usage-options.js";
 
+const MAX_LANGFUSE_USER_ID_LENGTH = 200;
+
+function normalizeUserId(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, MAX_LANGFUSE_USER_ID_LENGTH) : undefined;
+}
+
 export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.env as EnvLike): Config | null {
   if (existsSync(path)) {
     try {
@@ -23,6 +33,7 @@ export function loadConfigFromFile(path = CONFIG_PATH, env: EnvLike = process.en
           publicKey: config.publicKey,
           secretKey: config.secretKey,
           host: config.host || DEFAULT_LANGFUSE_HOST,
+          userId: normalizeUserId(config.userId) ?? normalizeUserId(env.LANGFUSE_USER_ID),
           capturePolicy: createCapturePolicy(captureSource),
           limits: createPayloadLimits(env),
           usage: createUsageOptions(captureSource),
@@ -47,6 +58,7 @@ export function loadConfigFromEnv(env: EnvLike = process.env as EnvLike): Config
     publicKey,
     secretKey,
     host: env.LANGFUSE_BASE_URL || env.LANGFUSE_HOST || DEFAULT_LANGFUSE_HOST,
+    userId: normalizeUserId(env.LANGFUSE_USER_ID),
     capturePolicy: createCapturePolicy(env),
     limits: createPayloadLimits(env),
     usage: createUsageOptions(env),
@@ -108,10 +120,12 @@ async function collectConfigFromUI(ctx: any, reason: string): Promise<Config | n
   }
 
   const hostInput = (await ctx.ui.input("Langfuse host:", DEFAULT_LANGFUSE_HOST))?.trim();
+  const userId = normalizeUserId(await ctx.ui.input("Langfuse user ID (optional):", ""));
   return {
     publicKey,
     secretKey,
     host: hostInput || DEFAULT_LANGFUSE_HOST,
+    ...(userId ? { userId } : {}),
     capturePolicy: createCapturePolicy(),
   };
 }

package/src/handlers/agent.ts

@@ -96,6 +96,7 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
     const root = rt.propagateAttributes(
       {
         sessionId: state.currentSessionId ? truncate(state.currentSessionId, 200) : undefined,
+        userId: state.config?.userId,
         traceName: "pi-agent",
         metadata: stringMetadata(captured.metadata),
       },

package/src/langfuse.ts

@@ -29,6 +29,7 @@ interface RestFallbackTrace {
   input?: unknown;
   output?: unknown;
   sessionId?: string;
+  userId?: string;
   metadata?: Record<string, unknown>;
 }
 
@@ -558,12 +559,15 @@ function wrapObservation(
   store.observationById.set(id, record);
 
   if (!parentObservationId && !store.trace) {
+    const propagated = readPropagatedAttributes(observation);
     store.trace = {
       id: traceId,
       timestamp: record.startTime,
       name,
       input: body?.input,
-      sessionId: typeof metadata?.sessionId === "string" ? metadata.sessionId : state.currentSessionId || undefined,
+      sessionId: propagated.sessionId
+        ?? (typeof metadata?.sessionId === "string" ? metadata.sessionId : state.currentSessionId || undefined),
+      userId: propagated.userId ?? state.config?.userId,
       metadata,
     };
   }
@@ -743,6 +747,7 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal)
         input: trace.input,
         output: trace.output,
         sessionId: trace.sessionId,
+        userId: trace.userId,
         metadata: trace.metadata,
       },
     },

package/src/types.ts

@@ -6,6 +6,7 @@ export interface Config {
   publicKey: string;
   secretKey: string;
   host: string;
+  userId?: string;
   capturePolicy?: CapturePolicy;
   limits?: PayloadLimits;
   usage?: UsageOptions;