@narumitw/pi-langfuse 0.28.0 → 0.35.0

package/README.md

@@ -48,7 +48,7 @@ Run the interactive manager, then choose **Set up Langfuse for this Pi agent dir
 /langfuse
 ```
 
-The setup flow prompts for the secret key, public key, and base URL in the same order Langfuse presents them. Leave either key blank to preserve its existing value when updating a valid config. Leave the base URL blank to use `https://us.cloud.langfuse.com`. The file is saved atomically with mode `0600`.
+The setup flow prompts for the secret key, public key, and base URL in the same order Langfuse presents them. Leave either key blank to preserve its existing value when updating a valid config. Leave the base URL blank to use `https://us.cloud.langfuse.com`. The first successful setup creates the file. Within one Pi process, updates run in invocation order, reread the latest valid private document, preserve unknown fields, and save atomically with mode `0600`. Malformed JSON or invalid recognized fields block setup and update writes until repaired; errors redact entered and stored credentials. A failed save leaves the current session and prior file unchanged.
 
 Configuration belongs to the displayed Pi agent directory, not just the current conversation. Restart each running Pi process after saving; the new connection applies to subsequent sessions in that process. `/reload` is not sufficient because the isolated Langfuse runtime is initialized once per process. In print or JSON mode, edit the file manually because the interactive manager is unavailable.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-langfuse",
-	"version": "0.28.0",
+	"version": "0.35.0",
 	"description": "Pi extension that traces LLM generations and tool activity to Langfuse.",
 	"type": "module",
 	"license": "MIT",
@@ -30,15 +30,15 @@
 	},
 	"dependencies": {
 		"@langfuse/otel": "^5.9.1",
-		"@langfuse/tracing": "^4.0.0",
+		"@langfuse/tracing": "^5.9.1",
 		"@opentelemetry/api": "^1.9.1",
-		"@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
-		"@opentelemetry/sdk-trace-base": "^2.9.0",
-		"@opentelemetry/sdk-trace-node": "^2.9.0"
+		"@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
+		"@opentelemetry/sdk-trace-base": "^2.10.0",
+		"@opentelemetry/sdk-trace-node": "^2.10.0"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.3",
-		"@earendil-works/pi-coding-agent": "0.80.10",
+		"@biomejs/biome": "2.5.5",
+		"@earendil-works/pi-coding-agent": "0.82.1",
 		"@types/node": "26.1.1",
 		"typescript": "7.0.2"
 	},

package/src/config.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const CONFIG_FILE_NAME = "pi-langfuse.json";
 export const DEFAULT_BASE_URL = "https://us.cloud.langfuse.com";
@@ -15,31 +15,66 @@ export interface LangfuseConfig {
 	captureContent: boolean;
 }
 
