oh-langfuse 0.1.54 → 0.1.56

package/README.md

@@ -1,142 +1,213 @@
-# oh-langfuse
-
-`oh-langfuse` 鏄敤浜庣粰 Claude Code銆丱penCode 鍜?Codex 閰嶇疆 Langfuse 杩借釜鐨勫懡浠よ宸ュ叿銆傚畠鎻愪緵浜や簰寮忓畨瑁呭悜瀵硷紝涔熸敮鎸?`setup` / `check` 鐩存帴鍛戒护锛屾柟渚垮湪鐢ㄦ埛鏈哄櫒涓婂畨瑁呫€佷慨澶嶅拰鏍￠獙閰嶇疆銆?
-褰撳墠 npm 鐗堟湰锛歚0.1.41`
-
-## 鑳藉仛浠€涔?
-- 缁?Claude Code 瀹夎 `Stop` hook锛屾妸浼氳瘽浜嬩欢鍐欏叆 Langfuse銆?- 缁?OpenCode 瀹夎骞?patch `opencode-plugin-langfuse`锛屽紑鍚?OpenTelemetry銆?- 缁?Codex 瀹夎 `notify` hook锛屽閲忚鍙?session JSONL 骞跺啓鍏?Langfuse銆?- 瀹夎瀹屾垚鍚庤嚜鍔ㄦ墽琛屽搴?`check`锛屽敖鏃╁彂鐜伴厤缃己澶便€?- 鏍￠獙鍛樺伐鍙锋牸寮忥紝蹇呴』鍖归厤 `^[a-z](?:\d{8}|wx\d{7})$`锛屼緥濡?`h00613222` 鎴?`hwx1234567`銆?
-## 蹇€熶娇鐢?
-寤鸿濮嬬粓甯?`@latest`锛岄伩鍏?npx 浣跨敤鏈湴鏃х紦瀛橈細
-
-```bash
-npx oh-langfuse@latest
-npx oh-langfuse@latest setup
-npx oh-langfuse@latest check
-```
-
-涔熷彲浠ユ寚瀹氱洰鏍囷細
-
-```bash
-npx oh-langfuse@latest setup claude
-npx oh-langfuse@latest setup opencode
-npx oh-langfuse@latest setup codex
-
-npx oh-langfuse@latest check claude
-npx oh-langfuse@latest check opencode
-npx oh-langfuse@latest check codex
-```
-
-## 鑷姩鏇存柊
-
-瀹夎鎴栨洿鏂?runtime 鍚庯紝宸ュ叿浼氬湪 `~/.config/oh-langfuse/runtime.json` 璁板綍 Claude Code / OpenCode / Codex 褰撳墠鍐欏叆鏈満 runtime 鐨?`oh-langfuse` 鐗堟湰銆?
-OpenCode 鐢熸垚鐨?`launch-opencode-langfuse.*` 浼氬湪鍚姩 agent 鍓嶆墽琛屼竴娆℃洿鏂版娴嬶細濡傛灉 npm 涓婄殑 `oh-langfuse@latest` 楂樹簬鏈満 runtime 鐗堟湰锛屼細鎻愮ず鏄惁鏇存柊锛涚敤鎴风‘璁ゅ悗鎵嶄細杩愯 `npx oh-langfuse@latest update opencode`銆侰laude Code 鍜?Codex 涔熶細鐢熸垚瀵瑰簲 launcher锛?
-OpenCode setup 杩樹細鐢熸垚 `~/.config/opencode/bin/opencode` / `opencode.cmd` 鍛戒护鍖呰鍣紝骞舵妸璇ョ洰褰曞啓鍏ョ敤鎴?PATH銆傛柊寮€缁堢鍚庣洿鎺ヨ繍琛?`opencode`锛屼細鍏堢敤杞婚噺鑴氭湰妫€娴?`oh-langfuse` runtime 鏄惁闇€瑕佹洿鏂帮紝鍐嶈浆鍙戝埌鐪熷疄 OpenCode CLI銆備负浜嗛伩鍏?Windows 涓嬪湪 agent 鍚姩閾捐矾閲屽祵濂楄繍琛?Node/npm installer 瀵艰嚧鍚姩宕╂簝锛宍opencode` 鍛戒护鍙仛妫€娴嬪拰鎻愮ず锛涢渶瑕佹洿鏂版椂璇峰叧闂?agent 鍚庤繍琛屾彁绀轰腑鐨?`npx oh-langfuse@latest update opencode`銆?
-- `~/.claude/launch-claude-langfuse.cmd` / `~/.claude/launch-claude-langfuse.sh`
-- `~/.codex/launch-codex-langfuse.cmd` / `~/.codex/launch-codex-langfuse.sh`
-
-濡傛灉鐩存帴杩愯绯荤粺鍘熷鐨?`claude` / `codex` 鍛戒护锛屽伐鍏蜂笉浼氬己琛屾浛鎹㈣鍛戒护锛涢渶瑕佷娇鐢ㄤ笂杩?launcher 鎵嶈兘鍋氬埌鍚姩鍓嶆娴嬪苟鎻愮ず鏇存柊銆備篃鍙互鎵嬪姩杩愯锛?
-```bash
-npx oh-langfuse@latest auto-update opencode
-npx oh-langfuse@latest auto-update claude
-npx oh-langfuse@latest auto-update codex
-```
-
-## Skill 使用量统计
-
-工具会把 skill 使用汇总写入每次交互的 `Agent Turn` observation，不再额外生成 `Skill Use` observation。
-
-```text
-Observation Name: Agent Turn
-metadata.skill_use_count: 本轮 skill 使用总次数
-metadata.unique_skill_count: 本轮不同 skill 数量
-metadata.repeated_skill_count: 本轮重复 skill 使用次数
-metadata.skill_names: 去重后的 skill 名称列表
-metadata.skill_names_all: 按使用顺序记录的 skill 名称列表
-```
-
-Dashboard 中统计全部 skill 使用量可配置：
-
-```text
-View: Observations
-Metric: Sum skill_use_count
-Filter: Observation Name equals Agent Turn
-```
-
-如果当前 Langfuse Dashboard 支持 metadata 维度，可用 `metadata.skill_names` 或导出数据中的 `metadata.skill_names_all` 按 skill 聚合。`skill_names_json`、`skill_names_all_json` 和 `skill_use_events_json` 不再写入，避免和数组字段重复。
-鏈湴寮€鍙戣繍琛岋細
-
-```bash
-npm install
-npm start
-```
-
-## 浜や簰寮忚彍鍗?
-杩愯 `npx oh-langfuse@latest` 浼氭墦寮€浜や簰寮忚彍鍗曪細
-
-- `Up` / `Down` 绉诲姩閫夐」銆?- 鏁板瓧閿揩閫熷畾浣嶃€?- `Space` 鍕鹃€夋垨鍙栨秷銆?- `Enter` 纭銆?- `q` 鎴?`Esc` 閫€鍑恒€?
-澶氶€夎彍鍗曢粯璁や笉鍕鹃€変换浣曠洰鏍囷紝閬垮厤璇銆傜粓绔笉鏀寔鍘熷鎸夐敭杈撳叆鏃讹紝浼氳嚜鍔ㄩ檷绾т负鏁板瓧杈撳叆妯″紡銆?
-## OpenCode 璇存槑
-
-OpenCode 瀹夎浼氬啓鍏ワ細
-
-- `~/.config/opencode/opencode.json`
-- `~/.config/opencode/plugins/opencode-plugin-langfuse`
-- `~/.config/opencode-plugin-langfuse/config.json`
-- Windows 涓嬬殑 `~/.config/opencode/launch-opencode-langfuse.cmd`
-- Linux/macOS 涓嬬殑 `~/.config/opencode/launch-opencode-langfuse.sh`
-
-Windows 涓嬪畨瑁呭櫒浼氬皾璇曞啓鍏ョ敤鎴风骇 `LANGFUSE_PUBLIC_KEY`銆乣LANGFUSE_SECRET_KEY`銆乣LANGFUSE_BASEURL`銆傝繖浜涘彉閲忓褰撳墠宸茬粡鎵撳紑鐨勭粓绔笉浼氱珛鍗崇敓鏁堬紝闇€瑕佹柊寮€缁堢锛屾垨鑰呬娇鐢ㄧ敓鎴愮殑 launcher 鍚姩 OpenCode銆?
-`check opencode` 宸叉寜瀹為檯鎯呭喌澶勭悊 Windows锛氬鏋滃綋鍓嶇粓绔繕鐪嬩笉鍒?`LANGFUSE_*`锛屼絾鐢ㄦ埛绾х幆澧冨彉閲忓凡鍐欏叆锛屾垨 launcher 宸茬敓鎴愶紝浼氭樉绀?OpenCode 浠嶆湁鍙敤鐨?Langfuse 鐜鍙橀噺鏉ユ簮锛屼笉鍐嶆妸杩欑鎯呭喌璇垽涓哄畨瑁呭け璐ャ€?
-WSL 鐢ㄦ埛璇风洿鎺ュ湪 WSL shell 涓畨瑁呭拰妫€鏌ワ細
-
-```bash
-npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
-npx oh-langfuse@latest check opencode
-```
-
-涓嶄細鍋?Windows 鍒?WSL 鐨勮浆鍙戯紱鍦?WSL 涓繍琛屾椂锛岄厤缃啓鍏?WSL 鐢ㄦ埛鑷繁鐨?`$HOME/.config/opencode`銆?
-## Claude Code 璇存槑
-
-Claude Code 瀹夎浼氾細
-
-- 瀹夎 `langfuse_hook.py`
-- 鍒涘缓 `~/.claude/langfuse-venv`
-- 瀹夎 Python 鍖?`langfuse`
-- 鍚堝苟鏇存柊 `~/.claude/settings.json`
-- 閰嶇疆 `Stop` hook
-
-Linux 濡傛灉缂哄皯 venv 鏀寔锛岃鏍规嵁鎻愮ず瀹夎 `python3-venv` 鎴栧搴?Python 鐗堟湰鐨?venv 鍖呫€?
-## Codex 璇存槑
-
-Codex 瀹夎浼氾細
-
-- 瀹夎 `codex_langfuse_notify.py`
-- 鍒涘缓 `~/.codex/langfuse-venv`
-- 鍐欏叆 `~/.codex/langfuse/config.json`
-- 鏇存柊 `~/.codex/config.toml` 椤跺眰 `notify`
-
-閰嶇疆鍚庨渶瑕侀噸鍚?Codex銆俷otify hook 浼氬閲忚鍙?`~/.codex/sessions/**/*.jsonl`锛屾妸鏂扮殑 user銆乤ssistant銆乼ool銆乼oken 浜嬩欢杞崲涓?Langfuse observation锛屽苟鎶婅鍙栧亸绉昏褰曞埌 `~/.codex/langfuse/state.json`銆?
-## 鐜鍙橀噺
-
-| 鍙橀噺 | 浣滅敤 |
-| --- | --- |
-| `LANGFUSE_BASEURL` / `LANGFUSE_HOST` | Langfuse 鏈嶅姟鍦板潃 |
-| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
-| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
-| `LANGFUSE_USER_ID` / `CC_USER_ID` | 鐢ㄦ埛鏍囪瘑锛屽繀椤诲尮閰嶅憳宸ュ彿瑙勫垯 |
-| `CODEX_HOME` | 鑷畾涔?Codex home 鐩綍 |
-| `OPENCODE_SKIP_PLUGIN_INSTALL` | 璺宠繃 OpenCode npm 鎻掍欢瀹夎 |
-| `OPENCODE_NPM_REGISTRY` | OpenCode 鎻掍欢 npm 瀹夎婧?|
-
-Secret key 涓嶄細鍦ㄤ氦浜掑紡鐣岄潰涓槑鏂囧睍绀恒€?
-## 甯哥敤缁存姢鍛戒护
-
-```bash
-npm run check
-npm pack --dry-run
-```
-
-鍙戝竷鍖呮毚闇蹭袱涓懡浠わ細
-
-- `oh-langfuse`
-- `code-tool-langfuse`锛屽吋瀹规棫鍏ュ彛
+# oh-langfuse
+
+`oh-langfuse` 是用于给 Claude Code、OpenCode、Codex 配置 Langfuse 追踪的命令行工具。它既提供交互式安装向导，也支持 `setup`、`check`、`update`、`auto-update` 等直接命令。
+
+当前 npm 版本：`0.1.56`
+
+## 能做什么
+
+- 为 Claude Code 安装 `Stop` hook，把会话事件写入 Langfuse。
+- 为 OpenCode 安装并 patch `opencode-plugin-langfuse`，开启 OpenTelemetry，并输出 `Agent Turn` 指标。
+- 为 Codex 安装 `notify` hook，增量读取 session JSONL 并写入 Langfuse。
+- 记录本地 runtime 版本，支持启动前更新检查和手动更新。
+- 校验员工号、环境变量、插件、hook、launcher、命令 shim 是否安装完整。
+
+员工号必须匹配：
+
+```text
+^[a-z](?:\d{8}|wx\d{7})$
+```
+
+示例：`h00613222`、`hwx1234567`。
+
+## 快速使用
+
+建议始终带 `@latest`：
+
+```bash
+npx oh-langfuse@latest
+npx oh-langfuse@latest setup
+npx oh-langfuse@latest check
+```
+
+指定目标：
+
+```bash
+npx oh-langfuse@latest setup claude
+npx oh-langfuse@latest setup opencode
+npx oh-langfuse@latest setup codex
+
+npx oh-langfuse@latest check claude
+npx oh-langfuse@latest check opencode
+npx oh-langfuse@latest check codex
+```
+
+更新已安装运行时：
+
+```bash
+npx oh-langfuse@latest update all
+npx oh-langfuse@latest update claude
+npx oh-langfuse@latest update opencode
+npx oh-langfuse@latest update codex
+```
+
+## 交互式菜单
+
+运行 `npx oh-langfuse@latest` 会打开菜单：
+
+- `Setup Langfuse`：选择 Claude Code、OpenCode、Codex 中的一个或多个目标安装。
+- `Update Installed Runtimes`：刷新已安装目标的 hook、plugin、launcher、命令 shim 和 runtime 版本记录。
+- `Check Environment`：检查 Node.js、npm、Python、pip、OpenCode CLI 等基础依赖。
+- `Check Configuration`：检查已写入的目标配置。
+
+多选菜单默认不选中任何目标，避免误写本地配置。
+
+## 自动更新
+
+安装或更新 runtime 后，工具会在：
+
+```text
+~/.config/oh-langfuse/runtime.json
+```
+
+记录 Claude Code / OpenCode / Codex 当前写入本机 runtime 的包名和版本。
+
+OpenCode setup 会生成直接命令 shim：
+
+- Windows：`~/.config/opencode/bin/opencode.cmd`
+- Linux/macOS：`~/.config/opencode/bin/opencode`
+
+新开终端后直接运行 `opencode`，会先做轻量更新检查，再转发到真实 OpenCode CLI。为了避免在 agent 启动链路里嵌套运行完整 installer，shim 默认只提示更新命令；需要更新时关闭 agent 后运行：
+
+```bash
+npx oh-langfuse@latest update opencode
+```
+
+Claude Code 和 Codex 也会生成 launcher：
+
+- `~/.claude/launch-claude-langfuse.cmd` / `~/.claude/launch-claude-langfuse.sh`
+- `~/.codex/launch-codex-langfuse.cmd` / `~/.codex/launch-codex-langfuse.sh`
+
+也可以手动触发轻量检查：
+
+```bash
+npx oh-langfuse@latest auto-update opencode
+npx oh-langfuse@latest auto-update claude
+npx oh-langfuse@latest auto-update codex
+```
+
+## Skill 使用统计
+
+当前版本把 skill 使用汇总写入每次交互的 `Agent Turn` observation，不再额外生成独立 `Skill Use` observation。
+
+常见字段：
+
+```text
+metadata.skill_use_count
+metadata.unique_skill_count
+metadata.repeated_skill_count
+metadata.skill_names
+metadata.skill_names_all
+metadata.skill_invocation_modes
+metadata.skill_agent_paths
+```
+
+Dashboard 统计建议：
+
+```text
+View: Observations
+Filter: Observation Name equals Agent Turn
+Metric: Sum skill_use_count
+```
+
+如果 Langfuse Dashboard 支持 metadata 维度，可用 `metadata.skill_names` 聚合；导出数据时可用 `metadata.skill_names_all` 保留重复调用顺序。
+
+## 各目标写入内容
+
+### OpenCode
+
+写入或更新：
+
+- `~/.config/opencode/opencode.json`
+- `~/.config/opencode/plugins/opencode-plugin-langfuse`
+- `~/.config/opencode-plugin-langfuse/config.json`
+- `~/.config/opencode/launch-opencode-langfuse.cmd` 或 `.sh`
+- `~/.config/opencode/bin/opencode.cmd` 或 `opencode`
+
+Windows 下会尝试写入用户级 `LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`、`LANGFUSE_BASEURL`、`LANGFUSE_USER_ID`。当前终端不会立即继承用户级环境变量，新开终端或使用 launcher 即可生效。
+
+### Claude Code
+
+写入或更新：
+
+- `~/.claude/hooks/langfuse_hook.py`
+- `~/.claude/langfuse-venv`
+- `~/.claude/settings.json`
+- `~/.claude/bin/claude.cmd` 或 `claude`
+- `~/.claude/launch-claude-langfuse.cmd` 或 `.sh`
+
+Linux 环境缺少 `python3-venv/ensurepip` 时，安装器会降级尝试 `python3 -m pip --user`、`pip3 --user`、`pip --user` 安装 `langfuse`。
+
+### Codex
+
+写入或更新：
+
+- `~/.codex/hooks/codex_langfuse_notify.py`
+- `~/.codex/langfuse-venv`
+- `~/.codex/langfuse/config.json`
+- `~/.codex/config.toml` 顶层 `notify`
+- `~/.codex/bin/codex.cmd` 或 `codex`
+- `~/.codex/launch-codex-langfuse.cmd` 或 `.sh`
+
+配置后需要重启 Codex，让新的 notify 命令加载。notify hook 会增量读取 `~/.codex/sessions/**/*.jsonl`，并把读取偏移记录到 `~/.codex/langfuse/state.json`。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `LANGFUSE_BASEURL` / `LANGFUSE_HOST` | Langfuse 服务地址 |
+| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
+| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
+| `LANGFUSE_USER_ID` / `CC_USER_ID` | 用户标识，必须匹配员工号规则 |
+| `CODEX_HOME` | 自定义 Codex home 目录 |
+| `OPENCODE_SKIP_PLUGIN_INSTALL` | 跳过 OpenCode npm 插件安装 |
+| `OPENCODE_NPM_REGISTRY` | OpenCode 插件 npm 安装 registry |
+| `LANGFUSE_PIP_INDEX_URL` | Python `langfuse` 安装 index |
+
+Secret key 不会在交互式界面中明文展示。
+
+## WSL
+
+WSL 用户请在 WSL shell 中直接安装和检查：
+
+```bash
+npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
+npx oh-langfuse@latest check opencode
+```
+
+工具不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 `$HOME/.config/opencode`。
+
+## 开发与验证
+
+```bash
+npm run check
+npm test
+npm pack --dry-run
+```
+
+涉及安装、hook、CLI、OpenCode、Claude Code、Codex、Langfuse、packaging 或 verification 行为的修改，应运行真实闭环验证：
+
+```bash
+npm run self:verify -- --targets=opencode --userId=h00613222
+```
+
+完整覆盖可运行：
+
+```bash
+npm run self:verify -- --targets=claude,opencode,codex --userId=h00613222
+```
+
+发布包暴露两个命令：
+
+- `oh-langfuse`
+- `code-tool-langfuse`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-langfuse",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "private": false,
   "type": "module",
   "description": "Use npm scripts to configure Claude Code / OpenCode / Codex with Langfuse tracing.",

