pi-langfuse 1.5.10 → 1.5.12

package/README.md

@@ -14,7 +14,7 @@ Langfuse observability extension for [Pi Coding Agent](https://github.com/earend
 - Final assistant output capture, tool error visibility, and trace-level scores.
 - Privacy controls for inputs, outputs, tool I/O, system prompt, and cwd.
 - Secret redaction and local path hashing before upload.
-- REST fallback for self-hosted Langfuse setups where OTel spans arrive but traces do not materialize.
+- Capability-gated REST fallback for self-hosted Langfuse setups that expose the legacy trace API when OTel spans arrive but traces do not materialize. Langfuse v4 `events_only` deployments use OTel without legacy fallback ingestion.
 
 ## Prerequisites
 

package/README_CN.md

@@ -14,7 +14,7 @@
 - 记录最终助手输出、工具错误状态和追踪级别分数。
 - 提供输入、输出、工具 I/O、system prompt 和 cwd 的隐私采集开关。
 - 上传前脱敏常见密钥，并对本地绝对路径做 hash。
-- 针对自托管 Langfuse 提供 REST 兜底，覆盖 OTel span 已到达但 trace 未可见的场景。
+- 对仍提供旧版 trace API 的自托管 Langfuse 启用能力检测后的 REST 兜底，覆盖 OTel span 已到达但 trace 未可见的场景；Langfuse v4 `events_only` 部署仅使用 OTel，不执行旧版 REST 兜底写入。
 
 ## 前提条件
 

package/index.ts

@@ -16,7 +16,7 @@ import { shutdownRuntime } from "./src/langfuse.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";
+import { startAgentRun, finishAgentRun, recordSystemPrompt } from "./src/handlers/agent.js";
 import { startTurnObservation, finishTurnObservation } from "./src/handlers/turn.js";
 import {
   startGeneration,
@@ -112,6 +112,9 @@ export default async function (pi: ExtensionAPI) {
     if (!state.agentState?.root) {
       await startAgentRun(event, ctx);
     }
+    // The system prompt is only final here: before_agent_start handlers that
+    // run after this extension may still rewrite it.
+    await recordSystemPrompt(ctx);
   }));
 
   pi.on("turn_start", async (event, ctx) => withSession(ctx, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.5.10",
+	"version": "1.5.12",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",

package/src/handlers/agent.ts

@@ -54,15 +54,6 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
       state.currentProvider = ctx.model.provider || "";
     }
 
-    let systemPrompt = undefined;
-    try {
-      if (ctx.getSystemPrompt) {
-        systemPrompt = await ctx.getSystemPrompt();
-      }
-    } catch {
-      // Ignore if getSystemPrompt is not available or fails
-    }
-
     const rawPromptInput = shapePayload({
       prompt: event.prompt,
       images: event.images,
@@ -79,7 +70,6 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
           ...(state.currentProvider ? { provider: state.currentProvider } : {}),
           sessionId: state.currentSessionId || undefined,
         },
-        systemPrompt: systemPrompt ? truncate(String(systemPrompt), getLimits().maxString) : undefined,
       },
       getCapturePolicy(),
     );
@@ -106,10 +96,7 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
           "pi-agent",
             {
               input: captured.input,
-              metadata: {
-                ...(captured.metadata ?? {}),
-                ...(captured.systemPrompt ? { systemPrompt: captured.systemPrompt } : {}),
-              },
+              metadata: captured.metadata ?? {},
             },
           { asType: "agent" },
         ),
@@ -124,6 +111,49 @@ export async function startAgentRun(event: Record<string, unknown>, ctx: any) {
   }
 }
 
