dores-codex 4.0.0

package/.codex/bin/dores-hook-dispatch

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+hook_event="${1:-}"
+project_root="${2:-${PROJECT_PATH:-}}"
+
+if [[ -z "$hook_event" ]]; then
+  printf 'usage: dores-hook-dispatch <hook-event> [project-root]\n' >&2
+  exit 1
+fi
+
+if [[ -z "$project_root" ]]; then
+  project_root="$PWD"
+  while [[ "$project_root" != "/" && ! -f "$project_root/.codex/hooks.json" ]]; do
+    project_root="$(dirname "$project_root")"
+  done
+fi
+
+if [[ ! -f "$project_root/lib/hook-runner.js" ]]; then
+  printf 'hook runner not found under %s\n' "$project_root" >&2
+  exit 1
+fi
+
+node_bin="$(command -v node || true)"
+if [[ -z "$node_bin" ]]; then
+  node_bin="$(command -v nodejs || true)"
+fi
+
+if [[ -z "$node_bin" ]]; then
+  printf 'node runtime not found in PATH\n' >&2
+  exit 1
+fi
+
+runtime_dir="${CODEX_PLUGIN_RUNTIME_DIR:-$project_root/runtime}"
+log_file="${CODEX_PLUGIN_HOOK_LOG_FILE:-$runtime_dir/codex-plugin.log}"
+
+exec env \
+  CODEX_PLUGIN_HOME="${CODEX_PLUGIN_HOME:-$project_root}" \
+  CODEX_PLUGIN_HOOK_DIRECT_LOG="1" \
+  CODEX_PLUGIN_HOOK_LOG_FILE="$log_file" \
+  CODEX_PLUGIN_RUNTIME_DIR="$runtime_dir" \
+  PROJECT_PATH="$project_root" \
+  "$node_bin" "$project_root/lib/hook-runner.js" "$hook_event" "$project_root"

package/.codex/hooks.json

@@ -0,0 +1,62 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'root=\"$PWD\"; while [ \"$root\" != \"/\" ] && [ ! -f \"$root/.codex/hooks.json\" ]; do root=\"$(dirname \"$root\")\"; done; exec \"$root/.codex/bin/dores-hook-dispatch\" SessionStart \"$root\"'",
+            "statusMessage": "Dispatching session start hook"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'root=\"$PWD\"; while [ \"$root\" != \"/\" ] && [ ! -f \"$root/.codex/hooks.json\" ]; do root=\"$(dirname \"$root\")\"; done; exec \"$root/.codex/bin/dores-hook-dispatch\" UserPromptSubmit \"$root\"'",
+            "statusMessage": "Dispatching prompt hook"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'root=\"$PWD\"; while [ \"$root\" != \"/\" ] && [ ! -f \"$root/.codex/hooks.json\" ]; do root=\"$(dirname \"$root\")\"; done; exec \"$root/.codex/bin/dores-hook-dispatch\" PreToolUse \"$root\"'",
+            "statusMessage": "Dispatching Bash pre-hook"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'root=\"$PWD\"; while [ \"$root\" != \"/\" ] && [ ! -f \"$root/.codex/hooks.json\" ]; do root=\"$(dirname \"$root\")\"; done; exec \"$root/.codex/bin/dores-hook-dispatch\" PostToolUse \"$root\"'",
+            "statusMessage": "Dispatching Bash post-hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'root=\"$PWD\"; while [ \"$root\" != \"/\" ] && [ ! -f \"$root/.codex/hooks.json\" ]; do root=\"$(dirname \"$root\")\"; done; exec \"$root/.codex/bin/dores-hook-dispatch\" Stop \"$root\"'",
+            "statusMessage": "Dispatching stop hook"
+          }
+        ]
+      }
+    ]
+  }
+}

package/INSTALL.md

@@ -0,0 +1,37 @@
+# Install Notes
+
+推荐安装流程：
+
+```bash
+env npm_config_cache=/tmp/dores-codex-npm-cache npm pack
+npm install -g ./dores-codex-4.0.0.tgz
+codex-plugin-setup
+```
+
+如果已经发布到 npm 仓库，也可以直接安装：
+
+```bash
+npm install -g dores-codex@4.0.0
+codex-plugin-setup
+```
+
+`codex-plugin-setup` 会自动：
+
+- 确保 `~/.codex/config.toml` 里启用了 `codex_hooks = true`
+- 把本插件的 hooks 安装到 `~/.codex/hooks.json`
+
+setup 完成后，直接运行原生 `codex` 即可触发全局 hooks。
+
+默认 websocket 地址：
+
+```text
+ws://127.0.0.1:8765
+```
+
+如果需要覆盖：
+
+```bash
+export CODEX_PLUGIN_APP_WS_URL=ws://127.0.0.1:8765
+```
+
+更完整的安装、触发和排查说明见 [README.md](./README.md)。