package/scripts/codex-langfuse-check.mjs

@@ -38,14 +38,31 @@ function findLatestSession(sessionsDir) {
   return latest;
 }
 
-function commandOk(cmd, args) {
-  const r = spawnSync(cmd, args, { encoding: "utf8" });
-  return { ok: !r.error && r.status === 0, detail: (r.stdout || r.stderr || "").trim() };
-}
-
-function venvPython(codexHome) {
-  return process.platform === "win32"
-    ? path.join(codexHome, "langfuse-venv", "Scripts", "python.exe")
+function commandOk(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: "utf8" });
+  return { ok: !r.error && r.status === 0, detail: (r.stdout || r.stderr || "").trim() };
+}
+
+function isWindowsAppsPath(candidate) {
+  return String(candidate || "").toLowerCase().includes("\\program files\\windowsapps\\");
+}
+
+function readCodexShimTarget(codexHome) {
+  if (process.platform !== "win32") return "";
+  const shimPath = path.join(codexHome, "bin", "codex.cmd");
+  if (!fs.existsSync(shimPath)) return "";
+  const text = stripBom(fs.readFileSync(shimPath, "utf8"));
+  const matches = text.matchAll(/^\s*call\s+"([^"]+)"/gim);
+  for (const match of matches) {
+    const base = path.basename(match[1]).toLowerCase();
+    if (base === "codex.exe" || base === "codex.cmd" || base === "codex") return match[1];
+  }
+  return "";
+}
+
+function venvPython(codexHome) {
+  return process.platform === "win32"
+    ? path.join(codexHome, "langfuse-venv", "Scripts", "python.exe")
     : path.join(codexHome, "langfuse-venv", "bin", "python");
 }
 
