pi-langfuse 1.3.2 → 1.4.0

package/README.md

@@ -14,6 +14,7 @@ Langfuse provides open-source observability for LLM applications. This extension
 ## Features
 
 - **Complete Agent Traces**: Creates one trace per user prompt with a root `agent` observation containing the prompt input and final assistant output.
+- **REST fallback for self-hosted Langfuse**: Uses the Langfuse OpenTelemetry SDK first, then verifies that the trace is visible. If a self-hosted OTel ingestion pipeline accepts spans but does not materialize traces, the extension writes the run through Langfuse's REST ingestion API.
 - **Per-Request Generations**: Records a separate `generation` observation for every provider request, including the actual provider payload instead of only the original prompt.
 - **Final Message Capture**: Uses finalized assistant messages for generation and root outputs, so Langfuse shows what the user actually saw in Pi.
 - **Tool Observability**: Creates Langfuse `tool` observations for every tool call, including arguments, results, and error states.
@@ -78,7 +79,7 @@ Run any `pi` command with the extension loaded. On first run without configurati
 2. **Langfuse secret key** — starts with `sk-lf-...`
 3. **Langfuse host** — defaults to `https://cloud.langfuse.com`
 
-The extension saves these to a local `config.json` (ignored by git).
+The extension saves these to `~/.pi/agent/pi-langfuse/config.json`, so package updates and reinstalls do not overwrite your Langfuse credentials.
 
 To re-run setup at any time:
 
@@ -86,7 +87,7 @@ To re-run setup at any time:
 /langfuse-setup
 ```
 
-### Method 2: Environment variables
+### Method 2: Environment variables (fallback)
 
 Set these before starting Pi:
 
@@ -96,11 +97,11 @@ export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
 export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # optional; LANGFUSE_HOST is also supported
 ```
 
-The extension checks the local `config.json` first, then falls back to environment variables.
+The saved config file takes precedence. Environment variables are used only when `~/.pi/agent/pi-langfuse/config.json` does not exist or is incomplete, which avoids drift after re-running `/langfuse-setup`.
 
-### Method 3: Local config.json (development only)
+### Method 3: Persistent config.json
 
-For local development, create a `config.json` in the project root:
+For persistent local configuration, create or update `~/.pi/agent/pi-langfuse/config.json`:
 
 ```json
 {
@@ -110,7 +111,7 @@ For local development, create a `config.json` in the project root:
 }
 ```
 
-> **⚠️ Security**: `config.json` is not tracked by git. Never commit API keys to version control.
+> **⚠️ Security**: Keep `~/.pi/agent/pi-langfuse/config.json` private. Never commit API keys to version control.
 
 ## Usage
 
@@ -160,7 +161,6 @@ pi-langfuse/
 ├── index.ts            # Extension entrypoint and core logic
 ├── package.json        # Package metadata
 ├── tsconfig.json       # TypeScript configuration
-├── config.json         # Local credentials (git-ignored)
 ├── types/
 │   ├── pi-coding-agent.d.ts   # Pi extension API types
 │   └── node-shims.d.ts        # Node.js module shims

package/README_CN.md

@@ -14,6 +14,7 @@ Langfuse 为 LLM 应用程序提供开源的可观测性。此扩展允许您以
 ## 功能
 
 - **完整的代理追踪**：为每个用户提示词创建一个追踪，包含一个根 `agent`（代理）观察节点，其中记录了提示词输入和最终助手输出。
+- **自建 Langfuse 的 REST 兜底**：优先使用 Langfuse OpenTelemetry SDK 上报，然后验证追踪是否可见。如果自建 OTel 摄取链路接受了 span 但没有生成 trace，扩展会通过 Langfuse REST ingestion API 补写本次运行。
 - **每次请求生成记录**：为每次提供商请求记录单独的 `generation`（生成）观察节点，包含实际的提供商请求负载，而不仅仅是原始提示词。
 - **捕获最终消息**：在生成和根输出中使用已定型的助手消息，因此 Langfuse 会显示用户在 Pi 中实际看到的内容。
 - **工具可观测性**：为每次工具调用创建 Langfuse `tool`（工具）观察节点，包括参数、结果和错误状态。