package/README.md

@@ -0,0 +1,231 @@
+# dores-codex
+
+`dores-codex` 是一个只基于原生 Codex 官方 hooks 的插件包。  
+它不会替换 `codex` 命令本身，也不会走桥接层；它做的事情是：
+
+- 把原生 Codex hooks 事件转成 websocket 消息
+- 默认发送到 `ws://127.0.0.1:8765`
+- 通过 `codex-plugin-setup` 把 hooks 安装到 `~/.codex/hooks.json`
+- 让你在任意目录启动原生 `codex` 时都能触发这套全局 hooks
+
+## 支持的原生 Hooks
+
+当前包只处理官方这 5 类 hooks：
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
+对应 websocket `event_type` 映射如下：
+
+- `SessionStart` -> `StartWork` 或 `ManualWorkRecovery`
+- `UserPromptSubmit` -> `Statistics`
+- `PreToolUse` -> `Statistics`
+- `PostToolUse` -> `Statistics` 或 `AutoDebugError`
+- `Stop` -> `EndWork`
+
+不再支持的旧能力：
+
+- 桥接 `bridge`
+- `notify` 驱动的 `TaskComplete`
+- 自定义 wrapper `codex`
+- HTTP 回调链路
+
+## 1. 打包本地 npm 包
+
+当前版本号是 `4.0.0`。
+
+在项目根目录执行：
+
+```bash
+env npm_config_cache=/tmp/dores-codex-npm-cache npm pack
+```
+
+执行后会生成本地包：
+
+```text
+dores-codex-4.0.0.tgz
+```
+
+## 2. 安装 npm 包
+
+推荐全局安装。这样 setup 写入的 hooks 会稳定指向全局安装路径，后续你在任何目录执行原生 `codex` 都能触发。
+
+如果你已经发布到 npm 仓库：
+
+```bash
+npm install -g dores-codex@4.0.0
+```
+
+如果你使用本地打包出来的 tgz：
+
+```bash
+npm install -g ./dores-codex-4.0.0.tgz
+```
+
+如果你只是临时测试，也可以本地安装：
+
+```bash
+npm install ./dores-codex-4.0.0.tgz
+```
+
+但本地安装不推荐长期使用，因为 hooks 会指向当前项目里的 `node_modules/dores-codex`，项目移动或删除后路径就会失效。
+
+## 3. 执行 Setup
+
+安装完包以后，**不是直接执行 `codex` 就会生效**。  
+你还需要先执行一次 setup，把 hooks 安装到 Codex 会读取的全局位置：
+
+```bash
+codex-plugin-setup
+```
+
+这个命令会做两件事：
+
+1. 确保 `~/.codex/config.toml` 里启用了：
+
+```toml
+[features]
+codex_hooks = true
+```
+
+2. 把本插件管理的 hooks 写入：
+
+```text
+~/.codex/hooks.json
+```
+
+写入的是带绝对路径的命令，所以 setup 完成后，你在任意目录执行原生 `codex`，都能加载这套全局 hooks。
+
+如果你本来就有自己的 `~/.codex/hooks.json`，`codex-plugin-setup` 会保留已有内容，只更新它自己管理的条目。  
+本插件管理的 hook 组会带有 `dores-codex:` 前缀，便于后续卸载和重装。
+
+## 4. WebSocket 地址
+
+默认 websocket 地址：
+
+```text
+ws://127.0.0.1:8765
+```
+
+如果你的服务端不是这个地址，可以在启动 `codex` 之前覆盖：
+
+```bash
+export CODEX_PLUGIN_APP_WS_URL=ws://127.0.0.1:8765
+```
+
+如果你不设置，默认就会连 `ws://127.0.0.1:8765`。
+
+## 5. 如何触发原生 Codex hooks
+
+setup 完成后，直接启动原生 `codex`：
+
+```bash
+codex
+```
+
+然后在交互里输入内容，不同场景会触发不同 hooks。
+
+### 场景 A：只测试会话开始和结束
+
+输入：
+
+```text
+1+1=?
+```
+
+通常会触发：
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `Stop`
+
+因为这类问题通常不需要调用 Bash。
+
+### 场景 B：测试 Bash 成功执行
+
+输入：
+
+```text
+Use Bash to run the command pwd exactly once, then reply with only the resulting directory path.
+```
+
+通常会触发：
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
+### 场景 C：测试 Bash 失败事件
+
+输入：
+
+```text
+Use Bash to run the command false exactly once, then reply with only the word failed.
+```
+
+通常会触发：
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `Stop`
+
+其中 `PostToolUse` 会因为非零退出码映射成 `AutoDebugError`。
+
+## 6. 如何判断 hooks 是否真的触发
+
+可以看两个地方：
+
+- 你的 websocket 服务端是否收到消息
+- 本地日志文件是否有 hook 执行记录
+
+默认日志路径在 setup 所安装的包目录运行时对应的：
+
+```text
+<package-root>/runtime/codex-plugin.log
+```
+
+如果 websocket 没收到消息，先检查：
+
+- `codex-plugin-setup` 是否执行过
+- `~/.codex/config.toml` 里是否真的启用了 `codex_hooks = true`
+- `~/.codex/hooks.json` 是否存在
+- websocket 服务是否真的监听在 `ws://127.0.0.1:8765`
+- 你运行的是原生 `codex`，不是别的 wrapper
+
+## 7. 卸载
+
+删除这套全局 hooks：
+
+```bash
+codex-plugin-uninstall
+```
+
+这个命令会从 `~/.codex/hooks.json` 里移除本插件写入的 managed hooks。  
+它不会自动把 `config.toml` 里的 `codex_hooks` 改回去。
+
+如果你还想彻底移除包：
+
+```bash
+npm uninstall -g dores-codex
+```
+
+## 8. 开发校验
+
+如果你在源码仓库里改了代码，可以先校验：
+
+```bash
+npm run check
+```
+
+再重新打包：
+
+```bash
+env npm_config_cache=/tmp/dores-codex-npm-cache npm pack
+```

