@narumitw/pi-langfuse 0.49.4 → 0.50.0

package/README.md

@@ -61,13 +61,14 @@ You can also create the file manually:
   "baseUrl": "https://us.cloud.langfuse.com",
   "environment": "development",
   "release": "local",
+  "userId": "your-user-id",
   "captureContent": true
 }
 ```
 
 `publicKey` and `secretKey` are required literal strings. Environment-variable and command interpolation are intentionally unsupported. `baseUrl` defaults to `https://us.cloud.langfuse.com`; regional and self-hosted HTTP or HTTPS endpoints are supported. Prefer HTTPS because HTTP sends Langfuse credentials and trace content without transport encryption.
 
-`environment` and `release` are optional Langfuse trace attributes. An environment must match Langfuse's contract: at most 40 lowercase letters, numbers, hyphens, or underscores, and it cannot start with `langfuse`. Set `captureContent` to `false` to trace timing, model, usage, cost, status, and bounded diagnostic metadata without sending prompts, provider-request snapshots, responses, or tool content.
+`environment`, `release`, and `userId` are optional Langfuse trace attributes. An environment must match Langfuse's contract: at most 40 lowercase letters, numbers, hyphens, or underscores, and it cannot start with `langfuse`. `userId` populates the Langfuse user dimension, which is what the Sessions and Traces views group by; Langfuse accepts at most 200 characters, and leaving it unset reports no user. Set `captureContent` to `false` to trace timing, model, usage, cost, status, and bounded diagnostic metadata without sending prompts, provider-request snapshots, responses, or tool content.
 
 The extension automatically restricts an existing config file to mode `0600` and refuses to load credentials if that protection cannot be enforced. You can also set it explicitly:
 
