@narumitw/pi-langfuse 0.50.5 → 0.51.0

package/dist/index.ts

@@ -1,232 +1,65 @@
 // @generated by scripts/build-runtime.mjs; do not edit.
 // @ts-nocheck -- the generated entry uses a .ts extension for Pi's Jiti loader.
+import {
+  DEFAULT_BASE_URL,
+  createLangfuseRuntimeFromBackend,
+  getLangfuseRuntimeInternal,
+  loadLangfuseConfig,
+  normalizeLangfuseConfig,
+  writeLangfuseConfig
+} from "./chunks/chunk-IASLJKKB.js";
 
-// src/config.ts
-import { randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-var CONFIG_FILE_NAME = "pi-langfuse.json";
-var DEFAULT_BASE_URL = "https://us.cloud.langfuse.com";
-function langfuseConfigPath() {
-  return join(getAgentDir(), CONFIG_FILE_NAME);
-}
-var configSaveQueues = /* @__PURE__ */ new Map();
-function writeLangfuseConfig(patch, path = langfuseConfigPath()) {
-  const previous = configSaveQueues.get(path) ?? Promise.resolve();
-  const operation = previous.then(() => writeLangfuseConfigNow(patch, path));
-  const tail = operation.then(
-    () => void 0,
-    () => void 0
-  );
-  configSaveQueues.set(path, tail);
-  void tail.then(() => {
-    if (configSaveQueues.get(path) === tail) configSaveQueues.delete(path);
-  });
-  return operation;
-}
-async function writeLangfuseConfigNow(patch, path) {
-  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,
-    userId: _userId,
-    captureContent: _captureContent,
-    ...unknownFields
-  } = currentDocument;
-  const nextDocument = { ...unknownFields, ...normalized.config };
-  await mkdir(dirname(path), { recursive: true, mode: 448 });
-  const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
-  try {
-    await writeFile(tempPath, `${JSON.stringify(nextDocument, null, 2)}
-`, {
-      encoding: "utf8",
-      mode: 384
-    });
-    await chmod(tempPath, 384);
-    await rename(tempPath, path);
-    return normalized.config;
-  } catch (error) {
-    await rm(tempPath, { force: true }).catch(() => void 0);
-    throw error;
-  }
-}
-async function readLangfuseDocumentForUpdate(path) {
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(path, "utf8"));
-  } 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 };
-}
-async function loadLangfuseConfig(path = langfuseConfigPath()) {
-  await configSaveQueues.get(path);
-  const warnings = [];
-  const permissionFailure = await ensurePrivatePermissions(path, warnings);
-  if (permissionFailure) {
-    return {
-      ok: false,
-      path,
-      warnings,
-      reason: `Refusing to load credentials: ${permissionFailure}`
-    };
-  }
-  let text;
-  try {
-    text = await readFile(path, "utf8");
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") {
-      return { ok: false, path, warnings, reason: `Configuration file not found: ${path}` };
-    }
-    return {
-      ok: false,
-      path,
-      warnings,
-      reason: `Failed to read ${path}: ${formatError(error)}`
-    };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } 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 };
-}
-function normalizeLangfuseConfig(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    return { ok: false, reason: "pi-langfuse.json must contain a JSON object." };
-  }
-  const input = value;
-  const publicKey = normalizeString(input.publicKey);
-  const secretKey = normalizeString(input.secretKey);
-  if (!publicKey) {
-    return { ok: false, reason: "pi-langfuse.json requires a literal publicKey string." };
-  }
-  if (!secretKey) {
-    return { ok: false, reason: "pi-langfuse.json requires a literal secretKey string." };
-  }
-  if (isInterpolation(publicKey)) {
-    return {
-      ok: false,
-      reason: "pi-langfuse.json publicKey must be literal; environment and command interpolation are not supported."
-    };
-  }
-  if (isInterpolation(secretKey)) {
-    return {
-      ok: false,
-      reason: "pi-langfuse.json secretKey must be literal; environment and command interpolation are not supported."
-    };
-  }
-  const rawBaseUrl = input.baseUrl === void 0 ? DEFAULT_BASE_URL : normalizeString(input.baseUrl);
-  if (!rawBaseUrl) {
-    return { ok: false, reason: "pi-langfuse.json baseUrl must be a non-empty string." };
-  }
-  const baseUrl = normalizeBaseUrl(rawBaseUrl);
-  if (!baseUrl) {
-    return {
-      ok: false,
-      reason: "pi-langfuse.json baseUrl must use HTTP or HTTPS without credentials, a query, or a fragment."
-    };
-  }
-  if (input.captureContent !== void 0 && typeof input.captureContent !== "boolean") {
-    return { ok: false, reason: "pi-langfuse.json captureContent must be a boolean." };
-  }
-  const environment = optionalString(input.environment, "environment");
-  if (!environment.ok) return environment;
-  if (environment.value && (environment.value.length > 40 || !/^(?!langfuse)[a-z0-9_-]+$/u.test(environment.value))) {
+// src/git.ts
+var GIT_LOOKUP_TIMEOUT_MS = 1e3;
+var MAX_GIT_BRANCH_LENGTH = 256;
+async function resolveGitMetadata(exec, cwd) {
+  const [branchResult, commit] = await Promise.all([resolveGitBranch(exec, cwd), resolveGitCommit(exec, cwd)]);
+  if (!branchResult.resolved) return void 0;
+  if (branchResult.branch) {
     return {
-      ok: false,
-      reason: "pi-langfuse.json environment must be at most 40 lowercase letters, numbers, hyphens, or underscores and must not start with langfuse."
+      branch: branchResult.branch,
+      ...commit ? { commit } : {},
+      detached: false
     };
   }
-  const release = optionalString(input.release, "release");
-  if (!release.ok) return release;
-  const userId = optionalString(input.userId, "userId");
-  if (!userId.ok) return userId;
-  if (userId.value && userId.value.length > 200) {
-    return { ok: false, reason: "pi-langfuse.json userId must be at most 200 characters." };
-  }
-  return {
-    ok: true,
-    config: {
-      publicKey,
-      secretKey,
-      baseUrl,
-      ...environment.value ? { environment: environment.value } : {},
-      ...release.value ? { release: release.value } : {},
-      ...userId.value ? { userId: userId.value } : {},
-      captureContent: input.captureContent ?? true
-    }
-  };
+  return commit ? { commit, detached: true } : void 0;
 }
-async function ensurePrivatePermissions(path, warnings) {
+async function resolveGitBranch(exec, cwd) {
   try {
-    const file = await stat(path);
-    if ((file.mode & 511) !== 384) {
-      await chmod(path, 384);
-      const repaired = await stat(path);
-      if ((repaired.mode & 511) !== 384) {
-        throw new Error(`permissions remained ${(repaired.mode & 511).toString(8)}`);
-      }
-      warnings.push(`Restricted ${path} permissions to 0600.`);
-    }
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") return void 0;
-    const failure = `Failed to enforce 0600 permissions for ${path}: ${formatError(error)}`;
-    warnings.push(failure);
-    return failure;
+    const result = await exec("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
+      cwd,
+      timeout: GIT_LOOKUP_TIMEOUT_MS
+    });
+    if (result.killed) return { resolved: false };
+    if (result.code === 1) return { resolved: true };
+    if (result.code !== 0) return { resolved: false };
+    const branch = normalizeGitBranch(result.stdout);
+    return branch ? { resolved: true, branch } : { resolved: false };
+  } catch {
+    return { resolved: false };
   }
-  return void 0;
 }
-function normalizeBaseUrl(value) {
+async function resolveGitCommit(exec, cwd) {
   try {
-    const url = new URL(value);
-    if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
-    if (url.username || url.password || url.search || url.hash) return void 0;
-    return url.toString().replace(/\/+$/, "");
+    const result = await exec("git", ["rev-parse", "--verify", "--short=12", "HEAD"], {
+      cwd,
+      timeout: GIT_LOOKUP_TIMEOUT_MS
+    });
+    if (result.code !== 0 || result.killed) return void 0;
+    const commit = result.stdout.trim();
+    return /^[0-9a-f]{4,64}$/iu.test(commit) ? commit.toLowerCase() : void 0;
   } catch {
     return void 0;
   }
 }
-function optionalString(value, name) {
-  if (value === void 0) return { ok: true };
-  const normalized = normalizeString(value);
-  return normalized ? { ok: true, value: normalized } : { ok: false, reason: `pi-langfuse.json ${name} must be a non-empty string.` };
-}
-function normalizeString(value) {
-  return typeof value === "string" && value.trim() ? value.trim() : void 0;
-}
-function isInterpolation(value) {
-  return value.startsWith("$") || value.startsWith("!");
-}
-function isNodeError(error) {
-  return error instanceof Error && "code" in error;
-}
-function formatError(error) {
-  return error instanceof Error ? error.message : String(error);
+function normalizeGitBranch(value) {
+  const branch = value.trim();
+  if (!branch || branch.length > MAX_GIT_BRANCH_LENGTH) return void 0;
+  for (const character of branch) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code <= 31 || code === 127) return void 0;
+  }
+  return branch;
 }
 
 // src/sanitizer.ts
@@ -249,9 +82,7 @@ function sanitize(value, active, depth, budget) {
     return consume(value, budget);
   }
   if (typeof value === "string") {
-    const bounded = truncateString(value, Math.min(MAX_STRING_LENGTH, budget.remaining));
-    const redacted = bounded.replace(BASE64_DATA_URI, BASE64_DATA_URI_OMITTED);
-    return consume(redacted, budget);
+    return consume(sanitizeString(value, Math.min(MAX_STRING_LENGTH, budget.remaining)), budget);
   }
   if (typeof value === "bigint") return consume(value.toString(), budget);
   if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol") {
@@ -301,12 +132,13 @@ function sanitize(value, active, depth, budget) {
           omitted = true;
           break;
         }
-        budget.remaining -= keyBytes + 4;
+        const sanitizedKey = sanitizeString(key, keyBudget);
+        budget.remaining -= byteLength(sanitizedKey) + 4;
         const property = readProperty(record, key);
         if (redactData && key === "data") {
-          output[key] = consume("[base64 omitted]", budget);
-        } else if (!property.ok) output[key] = consume("[unreadable property]", budget);
-        else output[key] = sanitize(property.value, active, depth + 1, budget);
+          output[sanitizedKey] = consume("[base64 omitted]", budget);
+        } else if (!property.ok) output[sanitizedKey] = consume("[unreadable property]", budget);
+        else output[sanitizedKey] = sanitize(property.value, active, depth + 1, budget);
         processed += 1;
       }
     } catch {
@@ -338,6 +170,9 @@ function consume(value, budget) {
   budget.remaining -= size;
   return value;
 }
+function sanitizeString(value, maxBytes) {
+  return truncateString(value, maxBytes).replace(BASE64_DATA_URI, BASE64_DATA_URI_OMITTED);
+}
 function truncateString(value, maxBytes) {
   const boundedPrefix = value.slice(0, maxBytes);
   if (boundedPrefix.length === value.length && byteLength(boundedPrefix) <= maxBytes) {
@@ -410,11 +245,7 @@ var TraceRecorder = class {
   counters = emptyCounters();
   startObservation(name, attributes, options) {
     const { sessionId, userId } = this.context;
-    return this.backend.start(
-      name,
-      { ...attributes, sessionId, ...userId ? { userId } : {} },
-      options
-    );
+    return this.backend.start(name, { ...attributes, sessionId, ...userId ? { userId } : {} }, options);
   }
   hasActiveTrace() {
     return this.root !== void 0;
@@ -436,6 +267,7 @@ var TraceRecorder = class {
       ...hasItems(input.images) ? { images: input.images } : {}
     });
     const metadata = {
+      ...customTraceMetadata(this.context.metadata),
       "pi.cwd": this.context.cwd,
       ...input.git?.branch ? { "pi.git.branch": input.git.branch } : {},
       ...input.git?.commit ? { "pi.git.commit": input.git.commit } : {},
@@ -443,6 +275,7 @@ var TraceRecorder = class {
       "pi.mode": this.context.mode,
       ...input.model?.id ? { "pi.model": input.model.id } : {},
       ...input.model?.provider ? { "pi.provider": input.model.provider } : {},
+      ...input.requestId ? { "pi.request.id": input.requestId } : {},
       "pi.session.id": this.context.sessionId,
       "pi.trace.schema_version": Number(TRACE_SCHEMA_VERSION),
       ...snapshotMetadata("start", input.snapshot)
@@ -451,14 +284,21 @@ var TraceRecorder = class {
     const gitTag = input.git?.branch ? `branch:${input.git.branch}` : input.git?.detached ? "git:detached" : void 0;
     this.root = this.startObservation("pi.agent", attributes, { asType: "agent" });
     this.root.updateTrace?.({
-      name: "pi.trace",
+      name: normalizeTraceName(this.context.traceName),
       sessionId: this.context.sessionId,
       ...this.context.userId ? { userId: this.context.userId } : {},
       version: TRACE_SCHEMA_VERSION,
       input: traceInput,
       metadata,
-      tags: ["pi", ...gitTag ? [gitTag] : []]
+      tags: traceTags(this.context.tags, gitTag)
     });
+    const traceId = this.root.traceId;
+    if (traceId && this.context.onTraceId) {
+      try {
+        void Promise.resolve(this.context.onTraceId(traceId)).catch(() => void 0);
+      } catch {
+      }
+    }
   }
   beginAttempt(input = {}) {
     if (!this.root) return;
@@ -548,7 +388,11 @@ var TraceRecorder = class {
         ...Object.keys(requestMetadata).length > 0 ? { metadata: requestMetadata } : {},
         version: TRACE_SCHEMA_VERSION
       },
-      { asType: "generation", parent: this.turn ?? this.attempt ?? this.root }
+      {
+        asType: "generation",
+        parent: this.turn ?? this.attempt ?? this.root,
+        ...input.startedAt === void 0 ? {} : { startTime: new Date(input.startedAt) }
+      }
     );
     this.generation = {
       observation,
@@ -682,10 +526,7 @@ var TraceRecorder = class {
       metadata: {
         "pi.tool.progress_update_count": tool.progressUpdates,
         ...tool.firstProgressAt !== void 0 ? {
-          "pi.tool.time_to_first_progress_ms": Math.max(
-            0,
-            tool.firstProgressAt - tool.startedAt
-          )
+          "pi.tool.time_to_first_progress_ms": Math.max(0, tool.firstProgressAt - tool.startedAt)
         } : {}
       },
       ...result.isError ? { level: "ERROR", statusMessage: "Pi tool execution failed." } : {}
@@ -753,12 +594,8 @@ var TraceRecorder = class {
   interrupt(statusMessage, snapshot) {
     this.closeActiveTrace(statusMessage, snapshot, "interrupted");
   }
-  async flush() {
-    await this.backend.forceFlush();
-  }
-  async shutdown(snapshot) {
-    this.closeActiveTrace("Pi shut down before the active trace settled.", snapshot, "interrupted");
-    await this.backend.shutdown();
+  dispose(statusMessage = "Pi session ended before the active trace settled.", snapshot) {
+    this.closeActiveTrace(statusMessage, snapshot, "interrupted");
   }
   closeActiveTrace(statusMessage, snapshot, forcedOutcome) {
     this.closeTurn(statusMessage ?? "Pi turn ended when the agent run settled.");
@@ -850,10 +687,7 @@ var TraceRecorder = class {
         metadata: {
           "pi.tool.progress_update_count": tool.progressUpdates,
           ...tool.firstProgressAt !== void 0 ? {
-            "pi.tool.time_to_first_progress_ms": Math.max(
-              0,
-              tool.firstProgressAt - tool.startedAt
-            )
+            "pi.tool.time_to_first_progress_ms": Math.max(0, tool.firstProgressAt - tool.startedAt)
           } : {}
         }
       });
@@ -884,6 +718,24 @@ var TraceRecorder = class {
     return this.context.captureContent ? sanitizeTraceValue(value) : CONTENT_DISABLED;
   }
 };
+function normalizeTraceName(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "pi.trace";
+}
+function traceTags(customTags, gitTag) {
+  const tags = ["pi", ...gitTag ? [gitTag] : [], ...customTags ?? []];
+  return [...new Set(tags.map(sanitizeTraceTag).filter((tag) => tag !== void 0))];
+}
+function sanitizeTraceTag(value) {
+  if (typeof value !== "string" || !value.trim()) return void 0;
+  const sanitized = sanitizeTraceValue(value.trim());
+  return typeof sanitized === "string" && sanitized.trim() ? sanitized.trim() : void 0;
+}
+function customTraceMetadata(metadata) {
+  if (!metadata) return {};
+  const sanitized = sanitizeTraceValue(metadata);
+  if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) return {};
+  return Object.fromEntries(Object.entries(sanitized).filter(([key]) => !key.startsWith("pi.")));
+}
 function generationHttpMetadata(state) {
   const finalStatus = state.statuses.at(-1);
   return {
@@ -945,9 +797,7 @@ function severityForOutcome(outcome, statusMessage) {
   };
 }
 function prefixRecord(prefix, values) {
-  return Object.fromEntries(
-    Object.entries(values).map(([key, value]) => [`${prefix}.${key}`, value])
-  );
+  return Object.fromEntries(Object.entries(values).map(([key, value]) => [`${prefix}.${key}`, value]));
 }
 function truncateString2(value, maxBytes) {
   const boundedPrefix = value.slice(0, maxBytes);
@@ -976,9 +826,7 @@ function numericRecord(values) {
 }
 function positiveNumericRecord(values) {
   return Object.fromEntries(
-    Object.entries(values).filter(
-      (entry) => finiteNumber(entry[1]) && entry[1] > 0
-    )
+    Object.entries(values).filter((entry) => finiteNumber(entry[1]) && entry[1] > 0)
   );
 }
 function finiteNumber(value) {
@@ -1000,235 +848,258 @@ function emptyCounters() {
   };
 }
 
-// src/langfuse.ts
-var FLUSH_ACTION = "Flush completed traces for this session";
-var SET_UP_ACTION = "Set up Langfuse for this Pi agent directory (restart required)";
-var UPDATE_ACTION = "Update Langfuse for this Pi agent directory (restart required)";
-var HELP_ACTION = "Show setup and privacy help";
-function createLangfuseExtension(dependencies = {}) {
-  const loadConfig = dependencies.loadConfig ?? loadLangfuseConfig;
-  const writeConfig = dependencies.writeConfig ?? writeLangfuseConfig;
-  const createBackend = dependencies.createBackend ?? (async (config) => {
-    const { createProductionBackend } = await import("./chunks/runtime-247EMSG3.js");
-    return createProductionBackend(config);
+// src/pi-session.ts
+function createPiLangfuseSession(runtime, options = {}) {
+  const sessionOptions = snapshotSessionOptions(options);
+  return createPiLangfuseSessionController({
+    resolveSession: async () => ({ runtime, options: sessionOptions })
   });
-  return function langfuse(pi) {
-    const resolveGit = dependencies.resolveGitMetadata ?? ((cwd) => resolveGitMetadata((command, args, options) => pi.exec(command, args, options), cwd));
-    let recorder;
-    let activeConfig;
-    let configPath;
-    let initializationError;
-    let hasStoredConfig = false;
-    let configurationNotice;
-    let sessionGeneration = 0;
-    let menuController = new AbortController();
-    let configWriteQueue = Promise.resolve();
-    let nextAttemptReason;
-    async function showLangfuseMenu(ctx) {
-      if (!ctx.hasUI) {
-        ctx.ui.notify(
-          formatNonInteractiveStatus(activeConfig, configPath, initializationError),
-          "warning"
-        );
-        return;
+}
+function createPiLangfuseSessionController(options) {
+  let binding;
+  let runtimeForShutdown;
+  let ownerRegistration;
+  let pendingInitialization;
+  const outstandingInitializations = /* @__PURE__ */ new Set();
+  let disposePromise;
+  let disposed = false;
+  let sessionGeneration = 0;
+  let requestId;
+  let requestIdRevision = 0;
+  let nextAttemptReason;
+  let lastSnapshot;
+  let pendingProviderGeneration;
+  const controller = {
+    extension(pi) {
+      if (disposed) throw new Error("A disposed Pi Langfuse session controller cannot be bound.");
+      registerHooks(pi);
+    },
+    setRequestId(value) {
+      requestId = normalizeOptionalString(value);
+      requestIdRevision += 1;
+    },
+    dispose() {
+      if (disposePromise) return disposePromise;
+      disposed = true;
+      const initializations = invalidateAllInitializations("disposed");
+      ownerRegistration = void 0;
+      sessionGeneration += 1;
+      closeBinding(binding, "Pi Langfuse session controller was disposed.", lastSnapshot);
+      runtimeForShutdown = void 0;
+      disposePromise = joinInitializations(initializations);
+      return disposePromise;
+    },
+    get active() {
+      return binding !== void 0;
+    },
+    get runtime() {
+      return binding?.runtime;
+    },
+    async flush() {
+      const runtime = binding?.runtime;
+      if (!runtime) throw new Error("Langfuse tracing is not enabled for this session.");
+      await runtime.flush();
+    }
+  };
+  function closeBinding(target, statusMessage, snapshot) {
+    if (!target) return;
+    const wasCurrent = binding === target;
+    if (wasCurrent) {
+      binding = void 0;
+      pendingProviderGeneration = void 0;
+    }
+    target.releaseRuntime();
+    target.recorder.dispose(statusMessage, snapshot);
+    if (wasCurrent) nextAttemptReason = void 0;
+  }
+  function invalidatePendingInitialization(reason) {
+    if (!pendingInitialization) return;
+    pendingInitialization.current = false;
+    pendingInitialization.reason = reason;
+    pendingInitialization = void 0;
+  }
+  function invalidateAllInitializations(reason) {
+    const initializations = [...outstandingInitializations];
+    for (const initialization of initializations) {
+      initialization.current = false;
+      initialization.reason = reason;
+    }
+    pendingInitialization = void 0;
+    return initializations;
+  }
+  function createPendingInitialization() {
+    let complete;
+    const completion = new Promise((resolve) => {
+      complete = resolve;
+    });
+    const initialization = { current: true, completion, complete };
+    outstandingInitializations.add(initialization);
+    return initialization;
+  }
+  async function joinInitializations(initializations) {
+    const results = await Promise.all(initializations.map(({ completion }) => completion));
+    const errors = results.flatMap((result) => result.ok ? [] : [result.error]);
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, "Pi Langfuse session initialization cleanup failed.");
+  }
+  async function initializeSession(registration, initialization, ctx) {
+    const generation = ++sessionGeneration;
+    closeBinding(binding, "Pi session was replaced before shutdown completed.", lastSnapshot);
+    lastSnapshot = contextSnapshot(ctx);
+    nextAttemptReason = void 0;
+    options.onSessionStart?.();
+    const isCurrent = () => !disposed && initialization.current && ownerRegistration === registration && generation === sessionGeneration;
+    let resolved;
+    try {
+      resolved = await options.resolveSession(ctx, isCurrent);
+    } catch (error) {
+      if (isCurrent()) options.onInitializationError?.(error, ctx);
+      return;
+    }
+    if (!isCurrent()) {
+      const reason = initialization.reason ?? "replaced";
+      if (resolved && options.shutdownRuntimeOnQuit && reason !== "quit" && reason !== "disposed" && (!runtimeForShutdown || runtimeForShutdown.closed)) {
+        runtimeForShutdown = resolved.runtime;
       }
-      const menuGeneration = sessionGeneration;
-      const menuSignal = menuController.signal;
-      const isCurrent = () => menuGeneration === sessionGeneration && !menuSignal.aborted;
-      const { defineMenu, runMenu } = await import("@narumitw/pi-tui-kit");
-      if (!isCurrent()) return;
-      const menu = defineMenu({
-        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" }] : [],
-              {
-                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: ${formatError2(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 : void 0,
-              () => menuGeneration === sessionGeneration
-            );
-            if (!next || menuGeneration !== sessionGeneration) return { kind: "close" };
-            try {
-              const write = configWriteQueue.then(() => writeConfig(next, loaded.path));
-              configWriteQueue = write.then(
-                () => void 0,
-                () => void 0
-              );
-              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: ${formatError2(error, next)}`, "error");
-            }
-            return { kind: "close" };
-          },
-          help: async () => {
-            ctx.ui.notify(formatHelp(configPath), "info");
-            return { kind: "close" };
-          }
-        }
-      });
-      await runMenu(ctx, menu, {
-        getState: () => void 0,
-        signal: menuSignal,
-        isCurrent
+      await resolved?.releaseIfStale?.(reason);
+      return;
+    }
+    if (!resolved) {
+      options.onSessionUnavailable?.();
+      return;
+    }
+    try {
+      const internal = getLangfuseRuntimeInternal(resolved.runtime);
+      const recorderOptions = createRecorderOptions(ctx, resolved.options);
+      const recorder = new TraceRecorder(internal.backend, recorderOptions);
+      const nextBinding = {};
+      const releaseRuntime = internal.registerSession((statusMessage) => {
+        closeBinding(nextBinding, statusMessage, lastSnapshot);
       });
+      Object.assign(nextBinding, { registration, recorder, runtime: resolved.runtime, releaseRuntime });
+      if (!isCurrent()) {
+        releaseRuntime();
+        return;
+      }
+      binding = nextBinding;
+      if (options.shutdownRuntimeOnQuit) runtimeForShutdown = resolved.runtime;
+      options.onSessionReady?.(resolved);
+    } catch (error) {
+      if (isCurrent()) options.onInitializationError?.(error, ctx);
     }
-    pi.registerCommand("langfuse", {
-      description: "Open interactive Langfuse tracing controls",
-      handler: async (_args, ctx) => showLangfuseMenu(ctx)
-    });
+  }
+  function registerHooks(pi) {
+    const registration = {};
+    const activeRecorder = () => activeRecorderFor(registration);
     pi.on("session_start", async (_event, ctx) => {
-      const generation = ++sessionGeneration;
-      menuController.abort(new DOMException("Langfuse session replaced", "AbortError"));
-      menuController = new AbortController();
-      recorder = void 0;
-      activeConfig = void 0;
-      configPath = void 0;
-      initializationError = void 0;
-      hasStoredConfig = false;
-      configurationNotice = void 0;
-      nextAttemptReason = void 0;
-      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) {
-        initializationError = formatConfigError(result);
-        ctx.ui.notify(initializationError, "warning");
+      if (disposed) return;
+      pendingProviderGeneration = void 0;
+      if (ownerRegistration && ownerRegistration !== registration) {
+        options.onInitializationError?.(
+          new Error("A Pi Langfuse session controller cannot manage multiple active Pi sessions."),
+          ctx
+        );
         return;
       }
-      hasStoredConfig = true;
+      invalidatePendingInitialization("replaced");
+      ownerRegistration = registration;
+      const initialization = createPendingInitialization();
+      pendingInitialization = initialization;
+      let result = { ok: true };
       try {
-        const backend = await createBackend(result.config);
-        if (generation !== sessionGeneration) {
-          await backend.shutdown().catch(() => void 0);
-          return;
-        }
-        activeConfig = result.config;
-        recorder = new TraceRecorder(backend, {
-          sessionId: ctx.sessionManager.getSessionId(),
-          ...result.config.userId ? { userId: result.config.userId } : {},
-          cwd: ctx.cwd,
-          mode: ctx.mode,
-          captureContent: result.config.captureContent
-        });
+        await initializeSession(registration, initialization, ctx);
       } catch (error) {
-        if (generation !== sessionGeneration) return;
-        initializationError = `Langfuse tracing could not start: ${formatError2(error, result.config)}`;
-        ctx.ui.notify(initializationError, "warning");
+        result = { ok: false, error };
+        throw error;
+      } finally {
+        initialization.complete(result);
+        outstandingInitializations.delete(initialization);
+        if (pendingInitialization === initialization) pendingInitialization = void 0;
       }
     });
     pi.on("before_agent_start", async (event, ctx) => {
+      pendingProviderGeneration = void 0;
+      const active = ownerRegistration === registration ? binding : void 0;
+      if (!active || active.runtime.closed) return;
       nextAttemptReason = void 0;
-      const activeRecorder = recorder;
-      if (!activeRecorder) return;
-      const git = await resolveGit(ctx.cwd).catch(() => void 0);
-      if (recorder !== activeRecorder) return;
-      activeRecorder.beginAgent({
-        prompt: event.prompt,
-        images: event.images,
-        model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id, api: ctx.model.api } : void 0,
-        git,
-        snapshot: contextSnapshot(ctx)
+      const git = await (options.resolveGitMetadata ? options.resolveGitMetadata(pi, ctx.cwd) : resolveGitMetadata((command, args, execOptions) => pi.exec(command, args, execOptions), ctx.cwd)).catch(() => void 0);
+      if (ownerRegistration !== registration || binding !== active || active.runtime.closed) return;
+      lastSnapshot = contextSnapshot(ctx);
+      startRootTrace((nextRequestId) => {
+        active.recorder.beginAgent({
+          prompt: event.prompt,
+          images: event.images,
+          model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id, api: ctx.model.api } : void 0,
+          git,
+          snapshot: lastSnapshot,
+          ...nextRequestId ? { requestId: nextRequestId } : {}
+        });
       });
     });
     pi.on("agent_start", () => {
+      const recorder = activeRecorder();
       if (!recorder) return;
       recorder.beginAttempt(nextAttemptReason ? { reason: nextAttemptReason } : void 0);
       nextAttemptReason = void 0;
     });
     pi.on("turn_start", (event, ctx) => {
+      const recorder = activeRecorder();
       if (!recorder) return;
-      ensureActiveRun(recorder, ctx);
+      lastSnapshot = contextSnapshot(ctx);
+      ensureActiveRun(recorder, ctx, startRootTrace);
       recorder.beginTurn(event.turnIndex);
     });
     pi.on("before_provider_request", (event, ctx) => {
-      if (!recorder) return;
-      ensureActiveRun(recorder, ctx);
-      recorder.beginGeneration({
+      if (!activeRecorder()) return;
+      lastSnapshot = contextSnapshot(ctx);
+      pendingProviderGeneration = {
+        startedAt: Date.now(),
         payload: event.payload,
-        payloadStage: "before_provider_request",
         model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id, api: ctx.model.api } : void 0,
-        thinkingLevel: pi.getThinkingLevel()
-      });
+        thinkingLevel: pi.getThinkingLevel(),
+        responses: []
+      };
     });
     pi.on("after_provider_response", (event) => {
-      recorder?.recordProviderResponse(event.status, event.headers);
+      pendingProviderGeneration?.responses.push({ status: event.status, headers: event.headers });
+    });
+    pi.on("message_start", (event, ctx) => {
+      if (event.message.role === "assistant") claimPendingProviderGeneration(ctx, activeRecorder());
     });
-    pi.on("message_update", (event) => {
-      if (isRealOutputDelta(event.assistantMessageEvent)) recorder?.markGenerationFirstOutput();
+    pi.on("message_update", (event, ctx) => {
+      if (!isRealOutputDelta(event.assistantMessageEvent)) return;
+      const recorder = activeRecorder();
+      claimPendingProviderGeneration(ctx, recorder);
+      recorder?.markGenerationFirstOutput();
     });
-    pi.on("message_end", (event) => {
-      if (event.message.role === "assistant") recorder?.markGenerationEnd();
+    pi.on("message_end", (event, ctx) => {
+      if (event.message.role !== "assistant") return;
+      const recorder = activeRecorder();
+      claimPendingProviderGeneration(ctx, recorder);
+      recorder?.markGenerationEnd();
     });
-    pi.on("turn_end", (event) => {
-      if (event.message.role === "assistant") recorder?.finishAssistant(event.message);
-      recorder?.finishTurn(event.turnIndex, {
+    pi.on("turn_end", (event, ctx) => {
+      const recorder = activeRecorder();
+      if (!recorder) return;
+      if (event.message.role === "assistant") claimPendingProviderGeneration(ctx, recorder);
+      lastSnapshot = contextSnapshot(ctx);
+      if (event.message.role === "assistant") recorder.finishAssistant(event.message);
+      recorder.finishTurn(event.turnIndex, {
         message: event.message,
         toolResultCount: event.toolResults.length
       });
     });
     pi.on("tool_execution_start", (event) => {
-      recorder?.beginTool(event.toolCallId, event.toolName, event.args);
+      activeRecorder()?.beginTool(event.toolCallId, event.toolName, event.args);
     });
     pi.on("tool_execution_update", (event) => {
-      recorder?.recordToolProgress(event.toolCallId);
+      activeRecorder()?.recordToolProgress(event.toolCallId);
     });
     pi.on("tool_result", (event) => {
-      recorder?.recordToolInput(event.toolCallId, event.input);
+      activeRecorder()?.recordToolInput(event.toolCallId, event.input);
     });
     pi.on("tool_execution_end", (event) => {
-      recorder?.finishTool(event.toolCallId, {
+      activeRecorder()?.finishTool(event.toolCallId, {
         content: event.result.content,
         details: event.result.details,
         isError: event.isError
@@ -1236,10 +1107,10 @@ function createLangfuseExtension(dependencies = {}) {
     });
     pi.on("agent_end", (event) => {
       const message = findLastAssistant(event.messages);
-      recorder?.finishAttempt(message);
+      activeRecorder()?.finishAttempt(message);
     });
     pi.on("session_before_compact", (event) => {
-      recorder?.beginCompaction({
+      activeRecorder()?.beginCompaction({
         reason: event.reason,
         willRetry: event.willRetry,
         tokensBefore: event.preparation.tokensBefore,
@@ -1250,6 +1121,7 @@ function createLangfuseExtension(dependencies = {}) {
       });
     });
     pi.on("session_compact", (event) => {
+      const recorder = activeRecorder();
       const entry = event.compactionEntry;
       recorder?.finishCompaction({
         reason: event.reason,
@@ -1262,45 +1134,102 @@ function createLangfuseExtension(dependencies = {}) {
       if (event.willRetry && recorder?.hasActiveTrace()) nextAttemptReason = "post_compaction";
     });
     pi.on("agent_settled", (_event, ctx) => {
-      recorder?.settle(contextSnapshot(ctx));
+      const recorder = activeRecorder();
+      if (!recorder) return;
+      lastSnapshot = contextSnapshot(ctx);
+      recorder.settle(lastSnapshot);
+      pendingProviderGeneration = void 0;
       nextAttemptReason = void 0;
     });
     pi.on("session_shutdown", async (event, ctx) => {
+      if (ownerRegistration !== registration) return;
+      const initializations = invalidateAllInitializations(event.reason);
+      ownerRegistration = void 0;
       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) : void 0;
-      recorder = void 0;
-      activeConfig = void 0;
-      await pendingConfigWrite;
-      if (!activeRecorder) return;
+      options.onSessionShutdown?.();
+      const active = binding?.registration === registration ? binding : void 0;
+      const runtime = active?.runtime ?? runtimeForShutdown;
+      lastSnapshot = active ? contextSnapshot(ctx) : lastSnapshot;
+      closeBinding(
+        active,
+        event.reason === "quit" ? "Pi shut down before the active trace settled." : `Pi session ended before settlement (${event.reason}).`,
+        lastSnapshot
+      );
+      let beforeDisposeFailure;
       try {
-        if (event.reason === "quit") await activeRecorder.shutdown(shutdownSnapshot);
-        else {
-          activeRecorder.interrupt(
-            `Pi session ended before settlement (${event.reason}).`,
-            shutdownSnapshot
-          );
-          await activeRecorder.flush();
+        await options.beforeSessionDispose?.();
+      } catch (error) {
+        beforeDisposeFailure = { error };
+      }
+      try {
+        await joinInitializations(initializations);
+        if (disposed || generation !== sessionGeneration) return;
+        if (beforeDisposeFailure) throw beforeDisposeFailure.error;
+        if (runtime) {
+          if (event.reason === "quit" && options.shutdownRuntimeOnQuit) await runtime.shutdown();
+          else if (options.flushOnReplacement) await runtime.flush();
         }
       } catch (error) {
-        if (generation !== sessionGeneration) return;
-        ctx.ui.notify(
-          `Langfuse shutdown export failed: ${formatError2(error, shutdownConfig)}`,
-          "error"
-        );
+        if (!disposed && generation === sessionGeneration) options.onShutdownError?.(error, ctx);
       }
     });
+  }
+  function claimPendingProviderGeneration(ctx, recorder) {
+    const pending = pendingProviderGeneration;
+    if (!pending || !recorder) return;
+    pendingProviderGeneration = void 0;
+    ensureActiveRun(recorder, ctx, startRootTrace);
+    recorder.beginGeneration({
+      startedAt: pending.startedAt,
+      payload: pending.payload,
+      payloadStage: "before_provider_request",
+      model: pending.model,
+      thinkingLevel: pending.thinkingLevel
+    });
+    for (const response of pending.responses) recorder.recordProviderResponse(response.status, response.headers);
+  }
+  function startRootTrace(start) {
+    const revision = requestIdRevision;
+    const nextRequestId = requestId;
+    start(nextRequestId);
+    if (requestIdRevision === revision) requestId = void 0;
+  }
+  function activeRecorderFor(registration) {
+    return ownerRegistration === registration && binding?.registration === registration && !binding.runtime.closed ? binding.recorder : void 0;
+  }
+  return controller;
+}
+function createRecorderOptions(ctx, options = {}) {
+  const userId = normalizeUserId(options.userId);
+  return {
+    sessionId: normalizeOptionalString(options.sessionId) ?? ctx.sessionManager.getSessionId(),
+    ...userId ? { userId } : {},
+    cwd: ctx.cwd,
+    mode: ctx.mode,
+    captureContent: options.captureContent ?? true,
+    ...normalizeOptionalString(options.traceName) ? { traceName: normalizeOptionalString(options.traceName) } : {},
+    ...options.tags ? { tags: [...options.tags] } : {},
+    ...options.metadata ? { metadata: { ...options.metadata } } : {},
+    ...options.onTraceId ? { onTraceId: options.onTraceId } : {}
   };
 }
-function ensureActiveRun(recorder, ctx) {
+function snapshotSessionOptions(options) {
+  normalizeUserId(options.userId);
+  return {
+    ...options,
+    ...options.tags ? { tags: [...options.tags] } : {},
+    ...options.metadata ? { metadata: { ...options.metadata } } : {}
+  };
+}
+function ensureActiveRun(recorder, ctx, startRootTrace) {
   if (!recorder.hasActiveTrace()) {
-    recorder.beginAgent({
-      prompt: "[automatic continuation]",
-      model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id, api: ctx.model.api } : void 0,
-      snapshot: contextSnapshot(ctx)
+    startRootTrace((nextRequestId) => {
+      recorder.beginAgent({
+        prompt: "[automatic continuation]",
+        model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id, api: ctx.model.api } : void 0,
+        snapshot: contextSnapshot(ctx),
+        ...nextRequestId ? { requestId: nextRequestId } : {}
+      });
     });
   }
   if (!recorder.hasActiveAttempt()) recorder.beginAttempt();
@@ -1321,59 +1250,200 @@ function findLastAssistant(messages) {
 function isRealOutputDelta(event) {
   return (event.type === "text_delta" || event.type === "thinking_delta" || event.type === "toolcall_delta") && typeof event.delta === "string" && event.delta.length > 0;
 }
-var GIT_LOOKUP_TIMEOUT_MS = 1e3;
-var MAX_GIT_BRANCH_LENGTH = 256;
-async function resolveGitMetadata(exec, cwd) {
-  const [branchResult, commit] = await Promise.all([
-    resolveGitBranch(exec, cwd),
-    resolveGitCommit(exec, cwd)
-  ]);
-  if (!branchResult.resolved) return void 0;
-  if (branchResult.branch) {
-    return {
-      branch: branchResult.branch,
-      ...commit ? { commit } : {},
-      detached: false
-    };
-  }
-  return commit ? { commit, detached: true } : void 0;
+function normalizeUserId(value) {
+  const userId = normalizeOptionalString(value);
+  if (userId && userId.length > 200) throw new Error("Langfuse userId must be at most 200 characters.");
+  return userId;
 }
-async function resolveGitBranch(exec, cwd) {
-  try {
-    const result = await exec("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], {
-      cwd,
-      timeout: GIT_LOOKUP_TIMEOUT_MS
-    });
-    if (result.killed) return { resolved: false };
-    if (result.code === 1) return { resolved: true };
-    if (result.code !== 0) return { resolved: false };
-    const branch = normalizeGitBranch(result.stdout);
-    return branch ? { resolved: true, branch } : { resolved: false };
-  } catch {
-    return { resolved: false };
-  }
+function normalizeOptionalString(value) {
+  if (typeof value !== "string" || !value.trim()) return void 0;
+  const sanitized = sanitizeTraceValue(value.trim());
+  return typeof sanitized === "string" && sanitized.trim() ? sanitized.trim() : void 0;
 }
-async function resolveGitCommit(exec, cwd) {
-  try {
-    const result = await exec("git", ["rev-parse", "--verify", "--short=12", "HEAD"], {
-      cwd,
-      timeout: GIT_LOOKUP_TIMEOUT_MS
+
+// src/langfuse.ts
+var FLUSH_ACTION = "Flush completed traces for this session";
+var SET_UP_ACTION = "Set up Langfuse for this Pi agent directory (restart required)";
+var UPDATE_ACTION = "Update Langfuse for this Pi agent directory (restart required)";
+var HELP_ACTION = "Show setup and privacy help";
+function createLangfuseExtension(dependencies = {}) {
+  const loadConfig = dependencies.loadConfig ?? loadLangfuseConfig;
+  const writeConfig = dependencies.writeConfig ?? writeLangfuseConfig;
+  const resolveInjectedGitMetadata = dependencies.resolveGitMetadata;
+  return function langfuse(pi) {
+    let activeConfig;
+    let loadingConfig;
+    let runtimeConfigForShutdown;
+    let shutdownConfig;
+    let configPath;
+    let initializationError;
+    let hasStoredConfig = false;
+    let configurationNotice;
+    let sessionGeneration = 0;
+    let menuController = new AbortController();
+    let configWriteQueue = Promise.resolve();
+    const tracing = createPiLangfuseSessionController({
+      onSessionStart() {
+        sessionGeneration += 1;
+        menuController.abort(new DOMException("Langfuse session replaced", "AbortError"));
+        menuController = new AbortController();
+        activeConfig = void 0;
+        loadingConfig = void 0;
+        shutdownConfig = void 0;
+        configPath = void 0;
+        initializationError = void 0;
+        hasStoredConfig = false;
+        configurationNotice = void 0;
+      },
+      onSessionShutdown() {
+        sessionGeneration += 1;
+        menuController.abort(new DOMException("Langfuse session shut down", "AbortError"));
+        shutdownConfig = activeConfig ?? runtimeConfigForShutdown ?? loadingConfig;
+        activeConfig = void 0;
+      },
+      async resolveSession(ctx, isCurrent) {
+        await configWriteQueue;
+        if (!isCurrent()) return void 0;
+        const result = await loadConfig();
+        if (!isCurrent()) return void 0;
+        configPath = result.path;
+        for (const warning of result.warnings) ctx.ui.notify(warning, "warning");
+        if (!result.ok) {
+          initializationError = formatConfigError(result);
+          ctx.ui.notify(initializationError, "warning");
+          return void 0;
+        }
+        hasStoredConfig = true;
+        loadingConfig = result.config;
+        const createBackend = dependencies.createBackend;
+        const ownsRuntime = createBackend !== void 0;
+        const runtime = createBackend ? createLangfuseRuntimeFromBackend(await createBackend(result.config)) : await (await import("./chunks/runtime-6MIKLWNJ.js")).createLangfuseRuntime({ config: result.config, env: false });
+        if (isCurrent() || !runtimeConfigForShutdown) runtimeConfigForShutdown = result.config;
+        if (isCurrent()) {
+          activeConfig = result.config;
+          loadingConfig = void 0;
+        }
+        return {
+          runtime,
+          releaseIfStale: async (reason) => {
+            if (ownsRuntime || reason === "quit") await runtime.shutdown();
+          },
+          options: {
+            ...result.config.userId ? { userId: result.config.userId } : {},
+            captureContent: result.config.captureContent
+          }
+        };
+      },
+      ...resolveInjectedGitMetadata ? { resolveGitMetadata: (_pi, cwd) => resolveInjectedGitMetadata(cwd) } : {},
+      onInitializationError(error, ctx) {
+        const config = loadingConfig;
+        loadingConfig = void 0;
+        initializationError = `Langfuse tracing could not start: ${formatError(error, config)}`;
+        ctx.ui.notify(initializationError, "warning");
+      },
+      beforeSessionDispose: async () => {
+        await configWriteQueue;
+      },
+      onShutdownError(error, ctx) {
+        ctx.ui.notify(`Langfuse shutdown export failed: ${formatError(error, shutdownConfig)}`, "error");
+      },
+      flushOnReplacement: true,
+      shutdownRuntimeOnQuit: true
     });
-    if (result.code !== 0 || result.killed) return void 0;
-    const commit = result.stdout.trim();
-    return /^[0-9a-f]{4,64}$/iu.test(commit) ? commit.toLowerCase() : void 0;
-  } catch {
-    return void 0;
-  }
-}
-function normalizeGitBranch(value) {
-  const branch = value.trim();
-  if (!branch || branch.length > MAX_GIT_BRANCH_LENGTH) return void 0;
-  for (const character of branch) {
-    const code = character.codePointAt(0) ?? 0;
-    if (code <= 31 || code === 127) return void 0;
-  }
-  return branch;
+    async function showLangfuseMenu(ctx) {
+      if (!ctx.hasUI) {
+        ctx.ui.notify(formatNonInteractiveStatus(activeConfig, configPath, initializationError), "warning");
+        return;
+      }
+      const menuGeneration = sessionGeneration;
+      const menuSignal = menuController.signal;
+      const isCurrent = () => menuGeneration === sessionGeneration && !menuSignal.aborted;
+      const { defineMenu, runMenu } = await import("@narumitw/pi-tui-kit");
+      if (!isCurrent()) return;
+      const menu = defineMenu({
+        start: "main",
+        screens: {
+          main: () => ({
+            kind: "actions",
+            title: "Langfuse",
+            lines: formatMenuTitle(activeConfig, configPath, initializationError, configurationNotice).split("\n").slice(1),
+            items: [
+              ...tracing.active ? [{ id: "flush", label: FLUSH_ACTION, action: "flush" }] : [],
+              {
+                id: "configure",
+                label: hasStoredConfig ? UPDATE_ACTION : SET_UP_ACTION,
+                action: "configure"
+              },
+              { id: "help", label: HELP_ACTION, action: "help" }
+            ],
+            hint: "close"
+          })
+        },
+        actions: {
+          flush: async () => {
+            const menuConfig = activeConfig;
+            if (!tracing.active) {
+              ctx.ui.notify("Langfuse tracing is not enabled for this session.", "warning");
+              return { kind: "close" };
+            }
+            try {
+              await tracing.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 : void 0,
+              () => menuGeneration === sessionGeneration
+            );
+            if (!next || menuGeneration !== sessionGeneration) return { kind: "close" };
+            try {
+              const write = configWriteQueue.then(() => writeConfig(next, loaded.path));
+              configWriteQueue = write.then(
+                () => void 0,
+                () => void 0
+              );
+              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: () => void 0,
+        signal: menuSignal,
+        isCurrent
+      });
+    }
+    pi.registerCommand("langfuse", {
+      description: "Open interactive Langfuse tracing controls",
+      handler: async (_args, ctx) => showLangfuseMenu(ctx)
+    });
+    tracing.extension(pi);
+  };
 }
 async function promptForConfig(ctx, current, isCurrent) {
   const secretKey = await ctx.ui.input("Langfuse secret key (leave blank to keep existing):");
@@ -1410,12 +1480,7 @@ async function promptForConfig(ctx, current, isCurrent) {
   return patch;
 }
 function formatMenuTitle(activeConfig, configPath, initializationError, configurationNotice) {
-  const lines = [
-    "Langfuse",
-    "",
-    "Current session:",
-    `  Tracing: ${activeConfig ? "enabled" : "disabled"}`
-  ];
+  const lines = ["Langfuse", "", "Current session:", `  Tracing: ${activeConfig ? "enabled" : "disabled"}`];
   if (activeConfig) {
     lines.push(
       `  Endpoint: ${activeConfig.baseUrl}`,
@@ -1463,7 +1528,7 @@ function formatConfigError(result) {
   const setupHint = result.reason.startsWith("Configuration file not found:") ? " Run /langfuse and choose Set up Langfuse." : "";
   return `Langfuse tracing is disabled: ${result.reason}${setupHint}`;
 }
-function formatError2(error, config) {
+function formatError(error, config) {
   let message = error instanceof Error ? error.message : String(error);
   const secrets = [config?.publicKey, config?.secretKey].filter((secret) => Boolean(secret)).sort((left, right) => right.length - left.length);
   for (const secret of secrets) {
@@ -1472,7 +1537,15 @@ function formatError2(error, config) {
   return message;
 }
 var langfuse_default = createLangfuseExtension();
+
+// src/public-api.ts
+async function createLangfuseRuntime(options = {}) {
+  const runtime = await import("./chunks/runtime-6MIKLWNJ.js");
+  return runtime.createLangfuseRuntime(options);
+}
 export {
+  createLangfuseRuntime,
+  createPiLangfuseSession,
   langfuse_default as default
 };
 //# sourceMappingURL=index.ts.map