oh-langfuse 0.1.59 → 0.1.61

package/scripts/auto-update-runtime.mjs

@@ -39,9 +39,9 @@ function parseArgs(argv) {
   return args;
 }
 
-async function latestVersion(registry = "https://registry.npmjs.org") {
+async function latestVersion(packageName, registry = "https://registry.npmjs.org") {
   const base = registry.replace(/\/+$/, "");
-  const response = await fetch(`${base}/oh-langfuse`, { headers: { accept: "application/json" } });
+  const response = await fetch(`${base}/${packageName}`, { headers: { accept: "application/json" } });
   if (!response.ok) throw new Error(`npm registry ${response.status} ${response.statusText}`);
   return extractVersionFromNpmMetadata(await response.json());
 }
@@ -65,11 +65,13 @@ function runNpx(args, options = {}) {
     return spawnSync("cmd.exe", ["/d", "/s", "/c", npxCommand(), ...args], {
       ...options,
       windowsHide: true,
+      encoding: "utf8",
     });
   }
   return spawnSync(npxCommand(), args, {
     ...options,
     windowsHide: true,
+    encoding: "utf8",
   });
 }
 
@@ -98,13 +100,23 @@ function shouldPrintStartupStatus(args, env = process.env) {
   return !!(args["startup-status"] || args.startupStatus || /^(1|true|yes|on)$/i.test(raw));
 }
 
