cx-viewer 1.0.0

package/lib/codex-config.js

@@ -0,0 +1,146 @@
+/**
+ * Codex config.toml management utility
+ * Reads/writes openai_base_url in Codex's TOML config files
+ * to redirect API traffic through the cxv proxy.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, copyFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const BACKUP_SUFFIX = '.cxv-backup';
+
+/**
+ * Older CX-Viewer versions could leave a loopback proxy URL in Codex's global
+ * config.toml. Treat that as stale and fall back to settings.json / env instead.
+ * Legit local overrides should be configured in settings.json or OPENAI_BASE_URL.
+ */
+export function isStaleLocalCodexBaseUrl(url) {
+  if (!url || typeof url !== 'string') return false;
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname;
+    const isLoopback = host === '127.0.0.1'
+      || host === 'localhost'
+      || host === '::1'
+      || host === '::ffff:127.0.0.1';
+    if (!isLoopback) return false;
+    return parsed.pathname === '' || parsed.pathname === '/';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a simple key = "value" from a TOML file
+ */
+function readTomlValue(filePath, key) {
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf-8');
+    const match = content.match(new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, 'm'));
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the original Codex base URL from user-level or system-level config.toml
+ * (Skips project-level to avoid reading our own proxy URL)
+ */
+export function getOriginalCodexBaseUrl() {
+  // User config
+  const userUrl = readTomlValue(join(homedir(), '.codex', 'config.toml'), 'openai_base_url');
+  if (userUrl && !isStaleLocalCodexBaseUrl(userUrl)) return userUrl;
+
+  // System config
+  const systemUrl = readTomlValue('/etc/codex/config.toml', 'openai_base_url');
+  return isStaleLocalCodexBaseUrl(systemUrl) ? null : systemUrl;
+}
+
+/**
+ * Set openai_base_url in project-level .codex/config.toml to redirect traffic.
+ * Backs up existing config and returns a cleanup function to restore it.
+ *
+ * @param {string} projectDir - workspace/project directory
+ * @param {string} proxyUrl - proxy URL (e.g. "http://127.0.0.1:PORT")
+ * @returns {() => void} cleanup function to restore original config
+ */
+export function setProjectCodexBaseUrl(projectDir, proxyUrl) {
+  const configDir = join(projectDir, '.codex');
+  const configPath = join(configDir, 'config.toml');
+  const backupPath = configPath + BACKUP_SUFFIX;
+
+  try { mkdirSync(configDir, { recursive: true }); } catch (err) { console.warn('[CX Viewer] mkdirSync failed:', configDir, err.message); }
+
+  // Backup existing config
+  let hadOriginal = false;
+  if (existsSync(configPath)) {
+    try {
+      copyFileSync(configPath, backupPath);
+      hadOriginal = true;
+    } catch (err) { console.warn('[CX Viewer] Config backup failed:', err.message); }
+  }
+
+  // Read existing content or start fresh
+  let content = '';
+  try {
+    if (existsSync(configPath)) {
+      content = readFileSync(configPath, 'utf-8');
+    }
+  } catch (err) { console.warn('[CX Viewer] Config read failed:', err.message); }
+
+  // Update or append openai_base_url
+  const regex = /^openai_base_url\s*=\s*"[^"]*"/m;
+  if (regex.test(content)) {
+    content = content.replace(regex, `openai_base_url = "${proxyUrl}"`);
+  } else {
+    // Append after any existing content
+    const trimmed = content.trimEnd();
+    content = trimmed ? trimmed + `\nopenai_base_url = "${proxyUrl}"\n` : `openai_base_url = "${proxyUrl}"\n`;
+  }
+
+  try {
+    writeFileSync(configPath, content);
+  } catch (err) {
+    console.error('[CX Viewer] Failed to write Codex config:', err.message);
+  }
+
+  // Return cleanup function
+  return function restoreCodexConfig() {
+    try {
+      if (hadOriginal && existsSync(backupPath)) {
+        copyFileSync(backupPath, configPath);
+        unlinkSync(backupPath);
+      } else if (!hadOriginal) {
+        // We created this config — remove our key or the whole file
+        if (existsSync(configPath)) {
+          const current = readFileSync(configPath, 'utf-8');
+          const cleaned = current.replace(/^openai_base_url\s*=\s*"[^"]*"\n?/gm, '').trim();
+          if (cleaned) {
+            writeFileSync(configPath, cleaned + '\n');
+          } else {
+            unlinkSync(configPath);
+          }
+        }
+        if (existsSync(backupPath)) unlinkSync(backupPath);
+      }
+    } catch (err) { console.warn('[CX Viewer] Config restore failed:', err.message); }
+  };
+}
+
+/**
+ * Restore config from backup on startup (in case of previous crash).
+ * Call this early in the startup sequence.
+ */
+export function restoreCrashBackup(projectDir) {
+  const configPath = join(projectDir, '.codex', 'config.toml');
+  const backupPath = configPath + BACKUP_SUFFIX;
+  try {
+    if (existsSync(backupPath)) {
+      copyFileSync(backupPath, configPath);
+      unlinkSync(backupPath);
+    }
+  } catch (err) { console.warn('[CX Viewer] Crash backup restore failed:', err.message); }
+}

