@narumitw/pi-langfuse 0.49.3 → 0.50.0

package/README.md

@@ -35,7 +35,7 @@ pi -e npm:@narumitw/pi-langfuse
 Try a local checkout:
 
 ```bash
-pi -e ./extensions/pi-langfuse
+pi -e ./packages/pi-langfuse
 ```
 
 The Langfuse v4 SDK requires Node.js 20 or newer.
@@ -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,14 +167,14 @@ 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 layout
 
 ```txt
-extensions/pi-langfuse/
+packages/pi-langfuse/
 ├── src/
 │   ├── index.ts     # Pi package entrypoint
 │   ├── langfuse.ts  # Pi lifecycle integration and slash command

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-langfuse",
-	"version": "0.49.3",
+	"version": "0.50.0",
 	"description": "Pi extension that traces LLM generations and tool activity to Langfuse.",
 	"type": "module",
 	"license": "MIT",
@@ -23,6 +23,9 @@
 			"./src/index.ts"
 		]
 	},
+	"piExtension": {
+		"lifecycle": "stable"
+	},
 	"scripts": {
 		"check": "biome check . && npm run typecheck",
 		"format": "biome check --write .",
@@ -32,15 +35,15 @@
 		"@earendil-works/pi-coding-agent": "*"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.7",
-		"@earendil-works/pi-coding-agent": "0.83.0",
-		"@types/node": "26.1.2",
+		"@biomejs/biome": "2.5.8",
+		"@earendil-works/pi-coding-agent": "0.84.2",
+		"@types/node": "26.2.0",
 		"typescript": "7.0.2"
 	},
 	"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",
@@ -49,6 +52,6 @@
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "extensions/pi-langfuse"
+		"directory": "packages/pi-langfuse"
 	}
 }

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,21 +39,23 @@ class ProductionObservation implements Observation {
 	constructor(readonly native: LangfuseObservation) {}
 
 	update(attributes: ObservationAttributes): Observation {
-		this.native.updateOtelSpanAttributes(attributes as LangfuseObservationAttributes);
+		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 });
 		}
 		if (name !== undefined) {
 			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_NAME, name);
 		}
-		if (sessionId !== undefined) {
-			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_SESSION_ID, sessionId);
-		}
+		applySessionId(this.native, sessionId);
+		applyUserId(this.native, userId);
 		if (tags !== undefined) {
 			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_TAGS, tags);
 		}
@@ -86,11 +88,15 @@ class ProductionTraceBackend implements TraceBackend {
 		attributes: ObservationAttributes,
 		options: { asType: ObservationType; parent?: Observation },
 	): Observation {
+		const { sessionId, userId, ...observationAttributes } = attributes;
 		const parent = options.parent;
-		if (parent instanceof ProductionObservation) {
-			return new ProductionObservation(startChild(parent.native, name, attributes, options.asType));
-		}
-		return new ProductionObservation(startRoot(name, attributes, options.asType));
+		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);
 	}
 
 	async forceFlush(): Promise<void> {
@@ -177,6 +183,18 @@ const defaultFactories: RuntimeFactories = {
 	selectProvider: setLangfuseTracerProvider,
 };
 
+function applySessionId(observation: LangfuseObservation, sessionId: string | undefined): void {
+	if (sessionId !== undefined) {
+		observation.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_SESSION_ID, sessionId);
+	}
+}
+
+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;
@@ -234,6 +236,19 @@ export class TraceRecorder {
 		private readonly context: RecorderContext,
 	) {}
 
+	private startObservation(
+		name: string,
+		attributes: ObservationAttributes,
+		options: { asType: ObservationType; parent?: Observation },
+	): Observation {
+		const { sessionId, userId } = this.context;
+		return this.backend.start(
+			name,
+			{ ...attributes, sessionId, ...(userId ? { userId } : {}) },
+			options,
+		);
+	}
+
 	hasActiveTrace(): boolean {
 		return this.root !== undefined;
 	}
@@ -275,10 +290,11 @@ export class TraceRecorder {
 				? "git:detached"
 				: undefined;
 
-		this.root = this.backend.start("pi.agent", attributes, { asType: "agent" });
+		this.root = this.startObservation("pi.agent", attributes, { asType: "agent" });
 		this.root.updateTrace?.({
 			name: "pi.trace",
 			sessionId: this.context.sessionId,
+			...(this.context.userId ? { userId: this.context.userId } : {}),
 			version: TRACE_SCHEMA_VERSION,
 			input: traceInput,
 			metadata,
@@ -296,7 +312,7 @@ export class TraceRecorder {
 		this.lastAssistant = undefined;
 		this.unresolvedToolErrors = 0;
 		this.attemptIndex = index;
-		this.attempt = this.backend.start(
+		this.attempt = this.startObservation(
 			"pi.attempt",
 			{
 				metadata: {
@@ -325,7 +341,7 @@ export class TraceRecorder {
 		if (this.turn) this.closeTurn("Interrupted by the next Pi turn.", "ERROR");
 		this.counters.turns += 1;
 		this.turnIndex = turnIndex;
-		this.turn = this.backend.start(
+		this.turn = this.startObservation(
 			"pi.turn",
 			{ metadata: { "pi.turn.index": turnIndex }, version: TRACE_SCHEMA_VERSION },
 			{ asType: "span", parent: this.attempt ?? this.root },
@@ -372,7 +388,7 @@ export class TraceRecorder {
 			...(input.model?.api ? { "pi.request.api": input.model.api } : {}),
 			...(input.thinkingLevel ? { "pi.request.thinking_level": input.thinkingLevel } : {}),
 		};
-		const observation = this.backend.start(
+		const observation = this.startObservation(
 			"pi.llm",
 			{
 				...(input.payload !== undefined ? { input: this.capture(input.payload) } : {}),
@@ -559,7 +575,7 @@ export class TraceRecorder {
 		this.closeCompaction("Interrupted by another Pi compaction.");
 		this.counters.compactions += 1;
 		this.compaction = {
-			observation: this.backend.start(
+			observation: this.startObservation(
 				"pi.compaction",
 				{
 					metadata: {
@@ -711,7 +727,7 @@ export class TraceRecorder {
 	}
 
 	private startToolObservation(toolCallId: string, toolName: string, args?: unknown): Observation {
-		return this.backend.start(
+		return this.startObservation(
 			`pi.tool.${toolName}`,
 			{
 				...(args !== undefined ? { input: this.capture(args) } : {}),