package/codex-plugin-setup

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_path="${BASH_SOURCE[0]}"
+while [[ -L "$script_path" ]]; do
+  script_dir="$(cd "$(dirname "$script_path")" && pwd)"
+  script_path="$(readlink "$script_path")"
+  if [[ "$script_path" != /* ]]; then
+    script_path="$script_dir/$script_path"
+  fi
+done
+script_dir="$(cd "$(dirname "$script_path")" && pwd)"
+
+exec node "$script_dir/lib/setup-hooks.js" "$@"

package/codex-plugin-uninstall

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_path="${BASH_SOURCE[0]}"
+while [[ -L "$script_path" ]]; do
+  script_dir="$(cd "$(dirname "$script_path")" && pwd)"
+  script_path="$(readlink "$script_path")"
+  if [[ "$script_path" != /* ]]; then
+    script_path="$script_dir/$script_path"
+  fi
+done
+script_dir="$(cd "$(dirname "$script_path")" && pwd)"
+
+exec node "$script_dir/lib/uninstall-hooks.js" "$@"

package/install.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$script_dir/codex-plugin-setup" "$@"

package/lib/client-event.js

@@ -0,0 +1,144 @@
+function splitWords(value) {
+  return String(value ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean);
+}
+
+function toPascalCase(value) {
+  return splitWords(value)
+    .map((part) => part[0].toUpperCase() + part.slice(1).toLowerCase())
+    .join("");
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") {
+      continue;
+    }
+
+    const trimmed = value.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+
+  return "";
+}
+
+function normalizeTurnStatus(payload = null) {
+  return firstString(
+    payload?.status,
+    payload?.turn?.status,
+    payload?.params?.turn?.status,
+    payload?.params?.status?.type
+  ).toLowerCase();
+}
+
+function normalizeEventIde(value) {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  return normalized || "codex";
+}
+
+function normalizeHookEventName(event, payload = null) {
+  return firstString(payload?.hook_event_name, event, payload?.event);
+}
+
+function normalizeStartSource(payload = null) {
+  return firstString(payload?.start_source, payload?.raw?.source).toLowerCase();
+}
+
+function normalizeExitCode(payload = null) {
+  return Number.isFinite(payload?.exit_code) ? payload.exit_code : null;
+}
+
+export function resolveClientEventType(event, payload = null) {
+  const hookEventName = normalizeHookEventName(event, payload);
+
+  switch (hookEventName) {
+    case "SessionStart":
+      return normalizeStartSource(payload) === "resume"
+        ? "ManualWorkRecovery"
+        : "StartWork";
+    case "UserPromptSubmit":
+    case "PreToolUse":
+      return "Statistics";
+    case "PostToolUse": {
+      const exitCode = normalizeExitCode(payload);
+      return exitCode != null && exitCode !== 0 ? "AutoDebugError" : "Statistics";
+    }
+    case "Stop":
+      return "EndWork";
+    default:
+      return `Codex${toPascalCase(hookEventName || "hook")}`;
+  }
+}
+
+export function resolveClientEventPhase(event, payload = null) {
+  const eventType = resolveClientEventType(event, payload);
+
+  switch (eventType) {
+    case "StartWork":
+      return "start";
+    case "ManualWorkRecovery":
+      return "recovery";
+    case "Statistics":
+      return "progress";
+    case "AutoDebugError":
+      return "error";
+    case "EndWork":
+      return "stop";
+    default:
+      return "custom";
+  }
+}
+
+export function buildClientEventData(event, payload = null) {
+  return {
+    command: payload?.command ?? null,
+    cwd: payload?.cwd ?? null,
+    event_phase: resolveClientEventPhase(event, payload),
+    exit_code: payload?.exit_code ?? null,
+    hook_event: normalizeHookEventName(event, payload) || null,
+    hook_event_name: payload?.hook_event_name ?? null,
+    input_text: payload?.input_text ?? null,
+    last_assistant_message:
+      payload?.last_assistant_message ??
+      payload?.raw?.["last-assistant-message"] ??
+      null,
+    message: payload?.message ?? null,
+    model: payload?.model ?? null,
+    ok: payload?.ok ?? null,
+    reason: payload?.reason ?? null,
+    session_id: payload?.session_id ?? null,
+    source: payload?.source ?? null,
+    start_source: payload?.start_source ?? null,
+    status: firstString(payload?.status, normalizeTurnStatus(payload)) || null,
+    stop_hook_active:
+      typeof payload?.stop_hook_active === "boolean"
+        ? payload.stop_hook_active
+        : null,
+    timestamp: payload?.timestamp ?? new Date().toISOString(),
+    transcript_path: payload?.transcript_path ?? null,
+    tool_name: payload?.tool_name ?? null,
+    tool_use_id: payload?.tool_use_id ?? null,
+    turn_id: payload?.turn_id ?? null,
+    payload: payload ?? {}
+  };
+}
+
+export function buildClientEventMessage(
+  event,
+  payload,
+  { eventIde = "codex", source = "codex-native-hook" } = {}
+) {
+  return {
+    type: "client_event",
+    source,
+    data: {
+      event_type: resolveClientEventType(event, payload),
+      event_ide: normalizeEventIde(eventIde),
+      event_data: buildClientEventData(event, payload)
+    }
+  };
+}

package/lib/dores-client.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+export const DEFAULT_DORES_CLIENT_WS_URL = "ws://127.0.0.1:8765";
+export const DORES_CLIENT_UNAVAILABLE_MESSAGE =
+  "dores客户端未启动，请启动后再重试当前命令";
+
+export class DoresClientUnavailableError extends Error {
+  constructor(
+    message = DORES_CLIENT_UNAVAILABLE_MESSAGE,
+    { cause = null, url = DEFAULT_DORES_CLIENT_WS_URL } = {}
+  ) {
+    super(message);
+    this.name = "DoresClientUnavailableError";
+    this.code = "dores_client_unavailable";
+    this.url = url;
+    if (cause) {
+      this.cause = cause;
+    }
+  }
+}
+
+function readErrorMessage(error) {
+  return error instanceof Error ? error.message.trim() : String(error ?? "").trim();
+}
+
+export function isDoresClientUnavailableError(error) {
+  return (
+    error instanceof DoresClientUnavailableError ||
+    error?.code === "dores_client_unavailable" ||
+    error?.code === "live2d_client_unavailable"
+  );
+}
+
+function looksLikeDoresClientConnectionFailure(message) {
+  if (!message) {
+    return true;
+  }
+
+  return (
+    /failed to connect/i.test(message) ||
+    /websocket connection failed/i.test(message) ||
+    /timed out while connecting/i.test(message) ||
+    /socket closed before/i.test(message) ||
+    /econnrefused/i.test(message)
+  );
+}
+
+export function normalizeDoresClientConnectionError(
+  error,
+  { url = DEFAULT_DORES_CLIENT_WS_URL } = {}
+) {
+  if (isDoresClientUnavailableError(error)) {
+    return error;
+  }
+
+  const message = readErrorMessage(error);
+  if (looksLikeDoresClientConnectionFailure(message)) {
+    return new DoresClientUnavailableError(undefined, {
+      cause: error instanceof Error ? error : null,
+      url
+    });
+  }
+
+  return error instanceof Error ? error : new Error(message || String(error));
+}
+
+export function formatDoresClientErrorMessage(
+  error,
+  { fallbackMessage = "操作失败，请稍后重试。" } = {}
+) {
+  if (isDoresClientUnavailableError(error)) {
+    return error.message || DORES_CLIENT_UNAVAILABLE_MESSAGE;
+  }
+
+  return readErrorMessage(error) || fallbackMessage;
+}