package/lib/constants.js

@@ -0,0 +1,26 @@
+/**
+ * Shared constants for cx-viewer
+ */
+
+// Server port range
+export const DEFAULT_START_PORT = 7008;
+export const DEFAULT_MAX_PORT = 7099;
+
+// Log management
+export const MAX_LOG_SIZE = 300 * 1024 * 1024;   // 300MB — trigger rotation
+export const CHECKPOINT_INTERVAL = 10;             // entries between delta checkpoints
+
+// HTTP limits
+export const MAX_POST_BODY = 10 * 1024 * 1024;    // 10MB
+export const MAX_UPLOAD_SIZE = 100 * 1024 * 1024;  // 100MB
+
+// Timers
+export const SSE_HEARTBEAT_MS = 30_000;            // 30s SSE ping
+export const HOOK_TIMEOUT_MS = 5 * 60 * 1000;     // 5min hook execution timeout
+export const EDITOR_SESSION_CLEANUP_MS = 3_600_000; // 1h stale editor session cleanup
+
+// Paths
+export const UPLOAD_DIR = '/tmp/cx-viewer-uploads';
+
+// API defaults
+export const DEFAULT_API_BASE = 'https://api.openai.com';

package/lib/context-watcher.js

@@ -0,0 +1,85 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const CONTEXT_WINDOW_FILE = join(homedir(), '.codex', 'context-window.json');
+export const CLAUDE_SETTINGS_FILE = join(homedir(), '.codex', 'settings.json');
+
+// Startup cache: read once, never re-read unless model changes
+let _startupModelBase = null;   // e.g. 'opus-4-6'
+let _startupContextSize = null; // e.g. 1000000
+
+/**
+ * Read context-window.json once at startup and cache model→size mapping.
+ * Extracts model base name (e.g. 'opus-4-6') and context size from model.id (e.g. 'codex-opus-4-6[1m]').
+ * @returns {{ modelId: string|null, contextSize: number }}
+ */
+export function readModelContextSize() {
+  try {
+    if (!existsSync(CONTEXT_WINDOW_FILE)) return { modelId: null, contextSize: 200000 };
+    const raw = readFileSync(CONTEXT_WINDOW_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    const modelId = data?.model?.id || null;
+    let contextSize = 200000;
+    if (modelId) {
+      const lower = modelId.toLowerCase();
+      const sizeMatch = lower.match(/\[(\d+)([km])\]/);
+      if (sizeMatch) {
+        const num = parseInt(sizeMatch[1], 10);
+        contextSize = sizeMatch[2] === 'm' ? num * 1000000 : num * 1000;
+      } else if (/opus/i.test(lower)) {
+        // Opus models default to 1M context
+        contextSize = 1000000;
+      }
+      // Cache the base name → size mapping
+      const base = lower.replace(/^codex-/i, '').replace(/\[.*\]/, '').trim();
+      _startupModelBase = base;
+      _startupContextSize = contextSize;
+    }
+    return { modelId, contextSize };
+  } catch {
+    return { modelId: null, contextSize: 200000 };
+  }
+}
+
+/**
+ * Get context size for a given API model name (e.g. 'codex-opus-4-6-20250514').
+ * Uses startup cache to avoid re-reading the file.
+ * @param {string} apiModelName - model name from req.body.model
+ * @returns {number} context window size in tokens
+ */
+export function getContextSizeForModel(apiModelName) {
+  if (!apiModelName) return _startupContextSize || 200000;
+  const lower = apiModelName.toLowerCase();
+  // Extract base: 'codex-opus-4-6-20250514' → 'opus-4-6'
+  const base = lower.replace(/^codex-/i, '').replace(/-\d{8}$/, '').trim();
+  // Match against startup cache
+  if (_startupModelBase && base === _startupModelBase) {
+    return _startupContextSize;
+  }
+  // Opus always has 1M context; other unknown models default to 200K
+  if (/opus/i.test(lower)) return 1000000;
+  return 200000;
+}
+
+/**
+ * Build a context_window SSE event payload from API usage data.
+ * @param {object} usage - API response usage object
+ * @param {number} contextSize - total context window size in tokens
+ * @returns {object|null} context_window event data, or null if usage missing
+ */
+export function buildContextWindowEvent(usage, contextSize) {
+  if (!usage) return null;
+  const inputTokens = (usage.input_tokens || 0) + (usage.cache_creation_input_tokens || 0) + (usage.cache_read_input_tokens || 0);
+  const outputTokens = usage.output_tokens || 0;
+  const totalTokens = inputTokens + outputTokens;
+  const usedPct = Math.round((totalTokens / contextSize) * 100);
+  return {
+    total_input_tokens: inputTokens,
+    total_output_tokens: outputTokens,
+    context_window_size: contextSize,
+    current_usage: usage,
+    used_percentage: usedPct,
+    remaining_percentage: 100 - usedPct,
+  };
+}

package/lib/cxv-editor.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * cxv-editor.js — Custom $EDITOR wrapper for cx-viewer.
+ *
+ * When Codex spawns $EDITOR (e.g. /memory), this script is invoked instead.
+ * It notifies the cx-viewer server to open the file in the built-in FileContentView,
+ * then polls until the user closes the editor in the web UI.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+
+const filePath = resolve(process.argv[2] || '');
+if (!filePath) {
+  console.error('Usage: cxv-editor <file>');
+  process.exit(1);
+}
+
+const port = process.env.CXV_EDITOR_PORT;
+if (!port) {
+  console.error('CXV_EDITOR_PORT not set');
+  process.exit(1);
+}
+
+const sessionId = randomUUID();
+const baseUrl = `http://127.0.0.1:${port}`;
+const POLL_INTERVAL = 500;
+const TIMEOUT = 30 * 60 * 1000; // 30 minutes
+
+async function main() {
+  // Notify server to open editor
+  try {
+    const res = await fetch(`${baseUrl}/api/editor-open`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, filePath }),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      console.error('Failed to open editor:', err);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error('Failed to connect to cx-viewer server:', err.message);
+    process.exit(1);
+  }
+
+  // Poll until done
+  const start = Date.now();
+  while (true) {
+    if (Date.now() - start > TIMEOUT) {
+      console.error('Editor session timed out');
+      process.exit(1);
+    }
+
+    await new Promise(r => setTimeout(r, POLL_INTERVAL));
+
+    try {
+      const res = await fetch(`${baseUrl}/api/editor-status?id=${sessionId}`);
+      if (!res.ok) continue;
+      const data = await res.json();
+      if (data.done) {
+        process.exit(0);
+      }
+    } catch {
+      // Connection error — server may have restarted, exit
+      process.exit(1);
+    }
+  }
+}
+
+main();

