pi-langfuse 1.5.4 → 1.5.6

package/README.md

@@ -57,6 +57,14 @@ To run setup again:
 /langfuse-setup
 ```
 
+To inspect the active configuration without exposing secrets:
+
+```text
+/langfuse-status
+```
+
+The status command reports the config source, host, masked public key, capture policy, active-run state, config path, and last runtime error.
+
 ### Method 2: Environment variables
 
 Set these before starting Pi:
@@ -124,6 +132,7 @@ Fine-grained capture flags can also be persisted:
 ```
 
 > **Security**: Keep `~/.pi/agent/pi-langfuse/config.json` private. Never commit API keys to version control.
+> When the extension writes this file itself, it creates the config directory with `0700` permissions and the file with `0600` permissions where the host filesystem supports POSIX modes.
 
 ## Verify the Extension
 
@@ -135,6 +144,14 @@ pi list
 
 `pi-langfuse` should appear in the installed package list.
 
+To verify the Langfuse host and API keys from inside Pi, run:
+
+```text
+/langfuse-test
+```
+
+This command makes a timeout-bounded authenticated request to Langfuse and, if it succeeds, sends a small test trace.
+
 ## What Appears in Langfuse
 
 - Each Pi session gets its own Langfuse session ID.
@@ -202,6 +219,7 @@ The extension must not upload raw absolute local paths, credentialed remotes, to
 ### No traces appearing?
 
 - Verify the API keys and run `/langfuse-setup` again if needed.
+- Run `/langfuse-status` to confirm the loaded host, config source, privacy mode, and last runtime error.
 - Confirm the Langfuse project is active and accepts writes.
 - Confirm the keys have write permission.
 - Look for `📊 Langfuse:` log messages in Pi output.

package/README_CN.md

@@ -57,6 +57,14 @@ Langfuse API 密钥可在 **Langfuse Cloud** -> **Settings** -> **API Keys** 中
 /langfuse-setup
 ```
 
+如需查看当前配置状态且不泄漏密钥：
+
+```text
+/langfuse-status
+```
+
+状态命令会显示配置来源、主机地址、脱敏后的公钥、采集策略、是否有活跃运行、配置文件路径，以及最近一次运行时错误。
+
 ### 方式 2：环境变量
 
 在启动 Pi 前设置：
@@ -124,6 +132,7 @@ export LANGFUSE_CAPTURE_CWD=false
 ```
 
 > **安全提醒**：`~/.pi/agent/pi-langfuse/config.json` 包含敏感信息，不应提交到版本控制。
+> 扩展自行写入该文件时，会在支持 POSIX 权限的文件系统上使用 `0700` 创建配置目录，并使用 `0600` 写入配置文件。
 
 ## 验证扩展是否已加载
 
@@ -135,6 +144,14 @@ pi list
 
 已安装包列表中应出现 `pi-langfuse`。
 
+如需在 Pi 内验证 Langfuse 主机地址和 API key：
+
+```text
+/langfuse-test
+```
+
+该命令会先发起一次带超时的认证请求；认证通过后，再发送一条小的测试 trace。
+
 ## 在 Langfuse 中会看到什么
 
 - 每个 Pi 会话对应一个独立的 Langfuse session ID。
@@ -155,6 +172,7 @@ pi list
 ### 没有看到 trace
 
 - 先检查 API 密钥是否正确，必要时重新执行 `/langfuse-setup`。
+- 执行 `/langfuse-status`，确认当前加载的主机、配置来源、隐私模式和最近一次运行时错误。
 - 确认 Langfuse 项目处于可写状态。
 - 确认密钥具备写权限。
 - 在 Pi 输出中查找 `📊 Langfuse:` 日志。

package/index.ts

@@ -13,7 +13,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { state, resetRunState, runWithSession, setCurrentSession } from "./src/state.js";
 import { ensureConfig, promptForConfig, loadConfig } from "./src/config.js";
 import { shutdownRuntime } from "./src/langfuse.js";