@@ -68,11 +85,13 @@ function main() {
   const latestSession = findLatestSession(sessionsDir);
   const langfuseConfig = readJsonIfExists(langfuseConfigPath);
   const configText = fs.existsSync(configPath) ? stripBom(fs.readFileSync(configPath, "utf8")) : "";
-  const hookPython = venvPython(codexHome);
-  const python = commandOk(process.platform === "win32" ? "python" : "python3", ["--version"]);
-  const langfuseImport = commandOk(hookPython, ["-c", "import langfuse; print('langfuse ok')"]);
-
-  const logPath = path.join(codexHome, "langfuse", "codex_langfuse_notify.log");
+  const hookPython = venvPython(codexHome);
+  const python = commandOk(process.platform === "win32" ? "python" : "python3", ["--version"]);
+  const langfuseImport = commandOk(hookPython, ["-c", "import langfuse; print('langfuse ok')"]);
+  const codexShimTarget = readCodexShimTarget(codexHome);
+  const codexShimUsesWindowsApps = !!codexShimTarget && isWindowsAppsPath(codexShimTarget);
+
+  const logPath = path.join(codexHome, "langfuse", "codex_langfuse_notify.log");
   const logText = fs.existsSync(logPath) ? stripBom(fs.readFileSync(logPath, "utf8")) : "";
   const recentLogHasError = /Traceback|ERROR|Exception|Failed/i.test(logText.slice(-4000));
 
@@ -111,8 +130,15 @@ function main() {
     "Start a Codex conversation, then check again.",
     { required: false }
   );
-  addResult(results, "Python", python.ok, python.detail || "not found", "Install Python and pip, then rerun setup.");
-  addResult(results, "Langfuse venv Python", fs.existsSync(hookPython), hookPython, "Run setup again; on Linux install python3-venv if venv creation fails.");
+  addResult(results, "Python", python.ok, python.detail || "not found", "Install Python and pip, then rerun setup.");
+  addResult(
+    results,
+    "Codex command shim target",
+    !codexShimUsesWindowsApps,
+    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,
     "Python langfuse package",

package/scripts/codex-langfuse-setup.mjs

@@ -59,13 +59,54 @@ 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 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" });
+    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) {
   return `'${String(s).replace(/'/g, "'\"'\"'")}'`;
 }
 
@@ -140,19 +181,44 @@ function isPathInsideDir(candidate, dir) {
   return relative === "" || (relative && !relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function existingCliCandidate(candidate, shimDir) {
-  if (!candidate || isPathInsideDir(candidate, shimDir)) return "";
-  try {
-    return fs.existsSync(candidate) ? candidate : "";
-  } catch {
-    return "";
-  }
-}
-
-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/)
@@ -170,13 +236,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,
-    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) {
@@ -288,14 +355,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") {
-        throw new Error("Failed to create Python venv. Please install python3-venv first, for example: sudo apt install python3-venv");
-      }
-      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
-    }
+    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.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -303,11 +370,14 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
     execFileSync(
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
-      { stdio: "inherit" }
-    );
-  } catch (e) {
-    throw new Error(`Failed to install langfuse in venv: ${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}`);
+  }
 
   return venvPython;
 }