package/lib/delta-reconstructor.js

@@ -0,0 +1,256 @@
+/**
+ * Delta Reconstructor — 增量日志重建模块
+ *
+ * 将 delta 格式的日志条目重建为完整的 messages 数组。
+ * 仅处理 mainAgent 条目，teammate/旧格式条目直接跳过。
+ *
+ * 提供三种 API：
+ * - reconstructEntries(entries): 批量重建，用于 readLogFile() 和 readLocalLog()
+ * - reconstructSegment(segment, nextCheckpoint): 段级重建，用于流式分段处理
+ * - createIncrementalReconstructor(): 有状态的增量重建器，用于 watcher 逐条重建
+ */
+
+/**
+ * 判断一个条目是否为 checkpoint（应重置累积状态）。
+ * 三种情况视为 checkpoint：
+ * 1. 无 _deltaFormat 字段 → 旧格式全量条目
+ * 2. _isCheckpoint === true → 显式 checkpoint
+ * 3. _totalMessageCount === body.messages.length → 隐式 checkpoint（delta 长度 === 总长度）
+ */
+export function isCheckpointEntry(entry) {
+  // 无 _deltaFormat：旧格式全量条目
+  if (!entry._deltaFormat) return true;
+  // 显式 checkpoint
+  if (entry._isCheckpoint) return true;
+  // 隐式 checkpoint：delta 长度等于总长度
+  const msgs = entry.body?.messages;
+  if (Array.isArray(msgs) && entry._totalMessageCount === msgs.length) return true;
+  return false;
+}
+
+/**
+ * 判断一个条目是否为需要重建的 delta 条目（mainAgent + _deltaFormat）。
+ */
+export function isDeltaEntry(entry) {
+  return entry._deltaFormat && entry.mainAgent;
+}
+
+/**
+ * 批量重建 — 用于 readLogFile() 和 readLocalLog()。
+ * 输入已去重的条目数组，输出重建后的条目数组（原地修改 body.messages）。
+ * 非 mainAgent delta 条目不受影响。
+ *
+ * @param {Array} entries - 已去重、按时间顺序排列的条目数组
+ * @returns {Array} 重建后的条目数组（同一引用，原地修改）
+ */
+export function reconstructEntries(entries) {
+  // 第一遍：正向重建
+  let accumulated = []; // mainAgent 累积 messages
+  const broken = [];    // 记录重建失败的条目索引（用于第二遍补偿）
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    // 跳过 inProgress 条目：孤立的 inProgress（请求超时未完成）在 dedup 后残留，
+    // 其 delta 与后续 completed 条目重复，双重累积会导致 accumulated 偏移
+    // （与 createIncrementalReconstructor line 209 保持一致）
+    if (entry.inProgress) continue;
+    if (!isDeltaEntry(entry)) {
+      // 非 delta 条目（旧格式 / teammate）：如果是 mainAgent 旧格式，重置累积状态
+      if (entry.mainAgent && Array.isArray(entry.body?.messages)) {
+        accumulated = [...entry.body.messages];
+      }
+      continue;
+    }
+
+    // delta 条目处理
+    const msgs = entry.body?.messages;
+    if (!Array.isArray(msgs)) continue;
+
+    if (isCheckpointEntry(entry)) {
+      // checkpoint：用当前 messages 重置累积状态
+      accumulated = [...msgs];
+    } else {
+      // delta：拼接到累积数组
+      accumulated = [...accumulated, ...msgs];
+      // 挂载重建后的完整 messages（checkpoint/旧格式条目保持不变）
+      entry.body.messages = accumulated;
+      if (entry._totalMessageCount && accumulated.length !== entry._totalMessageCount) {
+        broken.push(i);
+      }
+    }
+  }
+
+  // 第二遍：补偿修复 — 用后续最近的 checkpoint 回填断裂的条目
+  if (broken.length > 0) {
+    _compensateBrokenEntries(entries, broken);
+  }
+
+  return entries;
+}
+
+/**
+ * 补偿修复：对断裂的 delta 条目，从后续最近的 checkpoint 中提取完整 messages 回填。
+ * checkpoint 包含截至该点的完整历史，可以据此反推之前条目的 messages。
+ */
+function _compensateBrokenEntries(entries, brokenIndices) {
+  for (const brokenIdx of brokenIndices) {
+    const brokenEntry = entries[brokenIdx];
+    const expectedCount = brokenEntry._totalMessageCount;
+    if (!expectedCount) continue;
+
+    // 向后查找最近的 checkpoint 或旧格式全量条目
+    for (let j = brokenIdx + 1; j < entries.length; j++) {
+      const candidate = entries[j];
+      if (!candidate.mainAgent || !Array.isArray(candidate.body?.messages)) continue;
+
+      const candidateMsgs = candidate.body.messages;
+      const candidateTotal = candidate._totalMessageCount || candidateMsgs.length;
+
+      // 候选条目必须是 checkpoint/旧格式且包含足够的 messages
+      const isFullEntry = !candidate._deltaFormat || isCheckpointEntry(candidate);
+      if (isFullEntry && candidateTotal >= expectedCount) {
+        // 从完整 messages 中截取前 expectedCount 条作为补偿
+        brokenEntry.body.messages = candidateMsgs.slice(0, expectedCount);
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * 段级重建 — 用于流式分段处理。
+ * 对一个 checkpoint 边界内的段进行正向重建，如有 broken 条目则用 nextCheckpoint 反向修复。
+ * 段内条目数通常 ≤ CHECKPOINT_INTERVAL(10)，内存开销可控。
+ *
+ * @param {Array} segment - 段内条目数组（段首应为 checkpoint/旧格式条目）
+ * @param {object|null} nextCheckpoint - 下一个 checkpoint 条目（用于反向修复），最后一段可为 null
+ * @returns {Array} 重建后的段条目数组（原地修改）
+ */
+export function reconstructSegment(segment, nextCheckpoint) {
+  let accumulated = [];
+  const broken = [];
+
+  for (let i = 0; i < segment.length; i++) {
+    const entry = segment[i];
+    if (entry.inProgress) continue;
+    if (!isDeltaEntry(entry)) {
+      if (entry.mainAgent && Array.isArray(entry.body?.messages)) {
+        accumulated = [...entry.body.messages];
+      }
+      continue;
+    }
+
+    const msgs = entry.body?.messages;
+    if (!Array.isArray(msgs)) continue;
+
+    if (isCheckpointEntry(entry)) {
+      accumulated = [...msgs];
+    } else {
+      accumulated = [...accumulated, ...msgs];
+      entry.body.messages = accumulated;
+      if (entry._totalMessageCount && accumulated.length !== entry._totalMessageCount) {
+        broken.push(i);
+      }
+    }
+  }
+
+  // 补偿修复：先在段内向后查找，再用 nextCheckpoint
+  if (broken.length > 0) {
+    for (const brokenIdx of broken) {
+      const brokenEntry = segment[brokenIdx];
+      const expectedCount = brokenEntry._totalMessageCount;
+      if (!expectedCount) continue;
+
+      let repaired = false;
+      // 段内向后查找
+      for (let j = brokenIdx + 1; j < segment.length; j++) {
+        const candidate = segment[j];
+        if (!candidate.mainAgent || !Array.isArray(candidate.body?.messages)) continue;
+        const candidateMsgs = candidate.body.messages;
+        const candidateTotal = candidate._totalMessageCount || candidateMsgs.length;
+        const isFullEntry = !candidate._deltaFormat || isCheckpointEntry(candidate);
+        if (isFullEntry && candidateTotal >= expectedCount) {
+          brokenEntry.body.messages = candidateMsgs.slice(0, expectedCount);
+          repaired = true;
+          break;
+        }
+      }
+      // 段内未找到，用 nextCheckpoint 修复
+      if (!repaired && nextCheckpoint) {
+        const cpMsgs = nextCheckpoint.body?.messages;
+        const cpTotal = nextCheckpoint._totalMessageCount || cpMsgs?.length || 0;
+        if (Array.isArray(cpMsgs) && cpTotal >= expectedCount) {
+          brokenEntry.body.messages = cpMsgs.slice(0, expectedCount);
+        }
+      }
+    }
+  }
+
+  return segment;
+}
+
+/**
+ * 创建有状态的增量重建器 — 用于 watcher 逐条重建。
+ * 每次调用 reconstruct(entry) 处理一条新条目。
+ *
+ * @returns {{ reconstruct: (entry: object) => object }}
+ */
+export function createIncrementalReconstructor() {
+  let accumulated = []; // mainAgent 累积 messages
+
+  return {
+    /**
+     * 重建单条条目。
+     * - 非 delta 条目：如果是 mainAgent 旧格式，更新累积状态，原样返回
+     * - checkpoint：重置累积状态，原样返回
+     * - delta：拼接重建，修改 body.messages 后返回
+     *
+     * @param {object} entry - 单条日志条目
+     * @returns {object} 重建后的条目（同一引用）
+     */
+    reconstruct(entry) {
+      // inProgress 条目：用 accumulated 副本重建 messages，但不更新 accumulated 本身。
+      // 这样客户端收到完整 messages（避免 delta 闪烁），
+      // 而后续 completed 条目仍能基于正确的 accumulated 重建。
+      if (entry.inProgress) {
+        if (isDeltaEntry(entry) && !isCheckpointEntry(entry)) {
+          const msgs = entry.body?.messages;
+          if (Array.isArray(msgs)) {
+            entry.body.messages = [...accumulated, ...msgs];
+          }
+        }
+        return entry;
+      }
+
+      if (!isDeltaEntry(entry)) {
+        // 非 delta 条目：如果是 mainAgent 旧格式，更新累积状态
+        if (entry.mainAgent && Array.isArray(entry.body?.messages)) {
+          accumulated = [...entry.body.messages];
+        }
+        return entry;
+      }
+
+      const msgs = entry.body?.messages;
+      if (!Array.isArray(msgs)) return entry;
+
+      if (isCheckpointEntry(entry)) {
+        // checkpoint：重置累积状态
+        accumulated = [...msgs];
+      } else {
+        // delta：拼接
+        accumulated = [...accumulated, ...msgs];
+        entry.body.messages = accumulated;
+      }
+
+      return entry;
+    },
+
+    /**
+     * 重置累积状态（用于 full_reload 等场景）。
+     */
+    reset() {
+      accumulated = [];
+    }
+  };
+}
+

package/lib/ensure-hooks.js

@@ -0,0 +1,88 @@
+/**
+ * Register AskUserQuestion and permission approval hooks into ~/.codex/settings.json.
+ * Shared between cli.js and electron/tab-worker.js.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = resolve(__dirname, '..');
+
+export function ensureHooks() {
+  try {
+    const codexDir = resolve(homedir(), '.codex');
+    const settingsPath = resolve(codexDir, 'settings.json');
+    let settings = {};
+    try { if (existsSync(settingsPath)) settings = JSON.parse(readFileSync(settingsPath, 'utf-8')); } catch {
+      console.warn('[CX Viewer] ~/.codex/settings.json is malformed, skipping hook injection');
+      return;
+    }
+
+    if (!settings.hooks) settings.hooks = {};
+    if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+
+    let changed = false;
+
+    // AskUserQuestion hook → ask-bridge.js
+    // Guard: only execute when CXVIEWER_PORT is set (i.e. launched by cx-viewer)
+    const askBridgePath = resolve(rootDir, 'lib', 'ask-bridge.js');
+    const askCmd = `[ -n "$CXVIEWER_PORT" ] && node "${askBridgePath}" || true`;
+    const askExisting = settings.hooks.PreToolUse.find(h => h.matcher === 'AskUserQuestion');
+    if (askExisting) {
+      if ((askExisting.hooks?.[0]?.command || '') !== askCmd) {
+        askExisting.hooks = [{ type: 'command', command: askCmd }];
+        changed = true;
+      }
+    } else {
+      settings.hooks.PreToolUse.push({
+        matcher: 'AskUserQuestion',
+        hooks: [{ type: 'command', command: askCmd }]
+      });
+      changed = true;
+    }
+
+    // Permission approval hook → perm-bridge.js (matcher: "" = match all tools)
+    // Guard: only execute when CXVIEWER_PORT is set (i.e. launched by cx-viewer)
+    const permBridgePath = resolve(rootDir, 'lib', 'perm-bridge.js');
+    const permCmd = `[ -n "$CXVIEWER_PORT" ] && node "${permBridgePath}" || true`;
+    const permMatcher = '';
+    // Clean up legacy entries
+    for (let i = settings.hooks.PreToolUse.length - 1; i >= 0; i--) {
+      const h = settings.hooks.PreToolUse[i];
+      const cmd = h.hooks?.[0]?.command || '';
+      if (cmd.includes('perm-bridge.js') && h.matcher !== permMatcher) {
+        settings.hooks.PreToolUse.splice(i, 1);
+        changed = true;
+      } else if ((h.matcher === null || h.matcher === undefined) && cmd.includes('perm-bridge.js')) {
+        settings.hooks.PreToolUse.splice(i, 1);
+        changed = true;
+      } else if (h.matcher === 'Bash' && cmd.includes('grep') && /git|npm/.test(cmd)) {
+        settings.hooks.PreToolUse.splice(i, 1);
+        changed = true;
+      }
+    }
+    const permExisting = settings.hooks.PreToolUse.find(h => h.matcher === permMatcher);
+    if (permExisting) {
+      if ((permExisting.hooks?.[0]?.command || '') !== permCmd) {
+        permExisting.hooks = [{ type: 'command', command: permCmd }];
+        changed = true;
+      }
+    } else {
+      settings.hooks.PreToolUse.push({
+        matcher: permMatcher,
+        hooks: [{ type: 'command', command: permCmd }]
+      });
+      changed = true;
+    }
+
+    if (changed) {
+      mkdirSync(codexDir, { recursive: true });
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    }
+  } catch (err) {
+    console.warn('[CX Viewer] Failed to ensure hooks:', err.message);
+  }
+}

package/lib/extract-plugin-name.mjs

@@ -0,0 +1,18 @@
+/**
+ * 在隔离子进程中提取插件 name，避免不安全的插件代码影响主进程。
+ * 用法: node lib/extract-plugin-name.mjs <file-path>
+ * 输出: JSON { name: string } 到 stdout
+ */
+const filePath = process.argv[2];
+if (!filePath) {
+  process.stdout.write(JSON.stringify({ name: '' }));
+  process.exit(0);
+}
+try {
+  const mod = await import(`file://${filePath}`);
+  const plugin = mod.default || mod;
+  process.stdout.write(JSON.stringify({ name: plugin.name || '' }));
+} catch {
+  process.stdout.write(JSON.stringify({ name: '' }));
+}
+process.exit(0);