@@ -78,7 +79,7 @@ pi link /path/to/pi-langfuse
 2. **Langfuse 密钥** — 以 `sk-lf-...` 开头
 3. **Langfuse 主机地址** — 默认为 `https://cloud.langfuse.com`
 
-扩展会将这些保存到本地的 `config.json`（被 git 忽略）。
+扩展会将这些保存到 `~/.pi/agent/pi-langfuse/config.json`，这样 Pi 更新、重装扩展时不会覆盖你的 Langfuse 凭据。
 
 随时重新运行设置：
 
@@ -86,7 +87,7 @@ pi link /path/to/pi-langfuse
 /langfuse-setup
 ```
 
-### 方式 2：环境变量
+### 方式 2：环境变量（兜底）
 
 在启动 Pi 前设置：
 
@@ -96,11 +97,11 @@ export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
 export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # 可选；也支持 LANGFUSE_HOST
 ```
 
-扩展会先检查本地的 `config.json`，然后回退到环境变量。
+保存的配置文件优先级更高。只有当 `~/.pi/agent/pi-langfuse/config.json` 不存在或不完整时，扩展才会使用环境变量，这样重新运行 `/langfuse-setup` 后不会出现配置漂移。
 
-### 方式 3：本地 config.json（仅限开发）
+### 方式 3：持久化 config.json
 
-对于本地开发，在项目根目录创建 `config.json`：
+如需使用持久化本地配置，创建或更新 `~/.pi/agent/pi-langfuse/config.json`：
 
 ```json
 {
@@ -110,7 +111,7 @@ export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # 可选；也支持 LANG
 }
 ```
 
-> **⚠️ 安全提醒**：`config.json` 不会被 git 跟踪。切勿将 API 密钥提交到版本控制。
+> **⚠️ 安全提醒**：请保护好 `~/.pi/agent/pi-langfuse/config.json`。切勿将 API 密钥提交到版本控制。
 
 ## 使用
 
@@ -160,7 +161,6 @@ pi-langfuse/
 ├── index.ts            # 扩展入口和核心逻辑
 ├── package.json        # 包元数据
 ├── tsconfig.json       # TypeScript 配置
-├── config.json         # 本地凭据（git 忽略）
 ├── types/
 │   ├── pi-coding-agent.d.ts   # Pi 扩展 API 类型
 │   └── node-shims.d.ts        # Node.js 模块 shims

package/index.ts

@@ -11,7 +11,7 @@ import { basename } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { state, resetRunState } from "./src/state.js";
-import { ensureConfig, promptForConfig, loadConfigFromEnv, loadConfigFromFile } from "./src/config.js";
+import { ensureConfig, promptForConfig, loadConfig } from "./src/config.js";
 import { shutdownRuntime } from "./src/langfuse.js";
 import { getMessageFromEvent, extractAssistantOutput } from "./src/utils.js";
 import { startAgentRun, finishAgentRun } from "./src/handlers/agent.js";
