oh-langfuse 0.1.71 → 0.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-langfuse",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "private": false,
   "type": "module",
   "description": "Use npm scripts to configure Claude Code / OpenCode / Codex with Langfuse tracing.",
@@ -16,6 +16,7 @@
     "scripts/auto-update-runtime.mjs",
     "scripts/codex-langfuse-check.mjs",
     "scripts/codex-langfuse-setup.mjs",
+    "scripts/cli-detection-utils.mjs",
     "scripts/json-utils.mjs",
     "scripts/langfuse-check.mjs",
     "scripts/langfuse-setup.mjs",

package/scripts/cli-detection-utils.mjs

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function stripExecutableExtension(name) {
+  return String(name || "").replace(/\.(cmd|bat|exe)$/i, "");
+}
+
+function isTargetBinary(target, candidate) {
+  const base = stripExecutableExtension(path.basename(String(candidate || ""))).toLowerCase();
+  return base === String(target || "").toLowerCase();
+}
+
+function sortWindowsCliCandidates(candidates) {
+  const extPriority = (candidate) => {
+    const ext = path.extname(String(candidate || "")).toLowerCase();
+    if (ext === ".cmd" || ext === ".bat" || ext === ".exe") return 0;
+    return 1;
+  };
+  return [...candidates].sort((a, b) => extPriority(a) - extPriority(b));
+}
+
+export function parseWhereisBinaryOutput(target, stdout) {
+  const candidates = [];
+  for (const line of String(stdout || "").split(/\r?\n/)) {
+    const colon = line.indexOf(":");
+    const body = colon === -1 ? line : line.slice(colon + 1);
+    for (const token of body.split(/\s+/)) {
+      const candidate = token.trim();
+      if (candidate && path.isAbsolute(candidate) && isTargetBinary(target, candidate)) {
+        candidates.push(candidate);
+      }
+    }
+  }
+  return unique(candidates);
+}
+
+function isLikelyNodePrefix(name) {
+  return /^(node|nodejs)(?:[-_.].*)?$/i.test(String(name || ""));
+}
+
+export function listCommonUnixCliCandidates(target, roots = ["/usr/local", "/opt"]) {
+  if (process.platform === "win32") return [];
+  const candidates = [
+    path.join("/usr/local", "bin", target),
+    path.join("/usr", "bin", target),
+    path.join("/bin", target),
+  ];
+  for (const root of roots) {
+    try {
+      if (!fs.existsSync(root)) continue;
+      for (const ent of fs.readdirSync(root, { withFileTypes: true })) {
+        if (ent.isDirectory() && isLikelyNodePrefix(ent.name)) {
+          candidates.push(path.join(root, ent.name, "bin", target));
+        }
+      }
+    } catch {
+      // Best effort only; command lookups and other candidates may still work.
+    }
+  }
+  return unique(candidates);
+}
+
+export function listSystemCliCandidates(target) {
+  if (!target) return [];
+  const candidates = [];
+  if (process.platform === "win32") {
+    const result = spawnSync("where.exe", [target], { encoding: "utf8", windowsHide: true });
+    if (result.status === 0) {
+      candidates.push(...String(result.stdout || "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+    }
+    return sortWindowsCliCandidates(unique(candidates));
+  }
+
+  const which = spawnSync("which", ["-a", target], { encoding: "utf8", windowsHide: true });
+  if (which.status === 0) {
+    candidates.push(...String(which.stdout || "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+  }
+
+  const whereis = spawnSync("whereis", ["-b", target], { encoding: "utf8", windowsHide: true });
+  if (whereis.status === 0) {
+    candidates.push(...parseWhereisBinaryOutput(target, whereis.stdout));
+  }
+
+  candidates.push(...listCommonUnixCliCandidates(target));
+  return unique(candidates);
+}
+
+export function candidateExists(candidate) {
+  try {
+    return Boolean(candidate) && fs.existsSync(candidate);
+  } catch {
+    return false;
+  }
+}
+
+export function hasSystemCli(target) {
+  return listSystemCliCandidates(target).some(candidateExists);
+}
+
+export function defaultWindowsNpmCliCandidates(target) {
+  const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+  if (process.platform !== "win32") return [];
+  return [
+    path.join(appData, "npm", `${target}.cmd`),
+    path.join(appData, "npm", `${target}.exe`),
+    path.join(appData, "npm", target),
+  ];
+}

package/scripts/codex-langfuse-check.mjs

@@ -38,8 +38,8 @@ function findLatestSession(sessionsDir) {
   return latest;
 }
 
-function commandOk(cmd, args) {
-  const r = spawnSync(cmd, args, { encoding: "utf8" });
+function commandOk(cmd, args, env = process.env) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", env });
   return { ok: !r.error && r.status === 0, detail: (r.stdout || r.stderr || "").trim() };
 }
 
@@ -63,8 +63,22 @@ function readCodexShimTarget(codexHome) {
 function venvPython(codexHome) {
   return process.platform === "win32"
     ? path.join(codexHome, "langfuse-venv", "Scripts", "python.exe")
-    : path.join(codexHome, "langfuse-venv", "bin", "python");
-}
+    : path.join(codexHome, "langfuse-venv", "bin", "python");
+}
+
+function fallbackPythonCommand() {
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+function isolatedPythonPath(codexHome) {
+  return path.join(codexHome, "langfuse-python");
+}
+
+function langfuseImportOk(hookPython, fallbackTarget) {
+  if (fs.existsSync(hookPython)) return commandOk(hookPython, ["-c", "import langfuse; print('langfuse ok')"]);
+  const env = { ...process.env, PYTHONPATH: process.env.PYTHONPATH ? `${fallbackTarget}${path.delimiter}${process.env.PYTHONPATH}` : fallbackTarget };
+  return commandOk(fallbackPythonCommand(), ["-c", "import langfuse; print('langfuse ok')"], env);
+}
 
 function configHasNotify(configText) {
   const firstSection = configText.search(/^\s*\[/m);
@@ -84,10 +98,11 @@ function main() {
   const sessionsDir = path.join(codexHome, "sessions");
   const latestSession = findLatestSession(sessionsDir);
   const langfuseConfig = readJsonIfExists(langfuseConfigPath);
-  const configText = fs.existsSync(configPath) ? stripBom(fs.readFileSync(configPath, "utf8")) : "";
+  const configText = fs.existsSync(configPath) ? stripBom(fs.readFileSync(configPath, "utf8")) : "";
   const hookPython = venvPython(codexHome);
+  const fallbackTarget = isolatedPythonPath(codexHome);
   const python = commandOk(process.platform === "win32" ? "python" : "python3", ["--version"]);
-  const langfuseImport = commandOk(hookPython, ["-c", "import langfuse; print('langfuse ok')"]);
+  const langfuseImport = langfuseImportOk(hookPython, fallbackTarget);
   const codexShimTarget = readCodexShimTarget(codexHome);
   const codexShimUsesWindowsApps = !!codexShimTarget && isWindowsAppsPath(codexShimTarget);
 
@@ -138,7 +153,13 @@ function main() {
     codexShimTarget || "not installed",
     "Run setup/update again with a fixed oh-langfuse version; WindowsApps Codex paths cannot be called directly."
   );
-  addResult(results, "Langfuse venv Python", fs.existsSync(hookPython), hookPython, "Run setup again; on Linux install python3-venv if venv creation fails.");
+  addResult(
+    results,
+    "Langfuse hook Python",
+    fs.existsSync(hookPython) || fs.existsSync(fallbackTarget),
+    fs.existsSync(hookPython) ? hookPython : `${fallbackPythonCommand()} with PYTHONPATH=${fallbackTarget}`,
+    "Run setup again; on Linux the installer can fall back to an isolated PYTHONPATH target."
+  );
   addResult(
     results,
     "Python langfuse package",

package/scripts/codex-langfuse-setup.mjs

@@ -2,9 +2,10 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { execFileSync, spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { defaultWindowsNpmCliCandidates, listSystemCliCandidates } from "./cli-detection-utils.mjs";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const USER_ID_PATTERN = /^[a-z](?:\d{8}|wx\d{7})$/;
@@ -67,46 +68,63 @@ function pythonExecutableInVenv(venvDir) {
     : path.join(venvDir, "bin", "python");
 }
 
-function pythonCanImport(pythonCmd, moduleName) {
-  try {
-    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function runPipInstallWithFallback({ pythonCmd, pipIndexUrl }) {
-  const attempts = [
-    { command: pythonCmd, args: ["-m", "pip", "install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
-    { command: "pip3", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
-    { command: "pip", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] }
-  ];
-
-  const errors = [];
-  for (const attempt of attempts) {
-    try {
-      console.log(`Trying Python package install: ${attempt.command} ${attempt.args.join(" ")}`);
-      execFileSync(attempt.command, attempt.args, { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
-      return;
-    } catch (error) {
-      errors.push(`${attempt.command}: ${error?.message || error}`);
-    }
-  }
-
-  throw new Error(
-    `Failed to install langfuse with system Python/pip. Tried python -m pip, pip3, and pip. Last errors: ${errors.join(" | ")}`
-  );
-}
-
-function installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl }) {
-  console.log("Python venv is unavailable; falling back to system Python user install for langfuse.");
-  runPipInstallWithFallback({ pythonCmd, pipIndexUrl });
-  if (!pythonCanImport(pythonCmd, "langfuse")) {
-    throw new Error("langfuse was installed with pip, but python3 still cannot import it. Install python3-venv and rerun setup, for example: sudo apt install python3-venv");
-  }
-  return pythonCmd;
-}
+function pythonEnv(extraPythonPath = "") {
+  const env = { ...process.env, PYTHONUTF8: "1" };
+  if (extraPythonPath) {
+    env.PYTHONPATH = process.env.PYTHONPATH ? `${extraPythonPath}${path.delimiter}${process.env.PYTHONPATH}` : extraPythonPath;
+  }
+  return env;
+}
+
+function pythonCanImport(pythonCmd, moduleName, extraPythonPath = "") {
+  try {
+    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore", encoding: "utf8", env: pythonEnv(extraPythonPath) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installLangfuseIntoTargetDir({ pythonCmd, baseDir, pipIndexUrl }) {
+  const targetDir = path.join(baseDir, "langfuse-python");
+  ensureDir(targetDir);
+  console.log(`Installing Python package into isolated target: ${targetDir}`);
+  execFileSync(
+    pythonCmd,
+    ["-m", "pip", "install", "--target", targetDir, "--upgrade", "langfuse", "-i", pipIndexUrl],
+    { stdio: "inherit", encoding: "utf8", env: pythonEnv() }
+  );
+  if (!pythonCanImport(pythonCmd, "langfuse", targetDir)) {
+    throw new Error(`langfuse was installed into ${targetDir}, but ${pythonCmd} still cannot import it with PYTHONPATH.`);
+  }
+  return { python: pythonCmd, pythonPath: targetDir };
+}
+
+function runPipInstallWithFallback({ pythonCmd, baseDir, pipIndexUrl }) {
+  const attempts = [
+    () => installLangfuseIntoTargetDir({ pythonCmd, baseDir, pipIndexUrl }),
+    () => installLangfuseIntoTargetDir({ pythonCmd: "python3", baseDir, pipIndexUrl }),
+    () => installLangfuseIntoTargetDir({ pythonCmd: "python", baseDir, pipIndexUrl })
+  ];
+
+  const errors = [];
+  for (const attempt of attempts) {
+    try {
+      return attempt();
+    } catch (error) {
+      errors.push(error?.message || String(error));
+    }
+  }
+
+  throw new Error(
+    `Failed to install langfuse into isolated Python target. Last errors: ${errors.join(" | ")}`
+  );
+}
+
+function installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl }) {
+  console.log("Python venv is unavailable; falling back to isolated PYTHONPATH install for langfuse.");
+  return runPipInstallWithFallback({ pythonCmd, baseDir, pipIndexUrl });
+}
 
 function shQuote(s) {
   return `'${String(s).replace(/'/g, "'\"'\"'")}'`;
@@ -217,19 +235,11 @@ function listLocalCodexCliCandidates() {
   return candidates;
 }
 
-function listCliCandidatesFromPath(target) {
-  const cmd = process.platform === "win32" ? "where.exe" : "which";
-  const args = process.platform === "win32" ? [target] : ["-a", target];
-  const result = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true });
-  if (result.status !== 0) return [];
-  const candidates = String(result.stdout || "")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-  return process.platform === "win32" ? sortWindowsCliCandidates(candidates) : candidates;
-}
-
-function sortWindowsCliCandidates(candidates) {
+function listCliCandidatesFromPath(target) {
+  return listSystemCliCandidates(target);
+}
+
+function sortWindowsCliCandidates(candidates) {
   const extPriority = (candidate) => {
     const ext = path.extname(String(candidate || "")).toLowerCase();
     if (ext === ".cmd" || ext === ".bat" || ext === ".exe") return 0;
@@ -238,16 +248,13 @@ function sortWindowsCliCandidates(candidates) {
   return [...candidates].sort((a, b) => extPriority(a) - extPriority(b));
 }
 
-function resolveAgentCli({ target, preferred = "", shimDir = "" }) {
-  const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-  const candidates = [
-    preferred,
-    ...(target === "codex" ? listLocalCodexCliCandidates() : []),
-    process.platform === "win32" ? path.join(appData, "npm", `${target}.cmd`) : "",
-    process.platform === "win32" ? path.join(appData, "npm", `${target}.exe`) : "",
-    process.platform === "win32" ? path.join(appData, "npm", target) : "",
-    ...listCliCandidatesFromPath(target)
-  ];
+function resolveAgentCli({ target, preferred = "", shimDir = "" }) {
+  const candidates = [
+    preferred,
+    ...(target === "codex" ? listLocalCodexCliCandidates() : []),
+    ...defaultWindowsNpmCliCandidates(target),
+    ...listCliCandidatesFromPath(target)
+  ];
   for (const candidate of candidates) {
     const found = existingCliCandidate(candidate, shimDir);
     if (found) return found;
@@ -358,13 +365,13 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
   if (!fs.existsSync(venvPython)) {
     console.log(`Creating Python virtual environment: ${venvDir}`);
     try {
-      execFileSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
-    } catch (e) {
-      if (process.platform !== "win32") {
-        return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
-      }
-      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
-    }
+      execFileSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
+    } catch (e) {
+      if (process.platform !== "win32") {
+        return installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl });
+      }
+      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -373,16 +380,31 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
       { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } }
-    );
-  } catch (e) {
-    if (process.platform !== "win32") {
-      return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
-    }
-    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
-  }
-
-  return venvPython;
-}
+    );
+  } catch (e) {
+    if (process.platform !== "win32") {
+      return installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl });
+    }
+    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
+  }
+
+  if (!pythonCanImport(venvPython, "langfuse")) {
+    if (process.platform !== "win32") {
+      return installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl });
+    }
+    throw new Error(`langfuse was installed in venv, but cannot be imported by ${venvPython}`);
+  }
+
+  return { python: venvPython, pythonPath: "" };
+}
+
+function codexNotifyCommand({ python, pythonPath = "", hookPath }) {
+  if (pythonPath && process.platform !== "win32") {
+    const script = `if [ -n "\${PYTHONPATH:-}" ]; then export PYTHONPATH=${shQuote(pythonPath)}:"$PYTHONPATH"; else export PYTHONPATH=${shQuote(pythonPath)}; fi; exec ${shQuote(python)} ${shQuote(hookPath)}`;
+    return ["sh", "-c", script];
+  }
+  return [python, hookPath];
+}
 
 function updateCodexNotify(configPath, notifyCommand) {
   let content = fs.existsSync(configPath) ? fs.readFileSync(configPath, "utf8") : "";
@@ -483,11 +505,11 @@ async function main() {
     userId,
   });
 
-  const pythonCmd = process.platform === "win32" ? "python" : "python3";
-  const notifyPython = args["skip-pip-install"]
-    ? pythonCmd
-    : createOrUpdateLangfuseVenv({ baseDir: codexHome, pipIndexUrl });
-  updateCodexNotify(configPath, [notifyPython, destHook]);
+  const pythonCmd = process.platform === "win32" ? "python" : "python3";
+  const notifyRuntime = args["skip-pip-install"]
+    ? { python: pythonCmd, pythonPath: "" }
+    : createOrUpdateLangfuseVenv({ baseDir: codexHome, pipIndexUrl });
+  updateCodexNotify(configPath, codexNotifyCommand({ python: notifyRuntime.python, pythonPath: notifyRuntime.pythonPath, hookPath: destHook }));
   const codexShimDir = path.join(codexHome, "bin");
   const realCodexCli = resolveAgentCli({ target: "codex", preferred: args.cmd || "", shimDir: codexShimDir });
   const directShim = writeAgentCommandShim({

package/scripts/langfuse-check.mjs

@@ -14,11 +14,19 @@ function addResult(results, item, ok, detail, fix = "") {
   results.push({ item, ok, detail, fix });
 }
 
-function pythonExecutableInVenv(claudeDir) {
-  return process.platform === "win32"
-    ? path.join(claudeDir, "langfuse-venv", "Scripts", "python.exe")
-    : path.join(claudeDir, "langfuse-venv", "bin", "python");
-}
+function pythonExecutableInVenv(claudeDir) {
+  return process.platform === "win32"
+    ? path.join(claudeDir, "langfuse-venv", "Scripts", "python.exe")
+    : path.join(claudeDir, "langfuse-venv", "bin", "python");
+}
+
+function fallbackPythonCommand() {
+  return process.platform === "win32" ? "python" : "python3";
+}
+
+function isolatedPythonPath(claudeDir) {
+  return path.join(claudeDir, "langfuse-python");
+}
 
 function launcherPath(hooksDir) {
   return process.platform === "win32"
@@ -63,13 +71,18 @@ function pathExists(p) {
   return typeof p === "string" && p.length > 0 && fs.existsSync(p);
 }
 
-function checkPythonLangfuseImport(pythonPath) {
-  if (!pathExists(pythonPath)) return { ok: false, detail: "python executable missing" };
-  const result = spawnSync(pythonPath, ["-c", "import langfuse; print('OK')"], {
-    encoding: "utf8",
-    timeout: 15000,
-    windowsHide: true
-  });
+function checkPythonLangfuseImport(pythonPath, extraPythonPath = "") {
+  if (!pathExists(pythonPath) && pythonPath !== "python3" && pythonPath !== "python") return { ok: false, detail: "python executable missing" };
+  const env = { ...process.env };
+  if (extraPythonPath) {
+    env.PYTHONPATH = process.env.PYTHONPATH ? `${extraPythonPath}${path.delimiter}${process.env.PYTHONPATH}` : extraPythonPath;
+  }
+  const result = spawnSync(pythonPath, ["-c", "import langfuse; print('OK')"], {
+    encoding: "utf8",
+    timeout: 15000,
+    windowsHide: true,
+    env
+  });
   if (result.status === 0) return { ok: true, detail: "OK" };
   const err = `${result.stderr || result.stdout || result.error?.message || "unknown error"}`.trim();
   return { ok: false, detail: err || "import failed" };
@@ -80,10 +93,11 @@ function main() {
   const claudeDir = path.join(userHome, ".claude");
   const hooksDir = path.join(claudeDir, "hooks");
   const settingsPath = path.join(claudeDir, "settings.json");
-  const pyPath = path.join(hooksDir, "langfuse_hook.py");
-  const expectedLauncher = launcherPath(hooksDir);
-  const expectedPython = pythonExecutableInVenv(claudeDir);
-  const logPath = path.join(claudeDir, "state", "langfuse_hook.log");
+  const pyPath = path.join(hooksDir, "langfuse_hook.py");
+  const expectedLauncher = launcherPath(hooksDir);
+  const expectedPython = pythonExecutableInVenv(claudeDir);
+  const fallbackTarget = isolatedPythonPath(claudeDir);
+  const logPath = path.join(claudeDir, "state", "langfuse_hook.log");
 
   const results = [];
 
@@ -138,22 +152,26 @@ function main() {
     "Run setup again. Claude Code should execute the generated Python hook command."
   );
 
-  addResult(
-    results,
-    "hook python executable",
-    pathExists(expectedPython),
-    expectedPython,
-    "Run setup again to recreate the Python venv."
-  );
-
-  const importCheck = checkPythonLangfuseImport(expectedPython);
-  addResult(
-    results,
-    "python package langfuse",
-    importCheck.ok,
-    importCheck.detail,
-    `Run: ${expectedPython} -m pip install -U langfuse`
-  );
+  addResult(
+    results,
+    "hook python executable",
+    pathExists(expectedPython) || fs.existsSync(fallbackTarget),
+    pathExists(expectedPython) ? expectedPython : `${fallbackPythonCommand()} with PYTHONPATH=${fallbackTarget}`,
+    "Run setup again to recreate the Python venv."
+  );
+
+  const importCheck = pathExists(expectedPython)
+    ? checkPythonLangfuseImport(expectedPython)
+    : checkPythonLangfuseImport(fallbackPythonCommand(), fallbackTarget);
+  addResult(
+    results,
+    "python package langfuse",
+    importCheck.ok,
+    importCheck.detail,
+    pathExists(expectedPython)
+      ? `Run: ${expectedPython} -m pip install -U langfuse`
+      : "Run setup again to install langfuse into the isolated PYTHONPATH target."
+  );
 
   addResult(results, "hook log path", true, logPath);
 

package/scripts/langfuse-setup.mjs

@@ -2,9 +2,10 @@ import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { execFileSync, spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { defaultWindowsNpmCliCandidates, listSystemCliCandidates } from "./cli-detection-utils.mjs";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
@@ -221,26 +222,16 @@ function existingCliCandidate(candidate, shimDir) {
   }
 }
 
-function listCliCandidatesFromPath(target) {
-  const cmd = process.platform === "win32" ? "where.exe" : "which";
-  const args = process.platform === "win32" ? [target] : ["-a", target];
-  const result = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true });
-  if (result.status !== 0) return [];
-  return String(result.stdout || "")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-}
-
-function resolveAgentCli({ target, preferred = "", shimDir = "" }) {
-  const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-  const candidates = [
-    preferred,
-    process.platform === "win32" ? path.join(appData, "npm", `${target}.cmd`) : "",
-    process.platform === "win32" ? path.join(appData, "npm", `${target}.exe`) : "",
-    process.platform === "win32" ? path.join(appData, "npm", target) : "",
-    ...listCliCandidatesFromPath(target)
-  ];
+function listCliCandidatesFromPath(target) {
+  return listSystemCliCandidates(target);
+}
+
+function resolveAgentCli({ target, preferred = "", shimDir = "" }) {
+  const candidates = [
+    preferred,
+    ...defaultWindowsNpmCliCandidates(target),
+    ...listCliCandidatesFromPath(target)
+  ];
   for (const candidate of candidates) {
     const found = existingCliCandidate(candidate, shimDir);
     if (found) return found;
@@ -349,68 +340,87 @@ function pythonExecutableInVenv(venvDir) {
     : path.join(venvDir, "bin", "python");
 }
 
-function pythonCanImport(pythonCmd, moduleName) {
-  try {
-    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function runPipInstallWithFallback({ pythonCmd, pipIndexUrl }) {
-  const attempts = [
-    { command: pythonCmd, args: ["-m", "pip", "install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
-    { command: "pip3", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] },
-    { command: "pip", args: ["install", "--user", "-U", "langfuse", "-i", pipIndexUrl] }
-  ];
-
-  const errors = [];
-  for (const attempt of attempts) {
-    try {
-      console.log(`Trying Python package install: ${attempt.command} ${attempt.args.join(" ")}`);
-      execFileSync(attempt.command, attempt.args, { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
-      return;
-    } catch (error) {
-      errors.push(`${attempt.command}: ${error?.message || error}`);
-    }
-  }
-
-  throw new Error(
-    `Failed to install langfuse with system Python/pip. Tried python -m pip, pip3, and pip. Last errors: ${errors.join(" | ")}`
-  );
-}
-
-function installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl }) {
-  console.log("Python venv is unavailable; falling back to system Python user install for langfuse.");
-  runPipInstallWithFallback({ pythonCmd, pipIndexUrl });
-  if (!pythonCanImport(pythonCmd, "langfuse")) {
-    throw new Error("langfuse was installed with pip, but python3 still cannot import it. Install python3-venv and rerun setup, for example: sudo apt install python3-venv");
-  }
-  return pythonCmd;
-}
-
-async function createHookLauncher({ hooksDir, hookPython, pyPath }) {
-  if (process.platform === "win32") {
-    const launcher = path.join(hooksDir, "run-langfuse-hook.cmd");
-    const content = [
-      "@echo off",
-      `${cmdQuote(hookPython)} ${cmdQuote(pyPath)}`,
-      ""
-    ].join(os.EOL);
+function pythonEnv(extraPythonPath = "") {
+  const env = { ...process.env, PYTHONUTF8: "1" };
+  if (extraPythonPath) {
+    env.PYTHONPATH = process.env.PYTHONPATH ? `${extraPythonPath}${path.delimiter}${process.env.PYTHONPATH}` : extraPythonPath;
+  }
+  return env;
+}
+
+function pythonCanImport(pythonCmd, moduleName, extraPythonPath = "") {
+  try {
+    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore", encoding: "utf8", env: pythonEnv(extraPythonPath) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installLangfuseIntoTargetDir({ pythonCmd, baseDir, pipIndexUrl }) {
+  const targetDir = path.join(baseDir, "langfuse-python");
+  ensureDir(targetDir);
+  console.log(`Installing Python package into isolated target: ${targetDir}`);
+  execFileSync(
+    pythonCmd,
+    ["-m", "pip", "install", "--target", targetDir, "--upgrade", "langfuse", "-i", pipIndexUrl],
+    { stdio: "inherit", encoding: "utf8", env: pythonEnv() }
+  );
+  if (!pythonCanImport(pythonCmd, "langfuse", targetDir)) {
+    throw new Error(`langfuse was installed into ${targetDir}, but ${pythonCmd} still cannot import it with PYTHONPATH.`);
+  }
+  return { python: pythonCmd, pythonPath: targetDir };
+}
+
+function runPipInstallWithFallback({ pythonCmd, baseDir, pipIndexUrl }) {
+  const attempts = [
+    () => installLangfuseIntoTargetDir({ pythonCmd, baseDir, pipIndexUrl }),
+    () => installLangfuseIntoTargetDir({ pythonCmd: "python3", baseDir, pipIndexUrl }),
+    () => installLangfuseIntoTargetDir({ pythonCmd: "python", baseDir, pipIndexUrl })
+  ];
+
+  const errors = [];
+  for (const attempt of attempts) {
+    try {
+      return attempt();
+    } catch (error) {
+      errors.push(error?.message || String(error));
+    }
+  }
+
+  throw new Error(
+    `Failed to install langfuse into isolated Python target. Last errors: ${errors.join(" | ")}`
+  );
+}
+
+function installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl }) {
+  console.log("Python venv is unavailable; falling back to isolated PYTHONPATH install for langfuse.");
+  return runPipInstallWithFallback({ pythonCmd, baseDir, pipIndexUrl });
+}
+
+async function createHookLauncher({ hooksDir, hookPython, hookPythonPath = "", pyPath }) {
+  if (process.platform === "win32") {
+    const launcher = path.join(hooksDir, "run-langfuse-hook.cmd");
+    const content = [
+      "@echo off",
+      hookPythonPath ? `set PYTHONPATH=${hookPythonPath};%PYTHONPATH%` : null,
+      `${cmdQuote(hookPython)} ${cmdQuote(pyPath)}`,
+      ""
+    ].filter(Boolean).join(os.EOL);
     await fsp.writeFile(launcher, content, "utf8");
-    return launcher;
-  }
-
-  const launcher = path.join(hooksDir, "run-langfuse-hook.sh");
-  const content = [
-    "#!/usr/bin/env sh",
-    `exec ${shQuote(hookPython)} ${shQuote(pyPath)}`,
-    ""
-  ].join("\n");
-  await fsp.writeFile(launcher, content, "utf8");
-  fs.chmodSync(launcher, 0o755);
-  return launcher;
+    return launcher;
+  }
+
+  const launcher = path.join(hooksDir, "run-langfuse-hook.sh");
+  const content = [
+    "#!/usr/bin/env sh",
+    hookPythonPath ? `if [ -n "\${PYTHONPATH:-}" ]; then export PYTHONPATH=${shQuote(hookPythonPath)}:"$PYTHONPATH"; else export PYTHONPATH=${shQuote(hookPythonPath)}; fi` : null,
+    `exec ${shQuote(hookPython)} ${shQuote(pyPath)}`,
+    ""
+  ].filter(Boolean).join("\n");
+  await fsp.writeFile(launcher, content, "utf8");
+  fs.chmodSync(launcher, 0o755);
+  return launcher;
 }
 
 function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.tsinghua.edu.cn/simple" }) {
@@ -421,13 +431,13 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
   if (!fs.existsSync(venvPython)) {
     console.log(`Creating Python virtual environment: ${venvDir}`);
     try {
-      execFileSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
-    } catch (e) {
-      if (process.platform !== "win32") {
-        return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
-      }
-      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
-    }
+      execFileSync(pythonCmd, ["-m", "venv", venvDir], { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } });
+    } catch (e) {
+      if (process.platform !== "win32") {
+        return installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl });
+      }
+      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -436,16 +446,23 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
       { stdio: "inherit", encoding: "utf8", env: { ...process.env, PYTHONUTF8: "1" } }
-    );
-  } catch (e) {
-    if (process.platform !== "win32") {
-      return installLangfuseWithSystemPython({ pythonCmd, pipIndexUrl });
-    }
-    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
-  }
-
-  return venvPython;
-}
+    );
+  } catch (e) {
+    if (process.platform !== "win32") {
+      return installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl });
+    }
+    throw new Error(`Failed to install langfuse in venv: ${venvPython} -m pip install -U langfuse -i ${pipIndexUrl}`);
+  }
+
+  if (!pythonCanImport(venvPython, "langfuse")) {
+    if (process.platform !== "win32") {
+      return installLangfuseWithSystemPython({ pythonCmd, baseDir, pipIndexUrl });
+    }
+    throw new Error(`langfuse was installed in venv, but cannot be imported by ${venvPython}`);
+  }
+
+  return { python: venvPython, pythonPath: "" };
+}
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
@@ -526,8 +543,9 @@ async function main() {
   if (nextPyText !== pyText) {
     await fsp.writeFile(pyPath, nextPyText, "utf8");
   }
-  const hookPython = createOrUpdateLangfuseVenv({ baseDir: claudeDir, pipIndexUrl });
-  const hookLauncher = await createHookLauncher({ hooksDir, hookPython, pyPath });
+  const hookRuntime = createOrUpdateLangfuseVenv({ baseDir: claudeDir, pipIndexUrl });
+  const hookPython = hookRuntime.python;
+  const hookLauncher = await createHookLauncher({ hooksDir, hookPython, hookPythonPath: hookRuntime.pythonPath, pyPath });
   const claudeShimDir = path.join(claudeDir, "bin");
   const realClaudeCli = resolveAgentCli({ target: "claude", preferred: args.cmd || "", shimDir: claudeShimDir });
   const directShim = writeAgentCommandShim({

package/scripts/resolve-opencode-cli.mjs

@@ -1,7 +1,8 @@
 import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import { spawnSync } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { listSystemCliCandidates } from "./cli-detection-utils.mjs";
 
 /**
  * OpenCode CLI 的官方安装脚本默认会把二进制放到 ~/.opencode/bin；
@@ -36,10 +37,11 @@ export function resolveOpencodeCli(preferred) {
       candidates.push(path.join(process.env.APPDATA, "npm", "node_modules", "opencode-windows-x64-baseline", "bin", "opencode.exe"));
     }
     candidates.push(path.join(home, "scoop", "shims", "opencode.exe"));
-  } else {
-    candidates.push(path.join(home, ".opencode", "bin", "opencode"));
-    candidates.push(path.join(home, ".local", "bin", "opencode"));
-  }
+  } else {
+    candidates.push(path.join(home, ".opencode", "bin", "opencode"));
+    candidates.push(path.join(home, ".local", "bin", "opencode"));
+    candidates.push(...listSystemCliCandidates("opencode"));
+  }
 
   for (const c of candidates) {
     if (c && fs.existsSync(c)) return c;

package/scripts/update-langfuse-runtime.mjs

@@ -1,10 +1,11 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { buildUpdatePlan, extractVersionFromNpmMetadata } from "./update-utils.mjs";
-import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { hasSystemCli } from "./cli-detection-utils.mjs";
+import { buildUpdatePlan, extractVersionFromNpmMetadata } from "./update-utils.mjs";
+import { writeRuntimeInstallRecord } from "./runtime-state-utils.mjs";
 
 const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
@@ -59,16 +60,21 @@ function readJsonIfExists(p) {
   }
 }
 
-function detectInstalledTargets(home = os.homedir()) {
-  const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
-  return {
-    claude: fs.existsSync(path.join(home, ".claude", "hooks", "langfuse_hook.py")),
-    opencode:
-      fs.existsSync(path.join(home, ".config", "opencode", "opencode.json")) ||
-      fs.existsSync(path.join(home, ".config", "opencode", "plugins", "opencode-plugin-langfuse")),
-    codex: fs.existsSync(path.join(codexHome, "hooks", "codex_langfuse_notify.py")),
-  };
-}
+function detectInstalledTargets(home = os.homedir()) {
+  const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
+  return {
+    claude:
+      fs.existsSync(path.join(home, ".claude", "hooks", "langfuse_hook.py")) ||
+      hasSystemCli("claude"),
+    opencode:
+      fs.existsSync(path.join(home, ".config", "opencode", "opencode.json")) ||
+      fs.existsSync(path.join(home, ".config", "opencode", "plugins", "opencode-plugin-langfuse")) ||
+      hasSystemCli("opencode"),
+    codex:
+      fs.existsSync(path.join(codexHome, "hooks", "codex_langfuse_notify.py")) ||
+      hasSystemCli("codex"),
+  };
+}
 
 function claudeConfig(home) {
   const settings = readJsonIfExists(path.join(home, ".claude", "settings.json")) || {};