+/**
+ * Records the effective system prompt on the root agent observation.
+ *
+ * Deliberately called from `agent_start` rather than `before_agent_start`:
+ * during `before_agent_start` the extension runner hands each handler the
+ * prompt as it stands mid-chain, so extensions registered after this one
+ * (e.g. inline factories that rewrite the system prompt) are not reflected
+ * yet. By `agent_start` the session has applied the final override, and
+ * `ctx.getSystemPrompt()` returns the prompt actually sent to the model.
+ */
+export async function recordSystemPrompt(ctx: any) {
+  const root = state.agentState?.root;
+  if (state.isTracingDisabled || !root) {
+    return;
+  }
+
+  let systemPrompt = undefined;
+  try {
+    if (ctx.getSystemPrompt) {
+      systemPrompt = await ctx.getSystemPrompt();
+    }
+  } catch {
+    // Ignore if getSystemPrompt is not available or fails
+  }
+  if (!systemPrompt) {
+    return;
+  }
+
+  const captured = applyCapturePolicy(
+    { systemPrompt: truncate(String(systemPrompt), getLimits().maxString) },
+    getCapturePolicy(),
+  );
+  if (!captured.systemPrompt) {
+    return;
+  }
+
+  try {
+    root.update({ metadata: { systemPrompt: captured.systemPrompt } });
+  } catch (e) {
+    console.warn("\u{1F4CA} Langfuse: Failed to record system prompt", e);
+  }
+}
+
 export async function finishAgentRun(event: Record<string, unknown> = {}) {
   if (!state.agentState?.root) {
     resetRunState();

package/src/langfuse.ts

@@ -8,6 +8,8 @@ const activeSessions = new Set<string>();
 let lastRuntimeError: { scope: string; message: string; timestamp: Date } | null = null;
 
 type FallbackObservationType = "SPAN" | "GENERATION";
+type LegacyTraceApiCapability = "supported" | "unsupported";
+type TraceVisibility = "visible" | "missing" | "legacy-api-unsupported" | "unknown";
 
 interface OtelContextManager {
   enable(): OtelContextManager;
@@ -55,6 +57,7 @@ interface RestFallbackStore {
   observations: RestFallbackObservation[];
   observationById: Map<string, RestFallbackObservation>;
   attempted: boolean;
+  legacyTraceApi?: LegacyTraceApiCapability;
 }
 
 const OTEL_VISIBILITY_TIMEOUT_MS = 1_500;
@@ -139,7 +142,16 @@ export function getLastRuntimeError(): { scope: string; message: string; timesta
   return lastRuntimeError;
 }
 
-async function withShutdownDeadline<T>(label: string, startOperation: () => Promise<T> | undefined, deadline: number): Promise<T | undefined> {
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+async function withShutdownDeadline<T>(
+  label: string,
+  startOperation: () => Promise<T> | undefined,
+  deadline: number,
+  signal?: AbortSignal,
+): Promise<T | undefined> {
   const remainingMs = deadline - Date.now();
   if (remainingMs <= 0) {
     debugLog(`📊 Langfuse: Skipped ${label}; shutdown deadline elapsed`);
@@ -162,6 +174,12 @@ async function withShutdownDeadline<T>(label: string, startOperation: () => Prom
         }, remainingMs);
       }),
     ]);
+  } catch (error) {
+    if (signal?.aborted && isAbortError(error)) {
+      debugLog(`📊 Langfuse: ${label} aborted; shutdown deadline elapsed`);
+      return undefined;
+    }
+    throw error;
   } finally {
     if (timeout) {
       clearTimeout(timeout);
@@ -169,6 +187,21 @@ async function withShutdownDeadline<T>(label: string, startOperation: () => Prom
   }
 }
 
+async function runShutdownStep<T>(
+  label: string,
+  startOperation: () => Promise<T> | undefined,
+  deadline: number,
+  signal?: AbortSignal,
+): Promise<T | undefined> {
+  try {
+    return await withShutdownDeadline(label, startOperation, deadline, signal);
+  } catch (error) {
+    rememberRuntimeError(`runtime shutdown: ${label}`, error);
+    console.warn(`📊 Langfuse: Failed ${label} during shutdown`, error);
+    return undefined;
+  }
+}
+
 function getRuntimeConfig(rt: LangfuseRuntime) {
   return rt.runtimeConfig ?? state.config;
 }
@@ -436,10 +469,51 @@ function wrapObservation(
   };
 }
 
-async function traceExists(rt: LangfuseRuntime, traceId: string, signal: AbortSignal): Promise<boolean> {
+async function getLegacyTraceApiCapability(
+  rt: LangfuseRuntime,
+  store: RestFallbackStore,
+  signal: AbortSignal,
+): Promise<LegacyTraceApiCapability | undefined> {
+  if (store.legacyTraceApi) {
+    return store.legacyTraceApi;
+  }
+
+  const config = getRuntimeConfig(rt);
+  if (!config) {
+    return undefined;
+  }
+
+  try {
+    const response = await fetch(`${config.host.replace(/\/$/, "")}/api/public/traces?limit=1`, {
+      headers: ingestionHeaders(rt),
+      signal,
+    });
+    if (response.status === 404) {
+      store.legacyTraceApi = "unsupported";
+      return store.legacyTraceApi;
+    }
+    if (!response.ok) {
+      return undefined;
+    }
+    store.legacyTraceApi = "supported";
+    return store.legacyTraceApi;
+  } catch (error) {
+    if (signal.aborted) {
+      throw error;
+    }
+    return undefined;
+  }
+}
+
+async function getTraceVisibility(
+  rt: LangfuseRuntime,
+  store: RestFallbackStore,
+  traceId: string,
+  signal: AbortSignal,
+): Promise<TraceVisibility> {
   const config = getRuntimeConfig(rt);
   if (!config) {
-    return false;
+    return "unknown";
   }
 
   try {
@@ -451,31 +525,41 @@ async function traceExists(rt: LangfuseRuntime, traceId: string, signal: AbortSi
       },
     );
     if (response.status === 404) {
-      return false;
+      const capability = await getLegacyTraceApiCapability(rt, store, signal);
+      if (capability === "supported") {
+        return "missing";
+      }
+      return capability === "unsupported" ? "legacy-api-unsupported" : "unknown";
     }
     if (!response.ok) {
-      throw new Error(`Langfuse trace visibility check failed with HTTP ${response.status}`);
+      return "unknown";
     }
-    return true;
+    return "visible";
   } catch (error) {
     if (signal.aborted) {
       throw error;
     }
-    return false;
+    return "unknown";
   }
 }
 