package/scripts/langfuse-setup.mjs

@@ -343,13 +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");
-}
-
-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" });
+    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 }) {
   if (process.platform === "win32") {
     const launcher = path.join(hooksDir, "run-langfuse-hook.cmd");
     const content = [
@@ -379,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") {
-        throw new Error("Failed to create Python venv. Please install python3-venv first, for example: sudo apt install python3-venv");
-      }
-      throw new Error("Failed to create Python venv. Please confirm Python venv support is available.");
-    }
+    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.");
+    }
   }
 
   console.log("Installing/updating Python package in venv: langfuse");
@@ -394,11 +435,14 @@ function createOrUpdateLangfuseVenv({ baseDir, pipIndexUrl = "https://pypi.tuna.
     execFileSync(
       venvPython,
       ["-m", "pip", "install", "-U", "langfuse", "-i", pipIndexUrl],
-      { stdio: "inherit" }
-    );
-  } catch (e) {
-    throw new Error(`Failed to install langfuse in venv: ${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}`);
+  }
 
   return venvPython;
 }

package/scripts/opencode-langfuse-check.mjs

@@ -61,6 +61,7 @@ function main() {
   const userConfigPath = path.join(home, ".config", "opencode-plugin-langfuse", "config.json");
   const windowsLauncherPath = path.join(opencodeDir, "launch-opencode-langfuse.cmd");
   const unixLauncherPath = path.join(opencodeDir, "launch-opencode-langfuse.sh");
+  const opencodeCommandShimPath = path.join(opencodeDir, "bin", process.platform === "win32" ? "opencode.cmd" : "opencode");
 
   const results = [];
 
@@ -134,6 +135,14 @@ function main() {
     "Run setup again and enter userId when prompted."
   );
 
+  addResult(
+    results,
+    "opencode command shim",
+    fs.existsSync(opencodeCommandShimPath),
+    opencodeCommandShimPath,
+    "Run setup again after installing OpenCode so the direct opencode command can load Langfuse and auto-update checks."
+  );
+
   if (process.platform === "win32") {
     addResult(
       results,

package/scripts/opencode-langfuse-setup.mjs

@@ -512,12 +512,10 @@ function getPatchedLangfuseDistIndexJs() {
     "  if (userId) spanProcessors.push(createUserIdSpanProcessor(userId));",
     "",
     "  const sdk = new NodeSDK({ spanProcessors });",
-    "  // Defer SDK start to avoid blocking Opencode launch",
-    "  setImmediate(() => {",
-    '    try { sdk.start(); }',
-    '    catch (err) { log("warn", `OTEL SDK start failed: ${err?.message ?? err}`); }',
+    "  const sdkStartPromise = Promise.resolve().then(() => sdk.start()).catch((err) => {",
+    '    log("warn", `OTEL SDK start failed: ${err?.message ?? err}`);',
     "  });",
-    "  const metricsTracer = trace.getTracer('oh-langfuse-opencode-metrics');",
+    "  const getMetricsTracer = () => trace.getTracer('oh-langfuse-opencode-metrics');",
     "  const knownSkillNames = await collectKnownSkillNames();",
     "  const startupSkillUsages = detectOpencodeSkillUsages(process.argv.join('\\n'), knownSkillNames);",
     "  const messageTextById = new Map();",
@@ -534,21 +532,23 @@ function getPatchedLangfuseDistIndexJs() {
     '  if (userId) log("info", `LANGFUSE userId configured -> ${userId}`);',
     '  if (knownSkillNames.length) log("info", `OpenCode skills discovered -> ${knownSkillNames.length}`);',
     "",
-    "  let shutdownStarted = false;",
-    "  const flush = async (reason) => {",
-    "    try {",
-    '      log("info", `Flushing OTEL spans on ${reason}`);',
-    "      await processor.forceFlush();",
+    "  let shutdownStarted = false;",
+    "  const flush = async (reason) => {",
+    "    try {",
+    '      log("info", `Flushing OTEL spans on ${reason}`);',
+    "      await sdkStartPromise;",
+    "      await processor.forceFlush();",
     "    } catch (error) {",
     '      log("warn", `OTEL forceFlush failed on ${reason}: ${error?.message ?? error}`);',
     "    }",
     "  };",
     "  const shutdown = async (reason) => {",
-    "    if (shutdownStarted) return;",
-    "    shutdownStarted = true;",
-    "    try {",
-    '      log("info", `Shutting down OTEL SDK on ${reason}`);',
-    "      await sdk.shutdown();",
+    "    if (shutdownStarted) return;",
+    "    shutdownStarted = true;",
+    "    try {",
+    '      log("info", `Shutting down OTEL SDK on ${reason}`);',
+    "      await sdkStartPromise;",
+    "      await sdk.shutdown();",
     "    } catch (error) {",
     '      log("warn", `OTEL shutdown failed on ${reason}: ${error?.message ?? error}`);',
     "    }",
@@ -586,7 +586,7 @@ function getPatchedLangfuseDistIndexJs() {
     "    }",
     "    set.add(activity.toolCallId || `${kind}:${set.size + 1}`);",
     "  };",
-    "  const recordInteractionMetric = (event) => {",
+    "  const recordInteractionMetric = async (event) => {",
     "    const payload = eventPayload(event);",
     "    const part = eventPart(event);",
     "    const partType = part?.type ?? '';",
@@ -617,7 +617,8 @@ function getPatchedLangfuseDistIndexJs() {
     "    const tokenMetrics = tokenMetricsFromPart(part);",
     "    const total = tokenMetrics.total ?? (tokenMetrics.input !== undefined && tokenMetrics.output !== undefined ? tokenMetrics.input + tokenMetrics.output : undefined);",
     "    const tokenAvailable = [tokenMetrics.input, tokenMetrics.output, total, tokenMetrics.cacheRead, tokenMetrics.reasoning].some((value) => value !== undefined);",
-    "    const span = metricsTracer.startSpan('Agent Turn');",
+    "    await sdkStartPromise;",
+    "    const span = getMetricsTracer().startSpan('Agent Turn');",
     "    const text = messageTextById.get(messageId) || '';",
     "    const skillUsages = dedupeSkillUsages([...(skillUsagesByMessageId.get(messageId) ?? []), ...(skillUsagesBySessionId.get(sessionId) ?? [])]);",
     "    const interactionId = `opencode:${userId || \"unknown\"}:${sessionId || \"unknown\"}:${messageId}`;",
@@ -673,9 +674,9 @@ function getPatchedLangfuseDistIndexJs() {
     '        log("warn", "OpenTelemetry experimental feature is disabled in Opencode config - tracing disabled");',
     "      }",
     "    },",
-    "    event: async ({ event }) => {",
-    "      const eventType = pickEventString(event?.name, event?.type, eventPayload(event)?.name, eventPayload(event)?.type);",
-    "      recordInteractionMetric(event);",
+    "    event: async ({ event }) => {",
+    "      const eventType = pickEventString(event?.name, event?.type, eventPayload(event)?.name, eventPayload(event)?.type);",
+    "      await recordInteractionMetric(event);",
     '      if (eventType === "session.idle" || eventType === "message.updated" || eventType === "message.part.updated" || eventType === "session.updated" || eventType === "session.idle.1" || eventType === "message.updated.1" || eventType === "message.part.updated.1" || eventType === "session.updated.1") {',
     "        await flush(eventType);",
     "      }",
@@ -973,24 +974,28 @@ function npmInstallLooksLikeMissingVersion(result) {
   return text.includes("etarget") || text.includes("notarget") || text.includes("no matching version found");
 }
 
-function isOfficialNpmRegistry(registry) {
-  return /^https?:\/\/registry\.npmjs\.org\/?$/i.test(String(registry || "").trim());
-}
-
-async function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-langfuse", npmRegistry = "" }) {
-  const npmArgs = ["install", pkgName, "--prefix", opencodeDir, "--package-lock=false", "--no-save", "--audit=false", "--fund=false"];
-  if (npmRegistry) npmArgs.push("--registry", npmRegistry);
-  const cliJs = getNpmCliJsPath();
-  console.log(`使用 npm：${fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable()}`);
-  console.log("Installing OpenCode Langfuse plugin. This can take a few minutes on slow networks...");
-  let r = await runNpmInstallCapture(npmArgs);
-  if (!r.error && r.status !== 0 && npmInstallLooksLikeMissingVersion(r) && !isOfficialNpmRegistry(npmRegistry)) {
-    console.error("");
-    console.error("npm registry appears to be missing a package version. Retrying with https://registry.npmjs.org/ ...");
-    const retryArgs = ["install", pkgName, "--prefix", opencodeDir, "--package-lock=false", "--no-save", "--audit=false", "--fund=false", "--registry", "https://registry.npmjs.org/"];
-    r = await runNpmInstallCapture(retryArgs);
-    if (!r.error && r.status === 0) return;
-  }
+function isOfficialNpmRegistry(registry) {
+  return /^https?:\/\/registry\.npmjs\.org\/?$/i.test(String(registry || "").trim());
+}
+
+const OFFICIAL_NPM_REGISTRY = "https://registry.npmjs.org/";
+
+async function runNpmInstallOrThrow({ opencodeDir, pkgName = "opencode-plugin-langfuse", npmRegistry = "" }) {
+  const npmArgs = ["install", pkgName, "--prefix", opencodeDir, "--package-lock=false", "--no-save", "--audit=false", "--fund=false"];
+  const effectiveRegistry = npmRegistry || OFFICIAL_NPM_REGISTRY;
+  npmArgs.push("--registry", effectiveRegistry);
+  const cliJs = getNpmCliJsPath();
+  console.log(`使用 npm：${fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable()}`);
+  console.log(`使用 npm registry：${effectiveRegistry}`);
+  console.log("Installing OpenCode Langfuse plugin. This can take a few minutes on slow networks...");
+  let r = await runNpmInstallCapture(npmArgs);
+  if (!r.error && r.status !== 0 && npmInstallLooksLikeMissingVersion(r) && !isOfficialNpmRegistry(effectiveRegistry)) {
+    console.error("");
+    console.error(`npm registry appears to be missing a package version. Retrying with ${OFFICIAL_NPM_REGISTRY} ...`);
+    const retryArgs = ["install", pkgName, "--prefix", opencodeDir, "--package-lock=false", "--no-save", "--audit=false", "--fund=false", "--registry", OFFICIAL_NPM_REGISTRY];
+    r = await runNpmInstallCapture(retryArgs);
+    if (!r.error && r.status === 0) return;
+  }
   if (!r.error && r.status === 0) return;
   printNpmDiagnostics();
   const npmLabel = fs.existsSync(cliJs) ? `node ${cliJs}` : getNpmExecutable();
@@ -1105,7 +1110,7 @@ async function main() {
     throw new Error("缺少参数：--userId=你的工号");
   }
   assertValidUserId(userId);
-  const npmRegistry = args.npmRegistry || process.env.OPENCODE_NPM_REGISTRY || process.env.NPM_CONFIG_REGISTRY || "";
+  const npmRegistry = args.npmRegistry || process.env.OPENCODE_NPM_REGISTRY || "";
 
   const home = os.homedir();
   const opencodeDir = path.join(home, ".config", "opencode");

package/scripts/real-self-verify.mjs

@@ -136,16 +136,36 @@ function printRunResult(label, result) {
   }
 }
 
-function findOnPath(names) {
-  for (const name of names) {
-    const probe = run(name, ["--version"], { timeoutMs: 15000 });
-    if (probe.status === 0) return name;
-  }
-  return "";
-}
-
-function configFromArgs(args) {
-  return {
+function findOnPath(names) {
+  for (const name of names) {
+    const probe = run(name, ["--version"], { timeoutMs: 15000 });
+    if (probe.status === 0) return name;
+  }
+  return "";
+}
+
+function localCodexCliCandidates() {
+  if (process.platform !== "win32") return ["codex"];
+  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 {
+    // Fall back to PATH probing below.
+  }
+  return [...candidates, "codex.cmd", "codex.exe", "codex"].filter(Boolean);
+}
+
+function configFromArgs(args) {
+  return {
     baseUrl:
       String(args.langfuseBaseUrl || args.langfuseHost || args.host || process.env.LANGFUSE_BASEURL || process.env.LANGFUSE_HOST || DEFAULT_LANGFUSE_BASE_URL),
     publicKey: String(args.publicKey || process.env.LANGFUSE_PUBLIC_KEY || DEFAULT_LANGFUSE_PUBLIC_KEY),
@@ -213,9 +233,9 @@ function triggerOpenCode(prompt, args, env) {
   return last;
 }
 
-function triggerCodex(prompt, args, env) {
-  const cmd = String(args.codexCmd || findOnPath(process.platform === "win32" ? ["codex.cmd", "codex.exe", "codex"] : ["codex"]));
-  if (!cmd) return { status: 127, stdout: "", stderr: "Codex CLI not found. Set --codexCmd=<path>.", command: "codex", args: [] };
+function triggerCodex(prompt, args, env) {
+  const cmd = String(args.codexCmd || findOnPath(localCodexCliCandidates()));
+  if (!cmd) return { status: 127, stdout: "", stderr: "Codex CLI not found. Set --codexCmd=<path>.", command: "codex", args: [] };
   const candidates = [
     ["exec", prompt],
     ["exec", "--skip-git-repo-check", prompt],