@narumitw/pi-langfuse 0.31.0 → 0.38.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.
 
@@ -144,7 +144,11 @@ Completed observations are exported in batches while Pi remains live. Neither `a
 /langfuse
 ```
 
-The command opens one context-aware menu. Its title shows the current session's tracing state, endpoint, content-capture mode, initialization failure when applicable, and private configuration path. It never displays credentials.
+The command opens one context-aware standard menu in TUI or RPC mode. Its state lines show the
+current session's tracing state, endpoint, content-capture mode, initialization failure when
+applicable, and private configuration path. It never displays credentials. Escape closes the menu.
+Credential and endpoint text inputs remain extension-owned because they enforce secret-preserving
+setup/update semantics rather than standard navigation.
 
 Available actions depend on that state:
 
@@ -153,7 +157,10 @@ Available actions depend on that state:
 - **Update Langfuse for this Pi agent directory** appears when a valid config exists.
 - **Show setup and privacy help** explains the agent-directory scope, manual configuration path, and content-capture risk.
 
-Connection actions state their agent-directory scope and per-process restart requirement before selection. Command arguments are intentionally ignored so remembered subcommands cannot silently bypass the menu. In non-interactive modes, the command reports that the menu is unavailable and points to the manual config path.
+Connection actions state their agent-directory scope and per-process restart requirement before
+selection. Command arguments are intentionally ignored so remembered subcommands cannot silently
+bypass the menu. Print and JSON modes reject the interactive command with an observable error that
+includes current tracing state and the manual configuration path.
 
 ## 🔐 Privacy
 

package/package.json

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

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