-async function waitForTraceVisibility(rt: LangfuseRuntime, traceId: string, signal: AbortSignal): Promise<boolean> {
+async function waitForTraceVisibility(
+  rt: LangfuseRuntime,
+  store: RestFallbackStore,
+  traceId: string,
+  signal: AbortSignal,
+): Promise<TraceVisibility> {
   const deadline = Date.now() + OTEL_VISIBILITY_TIMEOUT_MS;
 
   while (true) {
-    if (await traceExists(rt, traceId, signal)) {
-      return true;
+    const visibility = await getTraceVisibility(rt, store, traceId, signal);
+    if (visibility !== "missing") {
+      return visibility;
     }
 
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0) {
-      return false;
+      return "missing";
     }
 
     await delay(Math.min(OTEL_VISIBILITY_POLL_INTERVAL_MS, remainingMs), signal);
@@ -493,7 +577,12 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal)
   }
   store.attempted = true;
 
-  if (await waitForTraceVisibility(rt, store.trace.id, signal)) {
+  const visibility = await waitForTraceVisibility(rt, store, store.trace.id, signal);
+  if (visibility === "visible") {
+    return;
+  }
+  if (visibility !== "missing") {
+    debugLog(`📊 Langfuse: Skipped REST fallback; trace visibility is ${visibility}`);
     return;
   }
 
@@ -654,32 +743,37 @@ function doShutdownRuntime(): Promise<void> {
     const controller = new AbortController();
     const abortTimeout = setTimeout(() => controller.abort(), shutdownStepTimeoutMs);
     const scoreController = new AbortController();
+    const scoreShutdownTimeoutMs = Math.min(getScoreShutdownTimeoutMs(), shutdownStepTimeoutMs);
+    const scoreDeadline = Math.min(deadline, Date.now() + scoreShutdownTimeoutMs);
     const scoreAbortTimeout = setTimeout(
       () => scoreController.abort(),
-      Math.min(getScoreShutdownTimeoutMs(), shutdownStepTimeoutMs),
+      scoreShutdownTimeoutMs,
     );
     scoreAbortTimeout.unref?.();
     stopScoreFlush(rt);
 
     try {
-      await withShutdownDeadline(
+      await runShutdownStep(
         "Active score flush",
         () => rt.scoreFlushPromise,
         deadline,
       );
-      await flushPendingScores(rt, scoreController.signal);
-      await withShutdownDeadline("OTel force flush", () => rt.tracerProvider?.forceFlush?.(), deadline);
-      await withShutdownDeadline(
+      await runShutdownStep(
+        "Pending score flush",
+        () => flushPendingScores(rt, scoreController.signal),
+        scoreDeadline,
+        scoreController.signal,
+      );
+      await runShutdownStep("OTel force flush", () => rt.tracerProvider?.forceFlush?.(), deadline);
+      await runShutdownStep("Langfuse score flush", () => rt.scoreClient.flush?.(), deadline);
+      await runShutdownStep("Langfuse client shutdown", () => rt.scoreClient.shutdown?.(), deadline);
+      await runShutdownStep("OTel tracer shutdown", () => rt.tracerProvider?.shutdown?.(), deadline);
+      await runShutdownStep(
         "REST fallback ingestion",
         () => fallbackToRestIngestion(rt, controller.signal),
         deadline,
+        controller.signal,
       );
-      await withShutdownDeadline("Langfuse score flush", () => rt.scoreClient.flush?.(), deadline);
-      await withShutdownDeadline("Langfuse client shutdown", () => rt.scoreClient.shutdown?.(), deadline);
-      await withShutdownDeadline("OTel tracer shutdown", () => rt.tracerProvider?.shutdown?.(), deadline);
-    } catch (e) {
-      rememberRuntimeError("runtime shutdown", e);
-      console.warn("📊 Langfuse: Failed to flush/shutdown cleanly", e);
     } finally {
       clearTimeout(abortTimeout);
       clearTimeout(scoreAbortTimeout);