@@ -75,7 +76,7 @@ The extension automatically restricts an existing config file to mode `0600` and
 chmod 600 ~/.pi/agent/pi-langfuse.json
 ```
 
-Restart Pi after changing credentials, endpoint, environment, release, or `captureContent`. The isolated OpenTelemetry tracer provider is initialized once per Pi process and selected only for Langfuse; it does not replace Pi's process-global provider or send Langfuse observations to another extension's exporter.
+Restart Pi after changing credentials, endpoint, environment, release, or `captureContent`. Changes to `userId` apply to new sessions without restarting Pi. The isolated OpenTelemetry tracer provider is initialized once per Pi process and selected only for Langfuse; it does not replace Pi's process-global provider or send Langfuse observations to another extension's exporter.
 
 ## 🔭 What is traced
 
@@ -166,7 +167,7 @@ includes current tracing state and the manual configuration path.
 
 With content capture enabled, traces can contain user prompts, model responses, tool arguments, and tool results. These may include source code, file contents, shell output, or other sensitive project data. Review your Langfuse retention and access controls before enabling this extension.
 
-Git branch names, commit ids, working directory, session/leaf ids, model identity, usage/cost, aggregate counts, and allowlisted response-header values are metadata. They remain exported when `captureContent` is `false`; branch names and diagnostic header values can themselves contain operational details.
+Git branch names, commit ids, working directory, session/leaf ids, the configured `userId`, model identity, usage/cost, aggregate counts, and allowlisted response-header values are metadata. They remain exported when `captureContent` is `false`; branch names and diagnostic header values can themselves contain operational details, and a `userId` may itself be personally identifying if you set it to an email address or a real name. Choose a pseudonymous value when that matters, or leave `userId` unset to export no user at all.
 
 The built-in mask specifically protects Langfuse credentials; it is not a general secret scanner. Set `"captureContent": false` in `pi-langfuse.json` when prompts, provider-request snapshots, responses, and tool content must remain local. Compaction summaries, tool partial results, opaque continuation signatures, authorization headers, cookies, and unapproved response headers are never exported in either mode.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-langfuse",
-	"version": "0.49.4",
+	"version": "0.50.0",
 	"description": "Pi extension that traces LLM generations and tool activity to Langfuse.",
 	"type": "module",
 	"license": "MIT",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@langfuse/otel": "^5.10.0",
 		"@langfuse/tracing": "^5.10.0",
-		"@narumitw/pi-tui-kit": "^0.49.1",
+		"@narumitw/pi-tui-kit": "^0.55.0",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
 		"@opentelemetry/sdk-trace-base": "^2.10.0",

package/src/config.ts

@@ -12,6 +12,7 @@ export interface LangfuseConfig {
 	baseUrl: string;
 	environment?: string;
 	release?: string;
+	userId?: string;
 	captureContent: boolean;
 }
 
@@ -61,6 +62,7 @@ async function writeLangfuseConfigNow(
 		baseUrl: _baseUrl,
 		environment: _environment,
 		release: _release,
+		userId: _userId,
 		captureContent: _captureContent,
 		...unknownFields
 	} = currentDocument;
@@ -209,6 +211,11 @@ export function normalizeLangfuseConfig(
 	}
 	const release = optionalString(input.release, "release");
 	if (!release.ok) return release;
+	const userId = optionalString(input.userId, "userId");
+	if (!userId.ok) return userId;
+	if (userId.value && userId.value.length > 200) {
+		return { ok: false, reason: "pi-langfuse.json userId must be at most 200 characters." };
+	}
 
 	return {
 		ok: true,
@@ -218,6 +225,7 @@ export function normalizeLangfuseConfig(
 			baseUrl,
 			...(environment.value ? { environment: environment.value } : {}),
 			...(release.value ? { release: release.value } : {}),
+			...(userId.value ? { userId: userId.value } : {}),
 			captureContent: input.captureContent ?? true,
 		},
 	};

package/src/langfuse.ts

@@ -201,6 +201,7 @@ export function createLangfuseExtension(
 				activeConfig = result.config;
 				recorder = new TraceRecorder(backend, {
 					sessionId: ctx.sessionManager.getSessionId(),
+					...(result.config.userId ? { userId: result.config.userId } : {}),
 					cwd: ctx.cwd,
 					mode: ctx.mode,
 					captureContent: result.config.captureContent,

package/src/runtime.ts

@@ -39,14 +39,15 @@ class ProductionObservation implements Observation {
 	constructor(readonly native: LangfuseObservation) {}
 
 	update(attributes: ObservationAttributes): Observation {
-		const { sessionId, ...observationAttributes } = attributes;
+		const { sessionId, userId, ...observationAttributes } = attributes;
 		this.native.updateOtelSpanAttributes(observationAttributes as LangfuseObservationAttributes);
 		applySessionId(this.native, sessionId);
+		applyUserId(this.native, userId);
 		return this;
 	}
 
 	updateTrace(attributes: ObservationAttributes): Observation {
-		const { input, output, metadata, name, sessionId, tags, version } = attributes;
+		const { input, output, metadata, name, sessionId, userId, tags, version } = attributes;
 		if (input !== undefined || output !== undefined) {
 			this.native.setTraceIO({ input, output });
 		}
@@ -54,6 +55,7 @@ class ProductionObservation implements Observation {
 			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_NAME, name);
 		}
 		applySessionId(this.native, sessionId);
+		applyUserId(this.native, userId);
 		if (tags !== undefined) {
 			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_TAGS, tags);
 		}
@@ -86,13 +88,14 @@ class ProductionTraceBackend implements TraceBackend {
 		attributes: ObservationAttributes,
 		options: { asType: ObservationType; parent?: Observation },
 	): Observation {
-		const { sessionId, ...observationAttributes } = attributes;
+		const { sessionId, userId, ...observationAttributes } = attributes;
 		const parent = options.parent;
 		const native =
 			parent instanceof ProductionObservation
 				? startChild(parent.native, name, observationAttributes, options.asType)
 				: startRoot(name, observationAttributes, options.asType);
 		applySessionId(native, sessionId);
+		applyUserId(native, userId);
 		return new ProductionObservation(native);
 	}
 
@@ -186,6 +189,12 @@ function applySessionId(observation: LangfuseObservation, sessionId: string | un
 	}
 }
 
+function applyUserId(observation: LangfuseObservation, userId: string | undefined): void {
+	if (userId !== undefined) {
+		observation.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_USER_ID, userId);
+	}
+}
+
 function startRoot(
 	name: string,
 	attributes: ObservationAttributes,

package/src/tracing.ts

@@ -40,6 +40,7 @@ export interface ObservationAttributes {
 	version?: string;
 	name?: string;
 	sessionId?: string;
+	userId?: string;
 	tags?: string[];
 }
 
@@ -63,6 +64,7 @@ export interface TraceBackend {
 
 interface RecorderContext {
 	sessionId: string;
+	userId?: string;
 	cwd: string;
 	mode: string;
 	captureContent: boolean;
@@ -239,7 +241,12 @@ export class TraceRecorder {
 		attributes: ObservationAttributes,
 		options: { asType: ObservationType; parent?: Observation },
 	): Observation {
-		return this.backend.start(name, { ...attributes, sessionId: this.context.sessionId }, options);
+		const { sessionId, userId } = this.context;
+		return this.backend.start(
+			name,
+			{ ...attributes, sessionId, ...(userId ? { userId } : {}) },
+			options,
+		);
 	}
 
 	hasActiveTrace(): boolean {
@@ -287,6 +294,7 @@ export class TraceRecorder {
 		this.root.updateTrace?.({
 			name: "pi.trace",
 			sessionId: this.context.sessionId,
+			...(this.context.userId ? { userId: this.context.userId } : {}),
 			version: TRACE_SCHEMA_VERSION,
 			input: traceInput,
 			metadata,