-function printAlreadyCurrent(target, version) {
+function printAlreadyCurrent(target, packageName, version) {
   const label = targetLabel(target);
-  console.log(paint(`[OK] ${label} Langfuse \u5df2\u662f\u6700\u65b0\uff1a${packageJson.name}@${version}`, t.bold, t.green));
+  console.log(paint(`[OK] ${label} Langfuse \u5df2\u662f\u6700\u65b0\uff1a${packageName}@${version}`, t.bold, t.green));
 }
 
-function runUpdate(target, args) {
-  const updateArgs = ["-y", "oh-langfuse@latest", "update", target];
+function updateCommandForPackage(packageName, target) {
+  if (packageName === "oh-aicoding-tool") return `npx oh-aicoding-tool@latest langfuse update ${target}`;
+  return `npx ${packageName}@latest update ${target}`;
+}
+
+function updateArgsForPackage(packageName, target) {
+  if (packageName === "oh-aicoding-tool") return ["-y", "oh-aicoding-tool@latest", "langfuse", "update", target];
+  return ["-y", `${packageName}@latest`, "update", target];
+}
+
+function runUpdate(target, packageName, args) {
+  const updateArgs = updateArgsForPackage(packageName, target);
   if (args["skip-check"]) updateArgs.push("--skip-check");
   if (args.npmRegistry) updateArgs.push(`--npmRegistry=${args.npmRegistry}`);
   if (args.pipIndexUrl) updateArgs.push(`--pipIndexUrl=${args.pipIndexUrl}`);
@@ -133,26 +145,27 @@ async function main() {
     throw new Error("Usage: oh-langfuse auto-update <claude|opencode|codex>");
   }
 
+  const record = getRuntimeInstallRecord(target);
+  const packageName = record?.packageName || packageJson.name;
   let latest;
   try {
-    latest = await latestVersion(args.npmRegistry);
+    latest = await latestVersion(packageName, args.npmRegistry);
   } catch (error) {
-    if (args.verbose) console.log(`[INFO] oh-langfuse update check skipped: ${error.message}`);
+    if (args.verbose) console.log(`[INFO] ${packageName} update check skipped: ${error.message}`);
     return 0;
   }
 
-  const record = getRuntimeInstallRecord(target);
   const installedVersion = record?.packageVersion || record?.version || "";
   const needsUpdate = installedVersion ? isNewerVersion(latest, installedVersion) : isNewerVersion(latest, packageJson.version);
   if (!needsUpdate) {
-    if (shouldPrintStartupStatus(args)) printAlreadyCurrent(target, installedVersion || packageJson.version);
+    if (shouldPrintStartupStatus(args)) printAlreadyCurrent(target, packageName, installedVersion || packageJson.version);
     return 0;
   }
 
   const message = installedVersion
-    ? `oh-langfuse ${target} runtime update available: ${installedVersion} -> ${latest}.`
-    : `oh-langfuse ${target} runtime may need update. Latest package: ${latest}.`;
-  const updateCommand = `npx oh-langfuse@latest update ${target}`;
+    ? `${packageName} ${target} runtime update available: ${installedVersion} -> ${latest}.`
+    : `${packageName} ${target} runtime may need update. Latest package: ${latest}.`;
+  const updateCommand = updateCommandForPackage(packageName, target);
 
   if (mode === "notify") {
     printUpdateAvailable(target, message, updateCommand);
@@ -163,7 +176,7 @@ async function main() {
   if (mode === "auto") {
     printUpdateAvailable(target, message, updateCommand);
     printUpdateCommand(target, updateCommand);
-    const code = runUpdate(target, args);
+    const code = runUpdate(target, packageName, args);
     return args.strict ? code : 0;
   }
 
@@ -176,7 +189,7 @@ async function main() {
   const answer = await question(`${paint("[CONFIRM]", t.bold, t.gold)} Update now? (y/N) `);
   if (!/^(y|yes)$/i.test(answer)) return 0;
   printUpdateCommand(target, updateCommand);
-  const code = runUpdate(target, args);
+  const code = runUpdate(target, packageName, args);
   return args.strict ? code : 0;
 }
 

package/scripts/codex-langfuse-setup.mjs

@@ -52,61 +52,63 @@ function writeJsonPretty(p, obj) {
 }
 
 function tomlString(s) {
-  return JSON.stringify(String(s));
+  const str = String(s);
+  const escaped = str.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+  return `"${escaped}"`;
 }
 
 function tomlArray(items) {
   return `[${items.map(tomlString).join(", ")}]`;
 }
 
-function pythonExecutableInVenv(venvDir) {
-  return process.platform === "win32"
-    ? path.join(venvDir, "Scripts", "python.exe")
-    : path.join(venvDir, "bin", "python");
-}
-
-function pythonCanImport(pythonCmd, moduleName) {
-  try {
-    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore" });
-    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" });
-      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 shQuote(s) {
+function pythonExecutableInVenv(venvDir) {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : 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 shQuote(s) {
   return `'${String(s).replace(/'/g, "'\"'\"'")}'`;
 }
 
@@ -145,7 +147,7 @@ function writeAutoUpdateHelper(target) {
       "exit /b 0",
       ""
     ];
-    fs.writeFileSync(helper, lines.join(os.EOL), "utf8");
+    fs.writeFileSync(helper, "\ufeff" + lines.join(os.EOL), "utf8");
     return helper;
   }
 
@@ -181,44 +183,44 @@ function isPathInsideDir(candidate, dir) {
   return relative === "" || (relative && !relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function existingCliCandidate(candidate, shimDir) {
-  if (!candidate || isPathInsideDir(candidate, shimDir)) return "";
-  if (process.platform === "win32" && isWindowsAppsPath(candidate)) return "";
-  try {
-    return fs.existsSync(candidate) ? candidate : "";
-  } catch {
-    return "";
-  }
-}
-
-function isWindowsAppsPath(candidate) {
-  return String(candidate || "").toLowerCase().includes("\\program files\\windowsapps\\");
-}
-
-function listLocalCodexCliCandidates() {
-  if (process.platform !== "win32") return [];
-  const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-  const codexBin = path.join(localAppData, "OpenAI", "Codex", "bin");
-  const candidates = [
-    process.env.CODEX_CLI_PATH || "",
-    path.join(codexBin, "codex.exe"),
-  ];
-  try {
-    if (fs.existsSync(codexBin)) {
-      for (const ent of fs.readdirSync(codexBin, { withFileTypes: true })) {
-        if (ent.isDirectory()) candidates.push(path.join(codexBin, ent.name, "codex.exe"));
-      }
-    }
-  } catch {
-    // Best effort only; PATH candidates are still checked below.
-  }
-  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 });
+function existingCliCandidate(candidate, shimDir) {
+  if (!candidate || isPathInsideDir(candidate, shimDir)) return "";
+  if (process.platform === "win32" && isWindowsAppsPath(candidate)) return "";
+  try {
+    return fs.existsSync(candidate) ? candidate : "";
+  } catch {
+    return "";
+  }
+}
+
+function isWindowsAppsPath(candidate) {
+  return String(candidate || "").toLowerCase().includes("\\program files\\windowsapps\\");
+}
+
+function listLocalCodexCliCandidates() {
+  if (process.platform !== "win32") return [];
+  const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+  const codexBin = path.join(localAppData, "OpenAI", "Codex", "bin");
+  const candidates = [
+    process.env.CODEX_CLI_PATH || "",
+    path.join(codexBin, "codex.exe"),
+  ];
+  try {
+    if (fs.existsSync(codexBin)) {
+      for (const ent of fs.readdirSync(codexBin, { withFileTypes: true })) {
+        if (ent.isDirectory()) candidates.push(path.join(codexBin, ent.name, "codex.exe"));
+      }
+    }
+  } catch {
+    // Best effort only; PATH candidates are still checked below.
+  }
+  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/)
@@ -236,14 +238,14 @@ 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) : "",
+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)
   ];
   for (const candidate of candidates) {
@@ -268,7 +270,7 @@ function prependWindowsUserPath(dir) {
     "  [Environment]::SetEnvironmentVariable('Path', $next, 'User');",
     "}"
   ].join(" ");
-  const result = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", windowsHide: true });
+  const result = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", windowsHide: true, encoding: "utf8" });
   if (result.status !== 0) throw new Error("Failed to prepend Codex Langfuse shim to the user PATH.");
 
   const currentParts = String(process.env.PATH || "").split(path.delimiter);
@@ -299,7 +301,7 @@ function writeAgentCommandShim({ baseDir, target, executable, realCli, publicKey
       "exit /b %ERRORLEVEL%",
       ""
     ].filter(Boolean).join(os.EOL);
-    fs.writeFileSync(shim, content, "utf8");
+    fs.writeFileSync(shim, "\ufeff" + content, "utf8");
     return { shim, shimDir };
   }
 
@@ -331,7 +333,7 @@ function createAgentLauncher({ baseDir, target, executable }) {
       `${executable} %*`,
       ""
     ].join(os.EOL);
-    fs.writeFileSync(launcher, content, "utf8");
+    fs.writeFileSync(launcher, "\ufeff" + content, "utf8");
     return launcher;
   }
 
@@ -355,14 +357,14 @@ 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" });
-    } 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.");
-    }
+    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.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -370,14 +372,14 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
     execFileSync(
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
-      { stdio: "inherit" }
-    );
-  } 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}`);
-  }
+      { 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;
 }
@@ -398,7 +400,8 @@ function updateCodexNotify(configPath, notifyCommand) {
   const next = [];
 
   for (const line of lines) {
-    if (/^\s*\[/.test(line)) {
+    const trimmed = line.trim();
+    if (/^\[/.test(trimmed) && !trimmed.startsWith("[[")) {
       if (!replaced && !inserted) {
         while (next.length && next[next.length - 1].trim() === "") next.pop();
         next.push(notifyLine, "");
@@ -419,7 +422,14 @@ function updateCodexNotify(configPath, notifyCommand) {
     next.push(notifyLine, "");
   }
 
-  fs.writeFileSync(configPath, next.join(os.EOL), "utf8");
+  const result = next.join("\n");
+  fs.writeFileSync(configPath, result, "utf8");
+
+  const verifyContent = fs.readFileSync(configPath, "utf8");
+  const notifyMatch = verifyContent.match(/^notify\s*=\s*\[[\s\S]*?\]/m);
+  if (!notifyMatch) {
+    throw new Error(`Failed to write valid notify config to ${configPath}. Generated content:\n${result}`);
+  }
 }
 
 async function main() {

package/scripts/langfuse-setup.mjs

@@ -81,7 +81,7 @@ function extractZipWithPowerShell({ zipPath, destDir }) {
   const cmd = cmdParts.join(" ");
 
   try {
-    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
   } catch {
     throw new Error("解压 hooks zip 失败：请确认 zip 文件存在，且 PowerShell 支持 Expand-Archive。");
   }
@@ -97,7 +97,7 @@ function downloadAndExtractZipWithPowerShell({ zipUrl, destDir }) {
   ].join(" ");
 
   try {
-    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit" });
+    execFileSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", encoding: "utf8" });
   } catch (e) {
     const msg = e?.message ? String(e.message) : "";
     if (msg.includes("(401)") || msg.toLowerCase().includes("unauthorized")) {
@@ -176,7 +176,7 @@ function writeAutoUpdateHelper(target) {
       "exit /b 0",
       ""
     ];
-    fs.writeFileSync(helper, lines.join(os.EOL), "utf8");
+    fs.writeFileSync(helper, "\ufeff" + lines.join(os.EOL), "utf8");
     return helper;
   }
 
@@ -263,7 +263,7 @@ function prependWindowsUserPath(dir) {
     "  [Environment]::SetEnvironmentVariable('Path', $next, 'User');",
     "}"
   ].join(" ");
-  const result = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", windowsHide: true });
+  const result = spawnSync("powershell", ["-NoProfile", "-Command", cmd], { stdio: "inherit", windowsHide: true, encoding: "utf8" });
   if (result.status !== 0) throw new Error("Failed to prepend Claude Langfuse shim to the user PATH.");
 
   const currentParts = String(process.env.PATH || "").split(path.delimiter);
@@ -294,7 +294,7 @@ function writeAgentCommandShim({ baseDir, target, executable, realCli, publicKey
       "exit /b %ERRORLEVEL%",
       ""
     ].filter(Boolean).join(os.EOL);
-    fs.writeFileSync(shim, content, "utf8");
+    fs.writeFileSync(shim, "\ufeff" + content, "utf8");
     return { shim, shimDir };
   }
 
@@ -326,7 +326,7 @@ function createAgentLauncher({ baseDir, target, executable }) {
       `${executable} %*`,
       ""
     ].join(os.EOL);
-    fs.writeFileSync(launcher, content, "utf8");
+    fs.writeFileSync(launcher, "\ufeff" + content, "utf8");
     return launcher;
   }
 
@@ -343,54 +343,54 @@ function createAgentLauncher({ baseDir, target, executable }) {
   return launcher;
 }
 
-function pythonExecutableInVenv(venvDir) {
-  return process.platform === "win32"
-    ? path.join(venvDir, "Scripts", "python.exe")
-    : path.join(venvDir, "bin", "python");
-}
-
-function pythonCanImport(pythonCmd, moduleName) {
-  try {
-    execFileSync(pythonCmd, ["-c", `import ${moduleName}`], { stdio: "ignore" });
-    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" });
-      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 }) {
+function pythonExecutableInVenv(venvDir) {
+  return process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : 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 = [
@@ -398,7 +398,7 @@ async function createHookLauncher({ hooksDir, hookPython, pyPath }) {
       `${cmdQuote(hookPython)} ${cmdQuote(pyPath)}`,
       ""
     ].join(os.EOL);
-    await fsp.writeFile(launcher, content, "utf8");
+    await fsp.writeFile(launcher, "\ufeff" + content, "utf8");
     return launcher;
   }
 
@@ -420,14 +420,14 @@ 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" });
-    } 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.");
-    }
+    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.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -435,14 +435,14 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
     execFileSync(
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
-      { stdio: "inherit" }
-    );
-  } 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}`);
-  }
+      { 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;
 }