+export type LangfuseConfigPatch = Partial<LangfuseConfig>;
+
 export type LangfuseConfigResult =
 	| { ok: true; config: LangfuseConfig; path: string; warnings: string[] }
 	| { ok: false; path: string; warnings: string[]; reason: string };
 
 export function langfuseConfigPath(): string {
-	return join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), CONFIG_FILE_NAME);
+	return join(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+const configSaveQueues = new Map<string, Promise<void>>();
+
+export async function waitForLangfuseConfigWrites(path = langfuseConfigPath()): Promise<void> {
+	await configSaveQueues.get(path);
 }
 
-export async function writeLangfuseConfig(
-	config: LangfuseConfig,
+export function writeLangfuseConfig(
+	patch: LangfuseConfigPatch,
 	path = langfuseConfigPath(),
 ): Promise<LangfuseConfig> {
-	const normalized = normalizeLangfuseConfig(config);
+	const previous = configSaveQueues.get(path) ?? Promise.resolve();
+	const operation = previous.then(() => writeLangfuseConfigNow(patch, path));
+	const tail = operation.then(
+		() => undefined,
+		() => undefined,
+	);
+	configSaveQueues.set(path, tail);
+	void tail.then(() => {
+		if (configSaveQueues.get(path) === tail) configSaveQueues.delete(path);
+	});
+	return operation;
+}
+
+async function writeLangfuseConfigNow(
+	patch: LangfuseConfigPatch,
+	path: string,
+): Promise<LangfuseConfig> {
+	const currentDocument = await readLangfuseDocumentForUpdate(path);
+	const normalized = normalizeLangfuseConfig({ ...currentDocument, ...patch });
 	if (!normalized.ok) throw new Error(normalized.reason);
+	const {
+		publicKey: _publicKey,
+		secretKey: _secretKey,
+		baseUrl: _baseUrl,
+		environment: _environment,
+		release: _release,
+		captureContent: _captureContent,
+		...unknownFields
+	} = currentDocument;
+	const nextDocument = { ...unknownFields, ...normalized.config };
 
 	await mkdir(dirname(path), { recursive: true, mode: 0o700 });
 	const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
 	try {
-		await writeFile(tempPath, `${JSON.stringify(normalized.config, null, 2)}\n`, {
+		await writeFile(tempPath, `${JSON.stringify(nextDocument, null, 2)}\n`, {
 			encoding: "utf8",
 			mode: 0o600,
 		});
 		await chmod(tempPath, 0o600);
 		await rename(tempPath, path);
-		await chmod(path, 0o600);
 		return normalized.config;
 	} catch (error) {
 		await rm(tempPath, { force: true }).catch(() => undefined);
@@ -47,9 +82,29 @@ export async function writeLangfuseConfig(
 	}
 }
 
+async function readLangfuseDocumentForUpdate(path: string): Promise<Record<string, unknown>> {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return {};
+		throw new Error(
+			`Cannot update ${CONFIG_FILE_NAME} because the existing file is malformed or unreadable; repair it first.`,
+		);
+	}
+	const normalized = normalizeLangfuseConfig(parsed);
+	if (!normalized.ok) {
+		throw new Error(
+			`Cannot update ${CONFIG_FILE_NAME} because the existing file has invalid recognized fields; repair it first.`,
+		);
+	}
+	return { ...(parsed as Record<string, unknown>) };
+}
+
 export async function loadLangfuseConfig(
 	path = langfuseConfigPath(),
 ): Promise<LangfuseConfigResult> {
+	await configSaveQueues.get(path);
 	const warnings: string[] = [];
 	const permissionFailure = await ensurePrivatePermissions(path, warnings);
 	if (permissionFailure) {
@@ -61,9 +116,9 @@ export async function loadLangfuseConfig(
 		};
 	}
 
-	let parsed: unknown;
+	let text: string;
 	try {
-		parsed = JSON.parse(await readFile(path, "utf8"));
+		text = await readFile(path, "utf8");
 	} catch (error) {
 		if (isNodeError(error) && error.code === "ENOENT") {
 			return { ok: false, path, warnings, reason: `Configuration file not found: ${path}` };
@@ -76,6 +131,18 @@ export async function loadLangfuseConfig(
 		};
 	}
 
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text) as unknown;
+	} catch {
+		return {
+			ok: false,
+			path,
+			warnings,
+			reason: `Failed to parse ${path} as JSON; repair the file before retrying.`,
+		};
+	}
+
 	const normalized = normalizeLangfuseConfig(parsed);
 	if (!normalized.ok) return { ok: false, path, warnings, reason: normalized.reason };
 	return { ok: true, config: normalized.config, path, warnings };

package/src/langfuse.ts

@@ -6,6 +6,7 @@ import type {
 import {
 	DEFAULT_BASE_URL,
 	type LangfuseConfig,
+	type LangfuseConfigPatch,
 	type LangfuseConfigResult,
 	loadLangfuseConfig,
 	normalizeLangfuseConfig,
@@ -20,7 +21,7 @@ import {
 
 interface ExtensionDependencies {
 	loadConfig(path?: string): Promise<LangfuseConfigResult>;
-	writeConfig(config: LangfuseConfig, path?: string): Promise<LangfuseConfig>;
+	writeConfig(config: LangfuseConfigPatch, path?: string): Promise<unknown>;
 	createBackend(config: LangfuseConfig): Promise<TraceBackend>;
 	resolveGitMetadata(cwd: string): Promise<GitMetadata | undefined>;
 }
@@ -54,6 +55,7 @@ export function createLangfuseExtension(
 		let hasStoredConfig = false;
 		let configurationNotice: string | undefined;
 		let sessionGeneration = 0;
+		let configWriteQueue = Promise.resolve();
 		let nextAttemptReason: string | undefined;
 
 		pi.registerCommand("langfuse", {
@@ -100,10 +102,19 @@ export function createLangfuseExtension(
 					const loaded = await loadConfig(configPath);
 					if (menuGeneration !== sessionGeneration) return;
 					configPath = loaded.path;
-					const next = await promptForConfig(ctx, loaded.ok ? loaded.config : undefined);
+					const next = await promptForConfig(
+						ctx,
+						loaded.ok ? loaded.config : undefined,
+						() => menuGeneration === sessionGeneration,
+					);
 					if (!next || menuGeneration !== sessionGeneration) return;
 					try {
-						await writeConfig(next, loaded.path);
+						const write = configWriteQueue.then(() => writeConfig(next, loaded.path));
+						configWriteQueue = write.then(
+							() => undefined,
+							() => undefined,
+						);
+						await write;
 						if (menuGeneration !== sessionGeneration) return;
 						hasStoredConfig = true;
 						configurationNotice =
@@ -126,7 +137,7 @@ export function createLangfuseExtension(
 		});
 
 		pi.on("session_start", async (_event, ctx) => {
-			sessionGeneration += 1;
+			const generation = ++sessionGeneration;
 			recorder = undefined;
 			activeConfig = undefined;
 			configPath = undefined;
@@ -135,7 +146,10 @@ export function createLangfuseExtension(
 			configurationNotice = undefined;
 			nextAttemptReason = undefined;
 
+			await configWriteQueue;
+			if (generation !== sessionGeneration) return;
 			const result = await loadConfig();
+			if (generation !== sessionGeneration) return;
 			configPath = result.path;
 			for (const warning of result.warnings) ctx.ui.notify(warning, "warning");
 			if (!result.ok) {
@@ -147,6 +161,10 @@ export function createLangfuseExtension(
 			hasStoredConfig = true;
 			try {
 				const backend = await createBackend(result.config);
+				if (generation !== sessionGeneration) {
+					await backend.shutdown().catch(() => undefined);
+					return;
+				}
 				activeConfig = result.config;
 				recorder = new TraceRecorder(backend, {
 					sessionId: ctx.sessionManager.getSessionId(),
@@ -155,6 +173,7 @@ export function createLangfuseExtension(
 					captureContent: result.config.captureContent,
 				});
 			} catch (error) {
+				if (generation !== sessionGeneration) return;
 				initializationError = `Langfuse tracing could not start: ${formatError(error, result.config)}`;
 				ctx.ui.notify(initializationError, "warning");
 			}
@@ -280,23 +299,26 @@ export function createLangfuseExtension(
 		});
 
 		pi.on("session_shutdown", async (event, ctx) => {
-			sessionGeneration += 1;
+			const generation = ++sessionGeneration;
 			const activeRecorder = recorder;
 			const shutdownConfig = activeConfig;
+			const pendingConfigWrite = configWriteQueue;
+			const shutdownSnapshot = activeRecorder ? contextSnapshot(ctx) : undefined;
 			recorder = undefined;
 			activeConfig = undefined;
+			await pendingConfigWrite;
 			if (!activeRecorder) return;
 			try {
-				const snapshot = contextSnapshot(ctx);
-				if (event.reason === "quit") await activeRecorder.shutdown(snapshot);
+				if (event.reason === "quit") await activeRecorder.shutdown(shutdownSnapshot);
 				else {
 					activeRecorder.interrupt(
 						`Pi session ended before settlement (${event.reason}).`,
-						snapshot,
+						shutdownSnapshot,
 					);
 					await activeRecorder.flush();
 				}
 			} catch (error) {
+				if (generation !== sessionGeneration) return;
 				ctx.ui.notify(
 					`Langfuse shutdown export failed: ${formatError(error, shutdownConfig)}`,
 					"error",
@@ -417,13 +439,16 @@ function normalizeGitBranch(value: string): string | undefined {
 async function promptForConfig(
 	ctx: ExtensionCommandContext,
 	current: LangfuseConfig | undefined,
-): Promise<LangfuseConfig | undefined> {
+	isCurrent: () => boolean,
+): Promise<LangfuseConfigPatch | undefined> {
 	const secretKey = await ctx.ui.input("Langfuse secret key (leave blank to keep existing):");
+	if (!isCurrent()) return undefined;
 	if (secretKey === undefined) {
 		ctx.ui.notify("Cancelled", "info");
 		return undefined;
 	}
 	const publicKey = await ctx.ui.input("Langfuse public key (leave blank to keep existing):");
+	if (!isCurrent()) return undefined;
 	if (publicKey === undefined) {
 		ctx.ui.notify("Cancelled", "info");
 		return undefined;
@@ -432,23 +457,23 @@ async function promptForConfig(
 		`Langfuse base URL (leave blank for default ${DEFAULT_BASE_URL}):`,
 		DEFAULT_BASE_URL,
 	);
+	if (!isCurrent()) return undefined;
 	if (baseUrl === undefined) {
 		ctx.ui.notify("Cancelled", "info");
 		return undefined;
 	}
 
-	const normalized = normalizeLangfuseConfig({
-		...current,
-		publicKey: publicKey.trim() || current?.publicKey || "",
-		secretKey: secretKey.trim() || current?.secretKey || "",
+	const patch: LangfuseConfigPatch = {
+		...(publicKey.trim() ? { publicKey: publicKey.trim() } : {}),
+		...(secretKey.trim() ? { secretKey: secretKey.trim() } : {}),
 		baseUrl: baseUrl.trim() || DEFAULT_BASE_URL,
-		captureContent: current?.captureContent ?? true,
-	});
+	};
+	const normalized = normalizeLangfuseConfig({ ...current, ...patch });
 	if (!normalized.ok) {
 		ctx.ui.notify(`Invalid Langfuse config: ${normalized.reason}`, "error");
 		return undefined;
 	}
-	return normalized.config;
+	return patch;
 }
 
 function formatMenuTitle(
@@ -524,7 +549,7 @@ function formatConfigError(result: Extract<LangfuseConfigResult, { ok: false }>)
 	return `Langfuse tracing is disabled: ${result.reason}${setupHint}`;
 }
 
-function formatError(error: unknown, config?: LangfuseConfig): string {
+function formatError(error: unknown, config?: LangfuseConfigPatch): string {
 	let message = error instanceof Error ? error.message : String(error);
 	const secrets = [config?.publicKey, config?.secretKey]
 		.filter((secret): secret is string => Boolean(secret))

package/src/runtime.ts

@@ -3,7 +3,7 @@ import { LangfuseSpanProcessor } from "@langfuse/otel";
 import {
 	type LangfuseObservation,
 	type LangfuseObservationAttributes,
-	type LangfuseTraceAttributes,
+	LangfuseOtelSpanAttributes,
 	setLangfuseTracerProvider,
 	startObservation,
 } from "@langfuse/tracing";
@@ -44,7 +44,28 @@ class ProductionObservation implements Observation {
 	}
 
 	updateTrace(attributes: ObservationAttributes): Observation {
-		this.native.updateTrace(attributes as LangfuseTraceAttributes);
+		const { input, output, metadata, name, sessionId, 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);
+		}
+		if (tags !== undefined) {
+			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.TRACE_TAGS, tags);
+		}
+		if (version !== undefined) {
+			this.native.otelSpan.setAttribute(LangfuseOtelSpanAttributes.VERSION, version);
+		}
+		for (const [key, value] of Object.entries(metadata ?? {})) {
+			this.native.otelSpan.setAttribute(
+				`${LangfuseOtelSpanAttributes.TRACE_METADATA}.${key}`,
+				String(value),
+			);
+		}
 		return this;
 	}
 
@@ -67,9 +88,7 @@ class ProductionTraceBackend implements TraceBackend {
 	): Observation {
 		const parent = options.parent;
 		if (parent instanceof ProductionObservation) {
-			return new ProductionObservation(
-				startChild(parent.native, name, attributes, options.asType),
-			);
+			return new ProductionObservation(startChild(parent.native, name, attributes, options.asType));
 		}
 		return new ProductionObservation(startRoot(name, attributes, options.asType));
 	}
@@ -236,10 +255,7 @@ function maskSecretValue(
 			return data.map((item) => maskSecretValue(item, secrets, active));
 		}
 		return Object.fromEntries(
-			Object.entries(data).map(([key, value]) => [
-				key,
-				maskSecretValue(value, secrets, active),
-			]),
+			Object.entries(data).map(([key, value]) => [key, maskSecretValue(value, secrets, active)]),
 		);
 	} finally {
 		active.delete(data);

package/src/tracing.ts

@@ -243,8 +243,7 @@ export class TraceRecorder {
 	}
 
 	beginAgent(input: BeginAgentInput): void {
-		if (this.root)
-			this.closeActiveTrace("Interrupted by a new Pi run.", undefined, "interrupted");
+		if (this.root) this.closeActiveTrace("Interrupted by a new Pi run.", undefined, "interrupted");
 
 		this.lastOutput = undefined;
 		this.lastAssistant = undefined;