-import { handleLangfusePrivacyCommand, handleLangfuseTestCommand } from "./src/commands.js";
+import { handleLangfusePrivacyCommand, handleLangfuseStatusCommand, handleLangfuseTestCommand } from "./src/commands.js";
 import { getMessageFromEvent, extractAssistantOutput, getCapturePolicy } from "./src/utils.js";
 import { applyCapturePolicy } from "./src/capture-policy.js";
 import { startAgentRun, finishAgentRun } from "./src/handlers/agent.js";
@@ -60,6 +60,13 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("langfuse-status", {
+    description: "Show Langfuse configuration and runtime status",
+    handler: async (args, ctx) => {
+      await handleLangfuseStatusCommand(String(args ?? ""), ctx);
+    },
+  });
+
   pi.registerCommand("langfuse-privacy", {
     description: "View or set Langfuse telemetry privacy preset",
     handler: async (args, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.5.4",
+	"version": "1.5.6",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",
@@ -46,6 +46,8 @@
 		"@langfuse/client": "^5.3.0",
 		"@langfuse/otel": "^5.3.0",
 		"@langfuse/tracing": "^5.3.0",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/sdk-node": "^0.218.0",
 		"@opentelemetry/sdk-trace-base": "^2.0.1"
 	},

package/src/commands.ts

@@ -1,11 +1,18 @@
 import { existsSync, readFileSync } from "node:fs";
 
 import { CONFIG_PATH } from "./constants.js";
-import { loadConfig, saveConfig, ensureConfig } from "./config.js";
+import {
+  loadConfig,
+  loadConfigFromEnv,
+  loadConfigFromFile,
+  sanitizeConfigForLog,
+  saveConfig,
+  ensureConfig,
+} from "./config.js";
 import { createCapturePolicy, type PrivacyPreset, type CapturePolicy } from "./capture-policy.js";
-import { getRuntime, forceShutdownRuntime as shutdownLangfuseRuntime } from "./langfuse.js";
+import { getRuntime, getLastRuntimeError, forceShutdownRuntime as shutdownLangfuseRuntime } from "./langfuse.js";
 import { state } from "./state.js";
-import type { LangfuseRuntime } from "./types.js";
+import type { Config, LangfuseRuntime } from "./types.js";
 
 const PRIVACY_PRESETS = ["metadata-only", "prompts-only", "conversations", "full-debug"] as const;
 
@@ -21,6 +28,13 @@ interface CommandDeps {
   configPath?: string;
   getRuntime?: () => Promise<LangfuseRuntime>;
   forceShutdownRuntime?: () => Promise<void>;
+  env?: Record<string, string | undefined>;
+  checkConnectivity?: (config: Config) => Promise<ConnectivityResult>;
+}
+
+interface ConnectivityResult {
+  ok: boolean;
+  message: string;
 }
 
 function notify(ctx: CommandContextLike, message: string, level: "info" | "warning" | "error" = "info") {
@@ -128,6 +142,10 @@ function describePolicy(policy: CapturePolicy) {
   ].join("\n");
 }
 
+function flag(value: boolean): "on" | "off" {
+  return value ? "on" : "off";
+}
+
 function readPersistedConfig(path: string) {
   if (!existsSync(path)) {
     return {};
@@ -148,6 +166,108 @@ function hasActiveAgentObservation() {
   return false;
 }
 
+function configSource(env: Record<string, string | undefined>, configPath: string): string {
+  const fileConfig = loadConfigFromFile(configPath, env);
+  const envConfig = loadConfigFromEnv(env);
+  if (fileConfig && envConfig) {
+    return "config file (env capture flags may override saved privacy)";
+  }
+  if (fileConfig) {
+    return "config file";
+  }
+  if (envConfig) {
+    return "environment variables";
+  }
+  return "none";
+}
+
+function lastErrorSummary() {
+  const lastError = getLastRuntimeError();
+  if (!lastError) {
+    return "none";
+  }
+  return `${lastError.scope}: ${lastError.message} (${lastError.timestamp.toISOString()})`;
+}
+
+function formatStatus(configPath: string, env: Record<string, string | undefined>) {
+  const config = loadConfig(env, configPath);
+  if (!config) {
+    return [
+      "pi-langfuse status:",
+      "State: not configured",
+      `Config file: ${configPath}`,
+      "Action: run /langfuse-setup or set LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY",
+      `Last error: ${lastErrorSummary()}`,
+    ].join("\n");
+  }
+
+  const safeConfig = sanitizeConfigForLog(config);
+  const policy = config.capturePolicy ?? createCapturePolicy(env);
+  return [
+    "pi-langfuse status:",
+    "State: configured",
+    `Source: ${configSource(env, configPath)}`,
+    `Host: ${safeConfig?.host ?? config.host}`,
+    `Public key: ${safeConfig?.publicKey ?? "[REDACTED_SECRET]"}`,
+    `Config file: ${configPath}`,
+    `Privacy preset: ${inferPreset(policy)}`,
+    "Capture:",
+    `  inputs: ${flag(policy.captureInputs)}`,
+    `  outputs: ${flag(policy.captureOutputs)}`,
+    `  tool IO: ${flag(policy.captureToolIo)}`,
+    `  system prompt: ${flag(policy.captureSystemPrompt)}`,
+    `  cwd: ${flag(policy.captureCwd)}`,
+    `Active run: ${hasActiveAgentObservation() ? "yes" : "no"}`,
+    `Last error: ${lastErrorSummary()}`,
+  ].join("\n");
+}
+
+async function checkLangfuseConnectivity(config: Config): Promise<ConnectivityResult> {
+  const host = config.host.replace(/\/+$/, "");
+  const auth = Buffer.from(`${config.publicKey}:${config.secretKey}`).toString("base64");
+
+  try {
+    const response = await fetch(`${host}/api/public/projects`, {
+      headers: {
+        Authorization: `Basic ${auth}`,
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (response.ok) {
+      return { ok: true, message: `Connected to ${config.host}` };
+    }
+
+    return {
+      ok: false,
+      message: `${config.host} returned ${response.status} ${response.statusText}`.trim(),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function handleLangfuseStatusCommand(
+  args: string,
+  ctx: CommandContextLike,
+  deps: CommandDeps = {},
+): Promise<boolean> {
+  const parsed = parseCommandArgs(args);
+  const unexpected = parsed.malformed[0] ?? parsed.positional[0] ?? Object.keys(parsed.values)[0];
+  if (unexpected) {
+    notify(ctx, `Unexpected argument '${unexpected}'. Usage: /langfuse-status`, "warning");
+    return false;
+  }
+
+  const env = deps.env ?? process.env;
+  const configPath = deps.configPath ?? CONFIG_PATH;
+  notify(ctx, formatStatus(configPath, env));
+  return true;
+}
+
 function savePrivacyPreset(
   requestedPreset: PrivacyPreset,
   ctx: CommandContextLike,
@@ -227,10 +347,17 @@ export async function handleLangfusePrivacyCommand(
 }
 
 export async function handleLangfuseTestCommand(
-  _args: string,
+  args: string,
   ctx: CommandContextLike,
   deps: CommandDeps = {},
 ): Promise<boolean> {
+  const parsed = parseCommandArgs(args);
+  const unexpected = parsed.malformed[0] ?? parsed.positional[0] ?? Object.keys(parsed.values)[0];
+  if (unexpected) {
+    notify(ctx, `Unexpected argument '${unexpected}'. Usage: /langfuse-test`, "warning");
+    return false;
+  }
+
   if (!state.config && !(await ensureConfig(ctx))) {
     notify(ctx, "Langfuse is not configured yet. Run /langfuse-setup first.", "warning");
     return false;
@@ -241,6 +368,18 @@ export async function handleLangfuseTestCommand(
     return false;
   }
 
+  const config = state.config;
+  if (!config) {
+    notify(ctx, "Langfuse is not configured yet. Run /langfuse-setup first.", "warning");
+    return false;
+  }
+
+  const connectivity = await (deps.checkConnectivity ?? checkLangfuseConnectivity)(config);
+  if (!connectivity.ok) {
+    notify(ctx, `Langfuse connectivity check failed: ${connectivity.message}`, "error");
+    return false;
+  }
+
   let runtimeInitialized = false;
   try {
     const rt = await (deps.getRuntime ?? getRuntime)();
@@ -270,7 +409,7 @@ export async function handleLangfuseTestCommand(
         return observation;
       },
     );
-    notify(ctx, `Langfuse test succeeded. Test trace sent to ${state.config?.host}.`);
+    notify(ctx, `Langfuse test succeeded. ${connectivity.message}; test trace sent to ${config.host}.`);
     return true;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/src/config.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Config } from "./types.js";
 import { CONFIG_PATH, DEFAULT_LANGFUSE_HOST } from "./constants.js";
@@ -52,8 +52,33 @@ export function loadConfig(env: EnvLike = process.env as EnvLike, path = CONFIG_
 }
 
 export function saveConfig(config: Config, path = CONFIG_PATH) {
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(path), 0o700);
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+function maskPublicKey(value: string): string {
+  if (value.length <= 9) {
+    return "[REDACTED_SECRET]";
+  }
+  return `${value.slice(0, 6)}...${value.slice(-4)}`;
+}
+
+export function sanitizeConfigForLog(config: Pick<Config, "publicKey" | "secretKey" | "host"> | null): {
+  publicKey: string;
+  secretKey: string;
+  host: string;
+} | null {
+  if (!config) {
+    return null;
+  }
+
+  return {
+    publicKey: maskPublicKey(config.publicKey),
+    secretKey: "[REDACTED_SECRET]",
+    host: config.host || DEFAULT_LANGFUSE_HOST,
+  };
 }
 
 async function collectConfigFromUI(ctx: any, reason: string): Promise<Config | null> {

package/src/langfuse.ts

@@ -3,10 +3,23 @@ import { state } from "./state.js";
 import { randomUUID } from "node:crypto";
 
 let runtime: LangfuseRuntime | null = null;
+let registeredContextManager: OtelContextManager | null = null;
 const activeSessions = new Set<string>();
+let lastRuntimeError: { scope: string; message: string; timestamp: Date } | null = null;
 
 type FallbackObservationType = "SPAN" | "GENERATION";
 
+interface OtelContextManager {
+  enable(): OtelContextManager;
+  disable(): void;
+}
+
+interface OtelContextApi {
+  setGlobalContextManager(contextManager: OtelContextManager): boolean;
+}
+
+type AsyncHooksContextManagerCtor = new () => OtelContextManager;
+
 interface RestFallbackTrace {
   id: string;
   timestamp: string;
@@ -64,6 +77,36 @@ function debugLog(message: string) {
   }
 }
 
+export function ensureOtelContextManager(
+  contextApi: OtelContextApi,
+  AsyncHooksContextManager: AsyncHooksContextManagerCtor,
+): boolean {
+  if (registeredContextManager) {
+    return true;
+  }
+
+  const contextManager = new AsyncHooksContextManager().enable();
+  if (contextApi.setGlobalContextManager(contextManager)) {
+    registeredContextManager = contextManager;
+    return true;
+  }
+
+  contextManager.disable();
+  return false;
+}
+
+function rememberRuntimeError(scope: string, error: unknown) {
+  lastRuntimeError = {
+    scope,
+    message: error instanceof Error ? error.message : String(error),
+    timestamp: new Date(),
+  };
+}
+
+export function getLastRuntimeError(): { scope: string; message: string; timestamp: Date } | null {
+  return lastRuntimeError;
+}
+
 async function withTimeout<T>(label: string, operation: Promise<T> | undefined): Promise<T | undefined> {
   if (!operation) {
     return undefined;
@@ -338,6 +381,7 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime) {
   const responseErrors = responseBody?.errors;
   const errors = Array.isArray(responseErrors) ? responseErrors : [];
   if (errors.length > 0) {
+    rememberRuntimeError("REST fallback ingestion", new Error(JSON.stringify(errors)));
     console.warn("📊 Langfuse: REST fallback ingestion reported errors", errors);
   } else {
     debugLog(`📊 Langfuse: OTel trace ${trace.id} was not visible; wrote fallback trace via REST ingestion`);
@@ -358,8 +402,17 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
   }
 
   if (!runtime) {
-    const [{ BasicTracerProvider }, { LangfuseSpanProcessor }, tracing, { LangfuseClient }] = await Promise.all([
+    const [
+      { BasicTracerProvider },
+      { context },
+      { AsyncHooksContextManager },
+      { LangfuseSpanProcessor },
+      tracing,
+      { LangfuseClient },
+    ] = await Promise.all([
       import("@opentelemetry/sdk-trace-base"),
+      import("@opentelemetry/api"),
+      import("@opentelemetry/context-async-hooks"),
       import("@langfuse/otel"),
       import("@langfuse/tracing"),
       import("@langfuse/client"),
@@ -371,30 +424,37 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
       attempted: false,
     };
 
-    const spanProcessor = new LangfuseSpanProcessor({
-      publicKey: state.config.publicKey,
-      secretKey: state.config.secretKey,
-      baseUrl: state.config.host,
-    });
-    const tracerProvider = new BasicTracerProvider({ spanProcessors: [spanProcessor] });
-    tracing.setLangfuseTracerProvider(tracerProvider);
-
-    runtime = {
-      startObservation: ((name: string, body?: Record<string, unknown>, options?: { asType?: string }) => {
-        const observation = (tracing as any).startObservation(name, body, options);
-        return wrapObservation(observation, restFallback, name, body, options?.asType);
-      }) as unknown as LangfuseRuntime["startObservation"],
-      propagateAttributes: tracing.propagateAttributes as unknown as LangfuseRuntime["propagateAttributes"],
-      scoreClient: new LangfuseClient({
+    try {
+      ensureOtelContextManager(context, AsyncHooksContextManager);
+      const spanProcessor = new LangfuseSpanProcessor({
         publicKey: state.config.publicKey,
         secretKey: state.config.secretKey,
         baseUrl: state.config.host,
-      }) as LangfuseScoreClient,
-      spanProcessor,
-      tracerProvider,
-      clearTracerProvider: () => tracing.setLangfuseTracerProvider(null),
-      restFallback,
-    };
+      });
+      const tracerProvider = new BasicTracerProvider({ spanProcessors: [spanProcessor] });
+      tracing.setLangfuseTracerProvider(tracerProvider);
+
+      runtime = {
+        startObservation: ((name: string, body?: Record<string, unknown>, options?: { asType?: string }) => {
+          const observation = (tracing as any).startObservation(name, body, options);
+          return wrapObservation(observation, restFallback, name, body, options?.asType);
+        }) as unknown as LangfuseRuntime["startObservation"],
+        propagateAttributes: tracing.propagateAttributes as unknown as LangfuseRuntime["propagateAttributes"],
+        scoreClient: new LangfuseClient({
+          publicKey: state.config.publicKey,
+          secretKey: state.config.secretKey,
+          baseUrl: state.config.host,
+        }) as LangfuseScoreClient,
+        spanProcessor,
+        tracerProvider,
+        clearTracerProvider: () => tracing.setLangfuseTracerProvider(null),
+        restFallback,
+      };
+      lastRuntimeError = null;
+    } catch (e) {
+      rememberRuntimeError("runtime init", e);
+      throw e;
+    }
   }
 
   return runtime as LangfuseRuntime;
@@ -416,6 +476,7 @@ function doShutdownRuntime(): Promise<void> {
       await withTimeout("Langfuse client shutdown", rt.scoreClient.shutdown?.());
       await withTimeout("OTel tracer shutdown", rt.tracerProvider?.shutdown?.());
     } catch (e) {
+      rememberRuntimeError("runtime shutdown", e);
       console.warn("📊 Langfuse: Failed to flush/shutdown cleanly", e);
     } finally {
       if (!runtime) {
@@ -472,6 +533,7 @@ export async function sendScore(name: string, value: number, options: { traceId?
       sessionId: options.traceId ? undefined : state.currentSessionId || undefined,
     });
   } catch (e) {
+    rememberRuntimeError(`score ${name}`, e);
     console.warn(`📊 Langfuse: Failed to send score ${name}`, e);
   }
 }