@@ -3,9 +3,11 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 import {
 	DEFAULT_BASE_URL,
 	type LangfuseConfig,
+	type LangfuseConfigPatch,
 	type LangfuseConfigResult,
 	loadLangfuseConfig,
 	normalizeLangfuseConfig,
@@ -20,7 +22,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,79 +56,118 @@ export function createLangfuseExtension(
 		let hasStoredConfig = false;
 		let configurationNotice: string | undefined;
 		let sessionGeneration = 0;
+		let menuController = new AbortController();
+		let configWriteQueue = Promise.resolve();
 		let nextAttemptReason: string | undefined;
 
-		pi.registerCommand("langfuse", {
-			description: "Open interactive Langfuse tracing controls",
-			handler: async (_args, ctx) => {
-				if (!ctx.hasUI) {
-					ctx.ui.notify(
-						formatNonInteractiveStatus(activeConfig, configPath, initializationError),
-						"warning",
-					);
-					return;
-				}
-
-				const menuGeneration = sessionGeneration;
-				const menuRecorder = recorder;
-				const menuConfig = activeConfig;
-				const choice = await ctx.ui.select(
-					formatMenuTitle(activeConfig, configPath, initializationError, configurationNotice),
-					[
-						...(menuRecorder ? [FLUSH_ACTION] : []),
-						hasStoredConfig ? UPDATE_ACTION : SET_UP_ACTION,
-						HELP_ACTION,
-					],
+		async function showLangfuseMenu(ctx: ExtensionCommandContext) {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(
+					formatNonInteractiveStatus(activeConfig, configPath, initializationError),
+					"warning",
 				);
-				if (!choice || menuGeneration !== sessionGeneration) return;
-
-				if (choice === FLUSH_ACTION) {
-					if (!menuRecorder) {
-						ctx.ui.notify("Langfuse tracing is not enabled for this session.", "warning");
-						return;
-					}
-					try {
-						await menuRecorder.flush();
-						if (menuGeneration !== sessionGeneration) return;
-						ctx.ui.notify("Langfuse traces flushed for this session.", "info");
-					} catch (error) {
-						if (menuGeneration !== sessionGeneration) return;
-						ctx.ui.notify(`Langfuse flush failed: ${formatError(error, menuConfig)}`, "error");
-					}
-					return;
-				}
-
-				if (choice === SET_UP_ACTION || choice === UPDATE_ACTION) {
-					const loaded = await loadConfig(configPath);
-					if (menuGeneration !== sessionGeneration) return;
-					configPath = loaded.path;
-					const next = await promptForConfig(ctx, loaded.ok ? loaded.config : undefined);
-					if (!next || menuGeneration !== sessionGeneration) return;
-					try {
-						await writeConfig(next, loaded.path);
-						if (menuGeneration !== sessionGeneration) return;
-						hasStoredConfig = true;
-						configurationNotice =
-							"Saved; restart each Pi process to use it in subsequent sessions.";
-						ctx.ui.notify(
-							`Saved Langfuse config to ${loaded.path} for this Pi agent directory. Restart each Pi process to apply it to subsequent sessions.`,
-							"info",
+				return;
+			}
+			const menuGeneration = sessionGeneration;
+			type Screen = "main";
+			type Action = "flush" | "configure" | "help";
+			const menu = defineMenu<undefined, Screen, Action>({
+				start: "main",
+				screens: {
+					main: () => ({
+						kind: "actions",
+						title: "Langfuse",
+						lines: formatMenuTitle(
+							activeConfig,
+							configPath,
+							initializationError,
+							configurationNotice,
+						)
+							.split("\n")
+							.slice(1),
+						items: [
+							...(recorder ? [{ id: "flush", label: FLUSH_ACTION, action: "flush" as const }] : []),
+							{
+								id: "configure",
+								label: hasStoredConfig ? UPDATE_ACTION : SET_UP_ACTION,
+								action: "configure",
+							},
+							{ id: "help", label: HELP_ACTION, action: "help" },
+						],
+						hint: "close",
+					}),
+				},
+				actions: {
+					flush: async () => {
+						const menuRecorder = recorder;
+						const menuConfig = activeConfig;
+						if (!menuRecorder) {
+							ctx.ui.notify("Langfuse tracing is not enabled for this session.", "warning");
+							return { kind: "close" };
+						}
+						try {
+							await menuRecorder.flush();
+							if (menuGeneration !== sessionGeneration) return { kind: "close" };
+							ctx.ui.notify("Langfuse traces flushed for this session.", "info");
+						} catch (error) {
+							if (menuGeneration !== sessionGeneration) return { kind: "close" };
+							ctx.ui.notify(`Langfuse flush failed: ${formatError(error, menuConfig)}`, "error");
+						}
+						return { kind: "close" };
+					},
+					configure: async () => {
+						const loaded = await loadConfig(configPath);
+						if (menuGeneration !== sessionGeneration) return { kind: "close" };
+						configPath = loaded.path;
+						const next = await promptForConfig(
+							ctx,
+							loaded.ok ? loaded.config : undefined,
+							() => menuGeneration === sessionGeneration,
 						);
-					} catch (error) {
-						if (menuGeneration !== sessionGeneration) return;
-						ctx.ui.notify(`Failed to save Langfuse config: ${formatError(error, next)}`, "error");
-					}
-					return;
-				}
+						if (!next || menuGeneration !== sessionGeneration) return { kind: "close" };
+						try {
+							const write = configWriteQueue.then(() => writeConfig(next, loaded.path));
+							configWriteQueue = write.then(
+								() => undefined,
+								() => undefined,
+							);
+							await write;
+							if (menuGeneration !== sessionGeneration) return { kind: "close" };
+							hasStoredConfig = true;
+							configurationNotice =
+								"Saved; restart each Pi process to use it in subsequent sessions.";
+							ctx.ui.notify(
+								`Saved Langfuse config to ${loaded.path} for this Pi agent directory. Restart each Pi process to apply it to subsequent sessions.`,
+								"info",
+							);
+						} catch (error) {
+							if (menuGeneration !== sessionGeneration) return { kind: "close" };
+							ctx.ui.notify(`Failed to save Langfuse config: ${formatError(error, next)}`, "error");
+						}
+						return { kind: "close" };
+					},
+					help: async () => {
+						ctx.ui.notify(formatHelp(configPath), "info");
+						return { kind: "close" };
+					},
+				},
+			});
+			await runMenu(ctx, menu, {
+				getState: () => undefined,
+				signal: menuController.signal,
+				isCurrent: () => menuGeneration === sessionGeneration,
+			});
+		}
 
-				if (choice === HELP_ACTION) {
-					ctx.ui.notify(formatHelp(configPath), "info");
-				}
-			},
+		pi.registerCommand("langfuse", {
+			description: "Open interactive Langfuse tracing controls",
+			handler: async (_args, ctx) => showLangfuseMenu(ctx),
 		});
 
 		pi.on("session_start", async (_event, ctx) => {
-			sessionGeneration += 1;
+			const generation = ++sessionGeneration;
+			menuController.abort(new DOMException("Langfuse session replaced", "AbortError"));
+			menuController = new AbortController();
 			recorder = undefined;
 			activeConfig = undefined;
 			configPath = undefined;
@@ -135,7 +176,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 +191,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 +203,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 +329,27 @@ export function createLangfuseExtension(
 		});
 
 		pi.on("session_shutdown", async (event, ctx) => {
-			sessionGeneration += 1;
+			const generation = ++sessionGeneration;
+			menuController.abort(new DOMException("Langfuse session shut down", "AbortError"));
 			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 +470,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 +488,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 +580,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))