@@ -35,7 +35,7 @@ import {
 
 export default async function (pi: ExtensionAPI) {
   if (!state.config) {
-    state.config = loadConfigFromEnv() || loadConfigFromFile();
+    state.config = loadConfig();
   }
 
   if (state.config) {

package/package.json

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

package/src/config.ts

@@ -1,6 +1,6 @@
-import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
 import type { Config } from "./types.js";
-import { CONFIG_PATH, DEFAULT_LANGFUSE_HOST } from "./constants.js";
+import { CONFIG_DIR, CONFIG_PATH, DEFAULT_LANGFUSE_HOST } from "./constants.js";
 import { state } from "./state.js";
 import { shutdownRuntime } from "./langfuse.js";
 
@@ -38,7 +38,12 @@ export function loadConfigFromEnv(): Config | null {
   };
 }
 
+export function loadConfig(): Config | null {
+  return loadConfigFromFile() || loadConfigFromEnv();
+}
+
 export function saveConfig(config: Config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
   writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
 }
 
@@ -79,7 +84,7 @@ async function saveConfigFromUI(ctx: any, config: Config): Promise<boolean> {
     return true;
   } catch (error) {
     console.warn("📊 Langfuse: Failed to save config.json", error);
-    ctx.ui.notify("Failed to save Langfuse config.json. Check extension directory permissions.", "error");
+    ctx.ui.notify(`Failed to save Langfuse config.json to ${CONFIG_PATH}. Check Pi config directory permissions.`, "error");
     state.config = null;
     return false;
   }
@@ -87,7 +92,7 @@ async function saveConfigFromUI(ctx: any, config: Config): Promise<boolean> {
 
 export async function ensureConfig(ctx: any): Promise<boolean> {
   if (!state.config) {
-    state.config = loadConfigFromEnv() || loadConfigFromFile();
+    state.config = loadConfig();
   }
 
   if (state.config) {
@@ -114,7 +119,7 @@ export async function promptForConfig(ctx: any): Promise<boolean> {
 
   const config = await collectConfigFromUI(ctx, "Manual setup requested");
   if (!config) {
-    state.config = loadConfigFromEnv() || loadConfigFromFile();
+    state.config = loadConfig();
     return false;
   }
 

package/src/constants.ts

@@ -1,11 +1,8 @@
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
 
-// Since we are in src/constants.ts, EXT_DIR should point to the parent of src/ (the root of the extension)
-// We use `import.meta.url` which points to `src/constants.ts`.
-// `dirname` gives us `src/`, and `resolve(..., '..')` gives us the root.
-export const EXT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-export const CONFIG_PATH = resolve(EXT_DIR, "config.json");
+export const CONFIG_DIR = resolve(homedir(), ".pi", "agent", "pi-langfuse");
+export const CONFIG_PATH = resolve(CONFIG_DIR, "config.json");
 export const DEFAULT_LANGFUSE_HOST = "https://cloud.langfuse.com";
 
 export const MAX_STRING_LENGTH = 12_000;

package/src/langfuse.ts

@@ -1,8 +1,277 @@
 import type { LangfuseRuntime, LangfuseScoreClient } from "./types.js";
 import { state } from "./state.js";
+import { randomUUID } from "node:crypto";
 
 let runtime: LangfuseRuntime | null = null;
 
+type FallbackObservationType = "SPAN" | "GENERATION";
+
+interface RestFallbackTrace {
+  id: string;
+  timestamp: string;
+  name: string;
+  input?: unknown;
+  output?: unknown;
+  sessionId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface RestFallbackObservation {
+  id: string;
+  traceId: string;
+  type: FallbackObservationType;
+  name: string;
+  startTime: string;
+  endTime?: string;
+  parentObservationId?: string;
+  input?: unknown;
+  output?: unknown;
+  metadata?: Record<string, unknown>;
+  model?: string;
+  usageDetails?: Record<string, number>;
+  costDetails?: Record<string, number>;
+  level?: "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
+  statusMessage?: string;
+  completionStartTime?: string;
+}
+
+interface RestFallbackStore {
+  trace?: RestFallbackTrace;
+  observations: RestFallbackObservation[];
+  observationById: Map<string, RestFallbackObservation>;
+  attempted: boolean;
+}
+
+const OTEL_VISIBILITY_DELAY_MS = 1_500;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function delay(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function toIso(value: unknown): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return undefined;
+}
+
+function mergeMetadata(current: Record<string, unknown> | undefined, next: Record<string, unknown> | undefined) {
+  return next ? { ...(current ?? {}), ...next } : current;
+}
+
+function applyObservationUpdate(record: RestFallbackObservation, body: Record<string, unknown> | undefined) {
+  if (!body) {
+    return;
+  }
+
+  if ("input" in body) record.input = body.input;
+  if ("output" in body) record.output = body.output;
+  if ("metadata" in body && body.metadata && typeof body.metadata === "object") {
+    record.metadata = mergeMetadata(record.metadata, body.metadata as Record<string, unknown>);
+  }
+  if (typeof body.model === "string") record.model = body.model;
+  if (body.usageDetails && typeof body.usageDetails === "object") {
+    record.usageDetails = body.usageDetails as Record<string, number>;
+  }
+  if (body.costDetails && typeof body.costDetails === "object") {
+    record.costDetails = body.costDetails as Record<string, number>;
+  }
+  if (typeof body.level === "string") record.level = body.level as RestFallbackObservation["level"];
+  if (typeof body.statusMessage === "string") record.statusMessage = body.statusMessage;
+  const completionStartTime = toIso(body.completionStartTime);
+  if (completionStartTime) record.completionStartTime = completionStartTime;
+}
+
+function applyTraceUpdate(store: RestFallbackStore, body: Record<string, unknown> | undefined) {
+  if (!store.trace || !body) {
+    return;
+  }
+
+  if ("input" in body) store.trace.input = body.input;
+  if ("output" in body) store.trace.output = body.output;
+  if ("metadata" in body && body.metadata && typeof body.metadata === "object") {
+    store.trace.metadata = mergeMetadata(store.trace.metadata, body.metadata as Record<string, unknown>);
+  }
+}
+
+function observationType(asType?: string): FallbackObservationType {
+  return asType === "generation" ? "GENERATION" : "SPAN";
+}
+
+function wrapObservation(
+  observation: any,
+  store: RestFallbackStore,
+  name: string,
+  body: Record<string, unknown> | undefined,
+  asType?: string,
+  parentObservationId?: string,
+): any {
+  const id = observation.id || randomUUID();
+  const traceId = observation.traceId || store.trace?.id || randomUUID();
+  const metadata = body?.metadata && typeof body.metadata === "object" ? body.metadata as Record<string, unknown> : undefined;
+  const record: RestFallbackObservation = {
+    id,
+    traceId,
+    name,
+    type: observationType(asType),
+    startTime: nowIso(),
+    parentObservationId,
+    metadata: mergeMetadata(metadata, asType && asType !== "generation" && asType !== "span" ? { langfuseObservationType: asType } : undefined),
+  };
+  applyObservationUpdate(record, body);
+
+  store.observations.push(record);
+  store.observationById.set(id, record);
+
+  if (!parentObservationId && !store.trace) {
+    store.trace = {
+      id: traceId,
+      timestamp: record.startTime,
+      name,
+      input: body?.input,
+      sessionId: typeof metadata?.sessionId === "string" ? metadata.sessionId : state.currentSessionId || undefined,
+      metadata,
+    };
+  }
+
+  return {
+    ...observation,
+    id,
+    traceId,
+    update(updateBody?: Record<string, unknown>) {
+      applyObservationUpdate(record, updateBody);
+      if (!parentObservationId) {
+        applyTraceUpdate(store, updateBody);
+      }
+      const updated = observation.update(updateBody);
+      return updated === observation ? this : updated;
+    },
+    end(endBody?: Record<string, unknown>) {
+      if (endBody && typeof endBody === "object") {
+        applyObservationUpdate(record, endBody);
+        if (!parentObservationId) {
+          applyTraceUpdate(store, endBody);
+        }
+      }
+      record.endTime = nowIso();
+      return observation.end();
+    },
+    startObservation(childName: string, childBody?: Record<string, unknown>, options?: { asType?: string }) {
+      const child = observation.startObservation(childName, childBody, options);
+      return wrapObservation(child, store, childName, childBody, options?.asType, id);
+    },
+    setTraceIO(traceBody?: { input?: unknown; output?: unknown }) {
+      applyTraceUpdate(store, traceBody);
+      return observation.setTraceIO?.(traceBody);
+    },
+  };
+}
+
+async function traceExists(rt: LangfuseRuntime, traceId: string): Promise<boolean> {
+  try {
+    const getTrace = rt.scoreClient.api?.trace?.get;
+    if (!getTrace) {
+      return false;
+    }
+    await getTrace(traceId);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function eventTimestamp(record: { endTime?: string; startTime?: string; timestamp?: string }) {
+  return record.endTime ?? record.startTime ?? record.timestamp ?? nowIso();
+}
+
+async function fallbackToRestIngestion(rt: LangfuseRuntime) {
+  const store = rt.restFallback as RestFallbackStore | undefined;
+  if (!store?.trace || store.attempted) {
+    return;
+  }
+  store.attempted = true;
+
+  await delay(OTEL_VISIBILITY_DELAY_MS);
+  if (await traceExists(rt, store.trace.id)) {
+    return;
+  }
+
+  const trace = store.trace;
+  const batch: any[] = [
+    {
+      type: "trace-create",
+      id: randomUUID(),
+      timestamp: eventTimestamp(trace),
+      body: {
+        id: trace.id,
+        timestamp: trace.timestamp,
+        name: trace.name,
+        input: trace.input,
+        output: trace.output,
+        sessionId: trace.sessionId,
+        metadata: trace.metadata,
+      },
+    },
+  ];
+
+  for (const observation of store.observations) {
+    const body = {
+      id: observation.id,
+      traceId: observation.traceId,
+      name: observation.name,
+      startTime: observation.startTime,
+      endTime: observation.endTime,
+      input: observation.input,
+      output: observation.output,
+      metadata: observation.metadata,
+      level: observation.level,
+      statusMessage: observation.statusMessage,
+      parentObservationId: observation.parentObservationId,
+      ...(observation.type === "GENERATION"
+        ? {
+            completionStartTime: observation.completionStartTime,
+            model: observation.model,
+            usageDetails: observation.usageDetails,
+            costDetails: observation.costDetails,
+          }
+        : {}),
+    };
+    batch.push({
+      type: observation.type === "GENERATION" ? "generation-create" : "span-create",
+      id: randomUUID(),
+      timestamp: eventTimestamp(observation),
+      body,
+    });
+  }
+
+  const response = await rt.scoreClient.api?.ingestion?.batch?.({
+    batch,
+    metadata: {
+      source: "pi-langfuse",
+      fallback: "rest-ingestion",
+      reason: "otel-trace-not-visible-after-flush",
+    },
+  });
+
+  const responseBody = response as { errors?: unknown[] } | undefined;
+  const errors = Array.isArray(responseBody?.errors) ? responseBody.errors : [];
+  if (errors.length > 0) {
+    console.warn("📊 Langfuse: REST fallback ingestion reported errors", errors);
+  } else {
+    console.warn(`📊 Langfuse: OTel trace ${trace.id} was not visible; wrote fallback trace via REST ingestion`);
+  }
+}
+
 export async function getRuntime(): Promise<LangfuseRuntime> {
   if (!state.config) {
     throw new Error("Langfuse config is not set");
@@ -16,6 +285,12 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
       import("@langfuse/client"),
     ]);
 
+    const restFallback: RestFallbackStore = {
+      observations: [],
+      observationById: new Map(),
+      attempted: false,
+    };
+
     const spanProcessor = new LangfuseSpanProcessor({
       publicKey: state.config.publicKey,
       secretKey: state.config.secretKey,
@@ -25,7 +300,10 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
     tracing.setLangfuseTracerProvider(tracerProvider);
 
     runtime = {
-      startObservation: tracing.startObservation as unknown as LangfuseRuntime["startObservation"],
+      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,
@@ -35,6 +313,7 @@ export async function getRuntime(): Promise<LangfuseRuntime> {
       spanProcessor,
       tracerProvider,
       clearTracerProvider: () => tracing.setLangfuseTracerProvider(null),
+      restFallback,
     };
   }
 
@@ -47,9 +326,10 @@ export async function shutdownRuntime(): Promise<void> {
   }
 
   try {
+    await runtime.tracerProvider?.forceFlush?.();
+    await fallbackToRestIngestion(runtime);
     await runtime.scoreClient.flush?.();
     await runtime.scoreClient.shutdown?.();
-    await runtime.tracerProvider?.forceFlush?.();
     await runtime.tracerProvider?.shutdown?.();
   } catch (e) {
     console.warn("📊 Langfuse: Failed to flush/shutdown cleanly", e);

package/src/types.ts

@@ -31,6 +31,14 @@ export interface ObservationUpdate {
 }
 
 export interface LangfuseScoreClient {
+  api?: {
+    trace?: {
+      get?: (traceId: string) => Promise<unknown>;
+    };
+    ingestion?: {
+      batch?: (request: unknown) => Promise<unknown>;
+    };
+  };
   score?: {
     create(body: {
       traceId?: string;
@@ -64,6 +72,7 @@ export interface LangfuseRuntime {
   spanProcessor?: { forceFlush?: () => Promise<void>; shutdown?: () => Promise<void> };
   tracerProvider?: { forceFlush?: () => Promise<void>; shutdown?: () => Promise<void> };
   clearTracerProvider?: () => void;
+  restFallback?: unknown;
 }
 
 export interface GenerationState {

package/types/node-shims.d.ts

@@ -1,9 +1,18 @@
 declare module "node:fs" {
+  export function mkdirSync(path: string, options?: { recursive?: boolean }): void;
   export function readFileSync(path: string, encoding: string): string;
   export function existsSync(path: string): boolean;
   export function writeFileSync(path: string, data: string, encoding: string): void;
 }
 
+declare module "node:crypto" {
+  export function randomUUID(): string;
+}
+
+declare module "node:os" {
+  export function homedir(): string;
+}
+
 declare module "node:path" {
   export function resolve(...paths: string[]): string;
   export function dirname(path: string): string;

package/.trae/documents/optimize_langfuse_reporting.md

@@ -1,68 +0,0 @@
-# Langfuse 追踪逻辑优化方案
-
-## 1. 背景与目标
-根据之前的建议，我们需要进一步优化 Pi-Langfuse 扩展的上报逻辑，使得在 Langfuse 控制台中观察 Agent 执行过程时更加细致、层级分明且数据完备。
-本次优化包含 5 个核心点：引入 Turn 级别的 Span、精准追踪 TTFT（首字响应时间）、处理 Provider 请求异常、上报 System Prompt，以及完善 Session 的边缘生命周期和上下文压缩（Compact）处理。
-
-## 2. 现状分析
-- **层级结构**：目前 `llm-generation` 和 `tool` 是平级挂载在根 Trace 下，多轮对话时瀑布图非常扁平。
-- **TTFT**：尚未记录 `completionStartTime`，无法在 Langfuse 中直观看到首字耗时。
-- **异常闭环**：LLM Provider 发生 4xx/5xx HTTP 错误时，`message_end` 可能不触发，导致 Generation 无法正常闭合。
-- **上下文完备性**：`before_agent_start` 仅提取了 user prompt，缺少 System Prompt，不利于后期 Debug。
-- **Session 生命周期**：仅处理了 `session_start` 和 `session_shutdown`，忽略了 `/new`, `/resume`, `/fork`, `/compact` 等高级会话操作引发的状态混乱问题。
-
-## 3. 具体修改方案
-
-### 3.1 引入 Turn-Level Span (层级结构优化)
-将一轮对话（Turn）包装为一个 Span，使其成为 Generation 和 Tool 的父节点。
-- **`src/types.ts`**:
-  - 在 `AgentState` 接口中增加 `activeTurn?: LangfuseObservation` 字段。
-- **`src/handlers/turn.ts` (新建)**:
-  - 实现 `startTurnObservation(event)`：调用 `state.agentState.root.startObservation("turn", {...}, { asType: "span" })` 并赋值给 `activeTurn`。
-  - 实现 `finishTurnObservation(event)`：结束 `activeTurn` 并将其置空。
-- **`src/handlers/generation.ts` & `src/handlers/tool.ts`**:
-  - 在创建 `llm-generation` 和 `tool` 观察节点时，优先判断 `state.agentState.activeTurn` 是否存在，若存在则调用 `activeTurn.startObservation`，否则降级使用 `root.startObservation`。
-- **`index.ts`**:
-  - 注册 `turn_start` 事件，调用 `startTurnObservation`。
-  - 在现有的 `turn_end` 监听器中，除了处理 Fallback Generation，还需要调用 `finishTurnObservation`。
-
-### 3.2 精准追踪 TTFT (首字生成时间)
-记录模型流式输出第一块 Chunk 的时间，用于计算 TTFT。
-- **`src/types.ts`**:
-  - 在 `GenerationState` 中增加 `ttftRecorded?: boolean` 标志位。
-- **`src/handlers/generation.ts`**:
-  - 新增 `recordTTFT(event)` 函数：获取当前 `activeGeneration`，若 `ttftRecorded` 为 false/undefined，则调用 `generation.observation.update({ completionStartTime: new Date() })`，并标记 `ttftRecorded = true`。
-- **`index.ts`**:
-  - 在 `message_update` 事件监听器中，除了原有的提取逻辑外，新增调用 `recordTTFT(event)`。
-
-### 3.3 异常流闭环：Provider 请求级错误处理
-防止因 Provider HTTP 请求失败导致 Generation 永远处于开启状态。
-- **`src/handlers/generation.ts`**:
-  - 修改 `updateGenerationMetadata(event)` 函数。在提取完 metadata 后，检查 `metadata.status`。
-  - 如果 `status >= 400` 或者存在明确的 error 信息，立刻将该 Generation 的状态设为 `level: "ERROR"`，附加 `statusMessage`，并调用 `.end()` 提前闭合它，同时设置 `ended = true`。
-
-### 3.4 完善上下文信息：上报 System Prompt
-将 System Prompt 纳入 Trace 的元数据或输入中，方便回溯。
-- **`src/handlers/agent.ts`**:
-  - 修改 `startAgentRun(event, ctx)`。
-  - 增加 `const systemPrompt = await ctx.getSystemPrompt();`。
-  - 在 `root` Trace 的 `metadata` 中增加 `systemPrompt: truncate(systemPrompt, MAX_TOOL_PAYLOAD_LENGTH)`。
-
-### 3.5 Session 边缘生命周期与 Compact 处理
-完善 Pi 扩展 API 提供的各类会话切换与上下文管理事件。
-- **`index.ts`**:
-  - 增加 `session_before_switch` 和 `session_before_fork` 的事件监听。当触发这些事件时，表明当前会话即将被替换，调用 `closeDanglingObservations("Session switched or forked")` 提前闭合所有挂起的节点，并调用 `resetRunState()`。
-  - 增加 `session_compact` 事件监听。如果当前 `state.agentState.root` 存在，调用 `root.startObservation("session_compact", { level: "DEFAULT", statusMessage: "Context was compacted" }, { asType: "span" }).end()`，在 Trace 中记录下压缩动作发生的时机。
-
-## 4. 假设与决策
-- **决策**: Turn Span 的命名直接使用 `"turn"`，类型使用 `span`，这样在 Langfuse 的甘特图中能清晰地包裹住内部的 Generation 和 Tool。
-- **决策**: TTFT 使用系统当前时间 `new Date()`。尽管存在微小的事件传递延迟，但在 Node.js 环境下已足够精确。
-- **假设**: `ctx.getSystemPrompt()` 是异步方法，在 `before_agent_start` 和 `agent_start` 中可以通过 `await` 正常获取。
-- **决策**: 对于 Session Lifecycle 的处理，统一视作强行终止当前 Agent Run 的执行，因此复用 `closeDanglingObservations` 逻辑以保证不会出现悬空（Dangling）的 Trace/Span。
-
-## 5. 验收标准
-1. 在代码中实现上述 5 项修改，且不破坏现有 TypeScript 编译。
-2. 运行 Pi Agent 进行一次多轮对话（调用工具），能够在 Langfuse 观察到 `Trace -> Turn -> Generation/Tool` 的层级结构。
-3. Langfuse 的 Generation 详情中能够看到 `Time to First Token (TTFT)`。
-4. Trace 的 Metadata 中包含 `systemPrompt` 字段。
-5. 通过 `/new` 或 `/compact` 时，控制台不报挂起节点相关的警告。

package/.trae/documents/pi-langfuse-refactor.md

@@ -1,78 +0,0 @@
-# Pi-Langfuse 代码重构与拆分计划
-
-## 摘要 (Summary)
-将当前长达 1105 行的单文件 `index.ts` 重构并按功能职责拆分至 `src/` 目录下的多个模块中。保留根目录的 `index.ts` 作为 Pi 扩展的纯入口文件。此举将极大提升代码的可读性和可维护性。
-
-## 当前状态分析 (Current State Analysis)
-目前 `index.ts` 是一个单文件巨石（Monolith），包含了以下所有逻辑：
-1. 本地与环境变量配置读取
-2. TypeScript 接口声明（`Config`, `AgentState`, `LangfuseObservation` 等）
-3. 全局可变状态（如 `agentState`, `currentSessionId`, 各类计数器）
-4. Langfuse SDK 的懒加载与生命周期管理
-5. 数据格式化、截断与负载提取工具函数
-6. Agent、Generation 和 Tool 各自的观测事件处理器
-7. Pi 扩展命令注册与生命周期事件监听
-
-所有逻辑混合在一起，导致状态变更难以追踪，且由于闭包共享了大量模块级状态，修改代码容易引入隐藏的副作用。
-
-## 提议更改 (Proposed Changes)
-
-### 1. 更新项目配置
-- 修改 `tsconfig.json`：在 `include` 中增加 `"src/**/*.ts"`，以包含新的源码目录。
-- **依赖引用规范**：由于 `tsconfig.json` 配置了 `"moduleResolution": "NodeNext"`，所有内部文件导入必须显式带有 `.js` 后缀（例如 `import { state } from "./state.js"`）。
-
-### 2. 建立 `src/` 目录结构并拆分职责
-计划新建如下文件与目录：
-
-- **`src/types.ts`**
-  - **内容**：提取所有的 Interface 和 Type 定义。
-  - **包含**：`Config`, `LangfuseObservation`, `ObservationUpdate`, `LangfuseScoreClient`, `LangfuseRuntime`, `GenerationState`, `ToolState`, `AgentState`。
-
-- **`src/constants.ts`**
-  - **内容**：提取所有魔法数字和常量配置。
-  - **包含**：`EXT_DIR`, `CONFIG_PATH`, `DEFAULT_LANGFUSE_HOST`, `MAX_STRING_LENGTH` 等。
-
-- **`src/state.ts`**
-  - **内容**：统一管理所有全局可变状态。
-  - **实现方式**：将原来的 `let agentState`, `let currentSessionId` 等包裹在一个 `export const state = { ... }` 对象中，确保跨模块引用时状态一致。
-  - **包含函数**：`resetRunState`, `computeEvaluationScores`。
-
-- **`src/utils.ts`**
-  - **内容**：集中存放与状态无关的纯工具函数。
-  - **包含**：`truncate`, `tryParseJson`, `shapePayload`, `safeSerialize`，以及一系列解析函数（`extractTextContent`, `extractToolCalls`, `getToolCallId` 等）。
-
-- **`src/config.ts`**
-  - **内容**：负责配置读取与持久化，以及与 Pi UI 的交互提示。
-  - **包含**：`loadConfigFromFile`, `loadConfigFromEnv`, `saveConfig`, `ensureConfig`, `promptForConfig`。
-
-- **`src/langfuse.ts`**
-  - **内容**：Langfuse SDK 客户端封装。
-  - **包含**：`getRuntime` (单例模式加载 SDK)、`shutdownRuntime`、`sendScore`。
-
-- **`src/handlers/agent.ts`**
-  - **内容**：Agent 生命周期的事件逻辑。
-  - **包含**：`startAgentRun`, `finishAgentRun`, `updateTraceIO`。
-
-- **`src/handlers/generation.ts`**
-  - **内容**：模型生成 (Generation) 相关的生命周期逻辑。
-  - **包含**：`getOpenGeneration`, `startGeneration`, `updateGenerationMetadata`, `finishGenerationFromMessage`, `createFallbackGenerationFromTurn`。
-
-- **`src/handlers/tool.ts`**
-  - **内容**：工具调用 (Tool) 相关的逻辑。
-  - **包含**：`startToolObservation`, `finishToolObservation`, `closeDanglingObservations`。
-
-### 3. 精简根目录 `index.ts`
-- **内容**：将其转换为纯粹的事件路由中心。
-- **改动**：删除原有的业务实现，改为从 `src/` 各个模块导入必要的 handler。保留默认导出的扩展注册函数 `export default async function (pi: ExtensionAPI)`，并在其中通过 `pi.on` 和 `pi.registerCommand` 将事件委派给对应的处理函数。
-
-## 假设与决策 (Assumptions & Decisions)
-- **零行为变更**：本次重构仅做结构上的梳理，不修改任何核心逻辑、状态变更时机或事件 payload 的生成规则，从而保证与当前 Langfuse 的数据对接一致。
-- **状态管理**：采用共享的 `state` 单例对象替代原本的顶层变量，以最少的改动适配多文件架构。
-- **兼容性**：保留根目录的 `index.ts` 以兼容现有的 `package.json` 中的 `pi.extensions` 配置，无需修改发布行为。
-
-## 验证步骤 (Verification steps)
-1. 运行 `npm run typecheck` 确认代码拆分后无 TypeScript 编译及引入报错。
-2. 开启 Pi CLI (`pi "test prompt"`) 并挂载该本地扩展，验证：
-   - 配置初始化弹窗或环境变量读取是否正常工作。
-   - 工具调用、LLM 生成以及会话结束时的逻辑是否无异常抛出。
-3. 登录 Langfuse 控制面板，核对新产生的 trace 数据结构（agent、generation、tool observations 及打分数据）是否完整，未出现状态泄漏或丢失。