skill-codex 0.7.1 → 0.8.0

package/dist/bin/skill-codex.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // bin/skill-codex.ts
-import fs8 from "fs";
-import path10 from "path";
+import fs11 from "fs";
+import path13 from "path";
 import { fileURLToPath } from "url";
 
 // setup/setup.ts
@@ -479,14 +479,1180 @@ async function runUninstall() {
   log("[ok]", "Uninstall complete. Restart Claude Code to apply changes.");
 }
 
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools/codex-exec.ts
+import fs10 from "fs";
+import path12 from "path";
+import { z } from "zod";
+
+// src/errors/errors.ts
+var BridgeError = class extends Error {
+  code;
+  retryable;
+  constructor(message, code, retryable) {
+    super(message);
+    this.name = "BridgeError";
+    this.code = code;
+    this.retryable = retryable;
+  }
+};
+var CliNotFoundError = class extends BridgeError {
+  constructor(binary = "codex") {
+    super(
+      `${binary} CLI not found on PATH. Install it with: npm i -g @openai/codex`,
+      "CLI_NOT_FOUND",
+      false
+    );
+    this.name = "CliNotFoundError";
+  }
+};
+var AuthExpiredError = class extends BridgeError {
+  constructor() {
+    super(
+      "Codex authentication expired or not found. Run `codex login` to re-authenticate.",
+      "AUTH_EXPIRED",
+      false
+    );
+    this.name = "AuthExpiredError";
+  }
+};
+var RecursionLimitError = class extends BridgeError {
+  constructor(depth, max) {
+    super(
+      `Maximum bridge nesting depth reached (${depth} >= ${max}). This prevents infinite recursion between Claude and Codex.`,
+      "RECURSION_LIMIT",
+      false
+    );
+    this.name = "RecursionLimitError";
+  }
+};
+var LockConflictError = class extends BridgeError {
+  constructor(pid) {
+    super(
+      `Another skill-codex instance is running (PID ${pid}). Wait for it to finish or delete the lock file.`,
+      "LOCK_CONFLICT",
+      false
+    );
+    this.name = "LockConflictError";
+  }
+};
+var TimeoutError = class extends BridgeError {
+  constructor(timeoutMs) {
+    super(
+      `Codex timed out after ${Math.round(timeoutMs / 1e3)}s. Increase SKILL_CODEX_TIMEOUT_MS if needed.`,
+      "TIMEOUT",
+      true
+    );
+    this.name = "TimeoutError";
+  }
+};
+var RateLimitError = class extends BridgeError {
+  constructor() {
+    super(
+      "Codex rate limited (429). Will retry with backoff.",
+      "RATE_LIMIT",
+      true
+    );
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends BridgeError {
+  constructor(detail = "") {
+    super(
+      `Codex server error${detail ? `: ${detail}` : ""}. Will retry.`,
+      "SERVER_ERROR",
+      true
+    );
+    this.name = "ServerError";
+  }
+};
+var NetworkError = class extends BridgeError {
+  constructor(detail = "") {
+    super(
+      `Network error connecting to Codex${detail ? `: ${detail}` : ""}. Check your connection.`,
+      "NETWORK_ERROR",
+      true
+    );
+    this.name = "NetworkError";
+  }
+};
+var EmptyOutputError = class extends BridgeError {
+  constructor() {
+    super(
+      "Codex returned empty output. This may be a transient issue.",
+      "EMPTY_OUTPUT",
+      true
+    );
+    this.name = "EmptyOutputError";
+  }
+};
+var NotGitRepoError = class extends BridgeError {
+  constructor(cwd) {
+    super(
+      `Not a git repository: ${cwd}. This operation requires a git repo.`,
+      "NOT_GIT_REPO",
+      false
+    );
+    this.name = "NotGitRepoError";
+  }
+};
+
+// src/config/constants.ts
+var MAX_BRIDGE_DEPTH = 2;
+var BRIDGE_DEPTH_ENV = "SKILL_CODEX_DEPTH";
+var DEFAULT_TIMEOUT_MS = 3e5;
+var TIMEOUT_ENV = "SKILL_CODEX_TIMEOUT_MS";
+var KILL_GRACE_MS = 5e3;
+var HEARTBEAT_INTERVAL_MS = 1e4;
+var MAX_RETRIES = 3;
+var MAX_RETRIES_ENV = "SKILL_CODEX_MAX_RETRIES";
+var RETRY_DELAYS_MS = [1e3, 2e3, 4e3];
+var RETRY_CAP_MS = 1e4;
+var MAX_RESPONSE_CHARS = 8e4;
+var LOCK_STALE_MS = 9e5;
+var LOCK_FILENAME = ".skill-codex.lock";
+var LOG_ENV = "SKILL_CODEX_LOG";
+var WINDOWS_SANDBOX_ENV = "SKILL_CODEX_WINDOWS_SANDBOX";
+var WINDOWS_SANDBOX_DEFAULT = "unelevated";
+
+// src/guards/check-recursion.ts
+function getCurrentDepth() {
+  return parseInt(process.env[BRIDGE_DEPTH_ENV] ?? "0", 10);
+}
+function getNextDepth() {
+  return getCurrentDepth() + 1;
+}
+function checkRecursion() {
+  const depth = getCurrentDepth();
+  if (depth >= MAX_BRIDGE_DEPTH) {
+    throw new RecursionLimitError(depth, MAX_BRIDGE_DEPTH);
+  }
+}
+
+// src/guards/check-binary.ts
+import which2 from "which";
+var cachedBinaryPath = null;
+function getCachedBinaryPath() {
+  return cachedBinaryPath;
+}
+async function checkBinary(binary = "codex") {
+  if (cachedBinaryPath !== null) {
+    return { found: true, path: cachedBinaryPath };
+  }
+  try {
+    const resolved = await which2(binary);
+    cachedBinaryPath = resolved;
+    return { found: true, path: resolved };
+  } catch {
+    throw new CliNotFoundError(binary);
+  }
+}
+
+// src/guards/check-auth.ts
+import { execFile } from "child_process";
+
+// src/runner/sandbox-args.ts
+function getSandboxConfigArgs() {
+  if (process.platform !== "win32") return [];
+  const raw = process.env[WINDOWS_SANDBOX_ENV]?.trim() || WINDOWS_SANDBOX_DEFAULT;
+  const mode = /^[a-z-]+$/.test(raw) ? raw : WINDOWS_SANDBOX_DEFAULT;
+  return ["-c", `windows.sandbox=${mode}`];
+}
+
+// src/guards/check-auth.ts
+var AUTH_CACHE_TTL_MS = 6e4;
+var authCachedAt = null;
+async function checkAuth() {
+  const now = Date.now();
+  if (authCachedAt !== null && now - authCachedAt < AUTH_CACHE_TTL_MS) {
+    return;
+  }
+  const binary = getCachedBinaryPath() ?? "codex";
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      binary,
+      ["exec", "--sandbox", "read-only", ...getSandboxConfigArgs(), "--skip-git-repo-check", "--ephemeral", "echo ok"],
+      { timeout: 3e4, shell: process.platform === "win32" },
+      (error, _stdout, stderr) => {
+        if (!error) {
+          authCachedAt = Date.now();
+          resolve();
+          return;
+        }
+        const lower = (stderr ?? error.message ?? "").toLowerCase();
+        if (error.code === "ENOENT" || error.code === "ENOENT") {
+          reject(new CliNotFoundError());
+          return;
+        }
+        if (error.killed) {
+          reject(new NetworkError("Auth check timed out \u2014 check your network connection"));
+          return;
+        }
+        if (["econnrefused", "econnreset", "etimedout", "network error", "fetch failed"].some((p) => lower.includes(p))) {
+          reject(new NetworkError("Network error during auth check"));
+          return;
+        }
+        reject(new AuthExpiredError());
+      }
+    );
+    child.stdin?.end();
+  });
+}
+
+// src/lock/lock-file.ts
+import fs8 from "fs";
+import path10 from "path";
+import os2 from "os";
+function getLockPath(cwd) {
+  return path10.join(cwd, LOCK_FILENAME);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isLockStale(data) {
+  const age = Date.now() - data.timestamp;
+  if (age > LOCK_STALE_MS) return true;
+  if (!isProcessAlive(data.pid)) return true;
+  return false;
+}
+function tryRemoveStaleLock(lockPath) {
+  try {
+    const raw = fs8.readFileSync(lockPath, "utf-8");
+    const data = JSON.parse(raw);
+    if (isLockStale(data)) {
+      fs8.unlinkSync(lockPath);
+      return true;
+    }
+    throw new LockConflictError(data.pid);
+  } catch (err) {
+    if (err instanceof LockConflictError) throw err;
+    try {
+      fs8.unlinkSync(lockPath);
+    } catch {
+    }
+    return true;
+  }
+}
+function acquireLock(cwd) {
+  const lockPath = getLockPath(cwd);
+  const lockData = {
+    pid: process.pid,
+    timestamp: Date.now(),
+    hostname: os2.hostname()
+  };
+  const content = JSON.stringify(lockData, null, 2);
+  try {
+    fs8.writeFileSync(lockPath, content, { flag: "wx" });
+  } catch (err) {
+    const fsErr = err;
+    if (fsErr.code === "EEXIST") {
+      tryRemoveStaleLock(lockPath);
+      try {
+        fs8.writeFileSync(lockPath, content, { flag: "wx" });
+      } catch (retryErr) {
+        const retryFsErr = retryErr;
+        if (retryFsErr.code === "EEXIST") {
+          throw new LockConflictError(0);
+        }
+        throw retryErr;
+      }
+    } else {
+      throw err;
+    }
+  }
+  const onExit = () => {
+    try {
+      fs8.unlinkSync(lockPath);
+    } catch {
+    }
+  };
+  process.on("exit", onExit);
+  process.on("SIGINT", onExit);
+  process.on("SIGTERM", onExit);
+  const release = () => {
+    process.removeListener("exit", onExit);
+    process.removeListener("SIGINT", onExit);
+    process.removeListener("SIGTERM", onExit);
+    try {
+      fs8.unlinkSync(lockPath);
+    } catch {
+    }
+  };
+  return { release };
+}
+
+// src/guards/check-lock.ts
+function checkLock(cwd) {
+  return acquireLock(cwd);
+}
+
+// src/guards/check-git.ts
+import { execFileSync } from "child_process";
+function checkGit(cwd) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd,
+      stdio: "pipe",
+      timeout: 5e3
+    });
+    return { isGitRepo: true };
+  } catch {
+    return { isGitRepo: false };
+  }
+}
+
+// src/guards/preflight.ts
+async function runPreflight(options) {
+  checkRecursion();
+  await checkBinary();
+  if (!options.skipAuth && process.platform !== "win32") {
+    await checkAuth();
+  }
+  let lockHandle = null;
+  if (!options.skipLock) {
+    lockHandle = checkLock(options.cwd);
+  }
+  if (options.requireGit) {
+    const { isGitRepo } = checkGit(options.cwd);
+    if (!isGitRepo) {
+      lockHandle?.release();
+      throw new NotGitRepoError(options.cwd);
+    }
+  }
+  return { lockHandle };
+}
+
+// src/runner/exec-runner.ts
+import { spawn } from "child_process";
+import { StringDecoder } from "string_decoder";
+
+// src/runner/timeout.ts
+function setupTimeout(child, timeoutMs) {
+  let timer = null;
+  let graceTimer = null;
+  const promise = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      if (isWindows()) {
+        child.kill();
+      } else {
+        child.kill("SIGTERM");
+        graceTimer = setTimeout(() => {
+          try {
+            if (!child.killed) {
+              child.kill("SIGKILL");
+            }
+          } catch {
+          }
+        }, KILL_GRACE_MS);
+      }
+      reject(new TimeoutError(timeoutMs));
+    }, timeoutMs);
+  });
+  const clear = () => {
+    if (timer) clearTimeout(timer);
+    if (graceTimer) clearTimeout(graceTimer);
+  };
+  return { clear, promise };
+}
+
+// src/util/truncate.ts
+function truncateResponse(text, maxChars = MAX_RESPONSE_CHARS) {
+  if (text.length <= maxChars) return text;
+  const omitted = text.length - maxChars;
+  return text.slice(0, maxChars) + `
+
+[Response truncated at ${maxChars} characters. ${omitted} characters omitted.]`;
+}
+
+// src/runner/output-parser.ts
+function parseCodexOutput(raw) {
+  if (!raw.trim()) {
+    throw new EmptyOutputError();
+  }
+  const lines = raw.split("\n").filter((line) => line.trim());
+  const messages = [];
+  const activity = [];
+  let resultContent = null;
+  let sessionId;
+  let usage = null;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.type === "thread.started" && typeof parsed.thread_id === "string") {
+        sessionId = parsed.thread_id;
+        continue;
+      }
+      if (parsed.type === "turn.completed" && parsed.usage) {
+        usage = {
+          input_tokens: parsed.usage.input_tokens ?? 0,
+          cached_input_tokens: parsed.usage.cached_input_tokens ?? 0,
+          output_tokens: parsed.usage.output_tokens ?? 0,
+          reasoning_output_tokens: parsed.usage.reasoning_output_tokens ?? 0
+        };
+        continue;
+      }
+      if (parsed.type === "result" && typeof parsed.content === "string") {
+        resultContent = parsed.content;
+        continue;
+      }
+      if (parsed.type === "message" && typeof parsed.content === "string") {
+        messages.push(parsed.content);
+        continue;
+      }
+      if (parsed.item?.type === "command_execution") {
+        const cmd = parsed.item;
+        const shortCmd = cmd.command?.length > 80 ? cmd.command.slice(0, 77) + "..." : cmd.command;
+        const statusIcon = cmd.status === "declined" ? "\u2718" : cmd.exit_code === 0 ? "\u2714" : cmd.exit_code !== null ? "\u2718" : "\u25B6";
+        const statusLabel = cmd.status === "declined" ? "blocked" : cmd.status === "in_progress" ? "running" : cmd.exit_code === 0 ? "ok" : `exit ${cmd.exit_code}`;
+        if (cmd.status !== "in_progress") {
+          activity.push({
+            type: "exec",
+            command: shortCmd,
+            icon: statusIcon,
+            status: statusLabel
+          });
+        }
+        continue;
+      }
+      if (parsed.item?.type === "agent_message" && typeof parsed.item.text === "string" && parsed.type !== "item.started" && parsed.type !== "item.updated") {
+        messages.push(parsed.item.text);
+        continue;
+      }
+      if (parsed.itemType === "agent_message" && typeof parsed.text === "string") {
+        messages.push(parsed.text);
+        continue;
+      }
+      if (parsed.item?.type === "file_read") {
+        activity.push({
+          type: "read",
+          path: parsed.item.path || "file",
+          icon: "\u25B6",
+          status: "read"
+        });
+        continue;
+      }
+      if (parsed.item?.type === "file_write" || parsed.item?.type === "file_edit") {
+        activity.push({
+          type: "write",
+          path: parsed.item.path || "file",
+          icon: "\u270E",
+          status: "write"
+        });
+        continue;
+      }
+      if (parsed.item?.type === "file_change") {
+        const changes = Array.isArray(parsed.item.changes) ? parsed.item.changes : null;
+        if (changes && changes.length > 0) {
+          for (const change of changes) {
+            activity.push({
+              type: "write",
+              path: change?.path || "file",
+              icon: "\u270E",
+              status: change?.kind || "write"
+            });
+          }
+        } else {
+          activity.push({
+            type: "write",
+            path: parsed.item.path || "file",
+            icon: "\u270E",
+            status: "write"
+          });
+        }
+        continue;
+      }
+    } catch {
+    }
+  }
+  let agentMessage;
+  if (resultContent !== null) {
+    agentMessage = resultContent;
+  } else if (messages.length > 0) {
+    agentMessage = messages.join("\n\n");
+  } else {
+    const substantiveLines = lines.filter(
+      (line) => !line.startsWith("OpenAI Codex") && !line.startsWith("---") && !line.startsWith("tokens used")
+    );
+    agentMessage = substantiveLines.join("\n").trim();
+  }
+  if (!agentMessage) {
+    throw new EmptyOutputError();
+  }
+  return {
+    content: truncateResponse(agentMessage),
+    activity,
+    usage,
+    raw,
+    sessionId
+  };
+}
+
+// src/util/text.ts
+function oneLine(text, max) {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? collapsed.slice(0, max - 1) + "\u2026" : collapsed;
+}
+function baseName(p) {
+  if (!p) return "file";
+  const parts = p.split(/[\\/]/).filter(Boolean);
+  return parts.length > 0 ? parts[parts.length - 1] : p;
+}
+
+// src/runner/progress.ts
+function formatProgressMessage(evt) {
+  if (!evt || typeof evt !== "object") return null;
+  const item = evt.item;
+  if (item?.type === "command_execution") {
+    const cmd = oneLine(String(item.command ?? ""), 60);
+    if (item.status === "in_progress") return `running: ${cmd}`;
+    if (item.status === "declined") return `blocked: ${cmd}`;
+    if (item.exit_code === 0) return `ran: ${cmd}`;
+    return `failed (exit ${String(item.exit_code)}): ${cmd}`;
+  }
+  if (item?.type === "file_read") return `reading ${baseName(String(item.path ?? "file"))}`;
+  if (item?.type === "file_write" || item?.type === "file_edit") {
+    return `editing ${baseName(String(item.path ?? "file"))}`;
+  }
+  if (item?.type === "file_change") {
+    const changes = Array.isArray(item.changes) ? item.changes : null;
+    if (changes && changes.length > 0) {
+      return changes.length === 1 ? `editing ${baseName(String(changes[0]?.path ?? "file"))}` : `editing ${changes.length} files`;
+    }
+    return `editing ${baseName(String(item.path ?? "file"))}`;
+  }
+  if (item?.type === "reasoning" || evt.type === "turn.started") return "thinking\u2026";
+  if (item?.type === "agent_message" && typeof item.text === "string" && evt.type !== "item.started" && evt.type !== "item.updated") {
+    return "writing response\u2026";
+  }
+  return null;
+}
+
+// src/util/live-logger.ts
+import fs9 from "fs";
+import os3 from "os";
+import path11 from "path";
+import { createHash } from "crypto";
+function resolveLogPath(cwd) {
+  const override = process.env[LOG_ENV];
+  if (override && override.trim()) return path11.resolve(override.trim());
+  const base = path11.basename(cwd).replace(/[^a-zA-Z0-9._-]/g, "_") || "run";
+  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, 8);
+  return path11.join(os3.tmpdir(), "skill-codex", `${base}-${hash}.log`);
+}
+function formatLogLines(evt) {
+  if (!evt || typeof evt !== "object") return [];
+  const item = evt.item;
+  if (item?.type === "command_execution") {
+    if (item.status === "in_progress") return [`  $ ${oneLine(String(item.command ?? ""), 120)}`];
+    if (item.status === "declined") return ["    \u2718 blocked"];
+    if (item.exit_code === 0) return ["    \u2714 ok"];
+    return [`    \u2718 exit ${String(item.exit_code)}`];
+  }
+  if (item?.type === "file_read") return [`  read   ${String(item.path ?? "file")}`];
+  if (item?.type === "file_write" || item?.type === "file_edit") {
+    return [`  write  ${String(item.path ?? "file")}`];
+  }
+  if (item?.type === "file_change") {
+    const changes = Array.isArray(item.changes) ? item.changes : null;
+    if (changes && changes.length > 0) {
+      return changes.map(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (change) => `  write  ${String(change?.path ?? "file")} (${String(change?.kind ?? "write")})`
+      );
+    }
+    return [`  write  ${String(item.path ?? "file")}`];
+  }
+  if (item?.type === "agent_message" && typeof item.text === "string" && evt.type !== "item.started" && evt.type !== "item.updated") {
+    return [`  msg    ${oneLine(item.text, 400)}`];
+  }
+  if (evt.type === "message" && typeof evt.content === "string") {
+    return [`  msg    ${oneLine(evt.content, 400)}`];
+  }
+  if (evt.type === "turn.completed" && evt.usage) {
+    const u = evt.usage;
+    const reasoning = u.reasoning_output_tokens ?? 0;
+    return [
+      `  tokens: ${u.input_tokens ?? 0} in \u2192 ${u.output_tokens ?? 0} out${reasoning > 0 ? ` (+${reasoning} reasoning)` : ""}`
+    ];
+  }
+  return [];
+}
+function createLiveLogger(opts) {
+  const logPath = resolveLogPath(opts.cwd);
+  let stream = null;
+  try {
+    fs9.mkdirSync(path11.dirname(logPath), { recursive: true });
+    stream = fs9.createWriteStream(logPath, { flags: "a" });
+  } catch {
+    stream = null;
+  }
+  const line = (text) => {
+    try {
+      stream?.write(text + "\n");
+    } catch {
+    }
+  };
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  line("");
+  line("=".repeat(60));
+  line(`> codex ${opts.mode}  ${startedAt}`);
+  line(`  cwd:  ${opts.cwd}`);
+  line(`  task: ${oneLine(opts.prompt, 200)}`);
+  line("-".repeat(60));
+  const handleEvent = (raw) => {
+    const trimmed = raw.trim();
+    if (!trimmed) return;
+    let evt;
+    try {
+      evt = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+    for (const l of formatLogLines(evt)) line(l);
+  };
+  let buffer = "";
+  return {
+    path: logPath,
+    write(fragment) {
+      buffer += fragment;
+      let idx;
+      while ((idx = buffer.indexOf("\n")) >= 0) {
+        const lineStr = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 1);
+        handleEvent(lineStr);
+      }
+    },
+    finish(summary) {
+      if (buffer.trim()) {
+        handleEvent(buffer);
+        buffer = "";
+      }
+      line("-".repeat(60));
+      line(`# done  ${(/* @__PURE__ */ new Date()).toISOString()}  ${summary}`);
+      try {
+        stream?.end();
+      } catch {
+      }
+    }
+  };
+}
+
+// src/runner/exec-runner.ts
+function getTimeout(override) {
+  if (override !== void 0) return override;
+  const envVal = process.env[TIMEOUT_ENV];
+  if (envVal) {
+    const parsed = parseInt(envVal, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+function classifyError(exitCode, stderr) {
+  const lower = stderr.toLowerCase();
+  if (lower.includes("unauthorized") || lower.includes("401") || lower.includes("api key")) {
+    return new AuthExpiredError();
+  }
+  if (lower.includes("rate limit") || lower.includes("429") || lower.includes("too many requests")) {
+    return new RateLimitError();
+  }
+  if (["500", "502", "503", "504", "internal server error", "bad gateway", "service unavailable"].some((p) => lower.includes(p))) {
+    return new ServerError(stderr.slice(0, 200));
+  }
+  if (["econnreset", "econnrefused", "etimedout", "network error", "fetch failed", "socket hang up"].some((p) => lower.includes(p))) {
+    return new NetworkError(stderr.slice(0, 200));
+  }
+  return new BridgeError(
+    `Codex exited with code ${exitCode}: ${stderr.slice(0, 300)}`,
+    "EXEC_FAILED",
+    false
+  );
+}
+async function execCodex(params) {
+  const codexPath = getCachedBinaryPath();
+  if (codexPath === null) {
+    throw new CliNotFoundError();
+  }
+  return new Promise((resolve, reject) => {
+    const timeoutMs = getTimeout(params.timeoutMs);
+    let args2;
+    let sendStdinPrompt;
+    if (params.review) {
+      args2 = ["exec", "review", "--json", "--skip-git-repo-check"];
+      if (params.reviewBase) {
+        args2.push("--base", params.reviewBase);
+        sendStdinPrompt = false;
+      } else if (params.reviewCommit) {
+        args2.push("--commit", params.reviewCommit);
+        sendStdinPrompt = false;
+      } else if (params.prompt?.trim()) {
+        sendStdinPrompt = true;
+      } else {
+        args2.push("--uncommitted");
+        sendStdinPrompt = false;
+      }
+    } else if (params.sessionId) {
+      args2 = ["exec", "resume", params.sessionId, "--json", "--skip-git-repo-check"];
+      sendStdinPrompt = true;
+    } else {
+      const sandbox = params.sandbox ?? (params.mode === "full-auto" ? "workspace-write" : "read-only");
+      args2 = ["exec", "--json", "--skip-git-repo-check", "--sandbox", sandbox];
+      sendStdinPrompt = true;
+    }
+    if (params.model) {
+      args2.push("-m", params.model);
+    }
+    if (params.reasoningEffort) {
+      args2.push("-c", `model_reasoning_effort=${params.reasoningEffort}`);
+    }
+    args2.push(...getSandboxConfigArgs());
+    const stdinPrompt = params.prompt ?? "";
+    if (sendStdinPrompt) {
+      args2.push("-");
+    }
+    const env = {
+      ...process.env,
+      [BRIDGE_DEPTH_ENV]: String(getNextDepth())
+    };
+    const child = spawn(codexPath, args2, {
+      cwd: params.cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: process.platform === "win32",
+      windowsHide: true
+    });
+    const { clear: clearTimeout_, promise: timeoutPromise } = setupTimeout(child, timeoutMs);
+    const startedAt = Date.now();
+    const logger = createLiveLogger({
+      cwd: params.cwd,
+      mode: params.mode,
+      prompt: params.prompt
+    });
+    process.stderr.write(`[skill-codex] live log: ${logger.path}
+`);
+    let heartbeat = null;
+    if (params.onProgress) {
+      heartbeat = setInterval(() => {
+        const secs = Math.round((Date.now() - startedAt) / 1e3);
+        params.onProgress?.(`Codex working\u2026 ${secs}s elapsed`);
+      }, HEARTBEAT_INTERVAL_MS);
+      if (typeof heartbeat.unref === "function") heartbeat.unref();
+    }
+    const stopHeartbeat = () => {
+      if (heartbeat) {
+        clearInterval(heartbeat);
+        heartbeat = null;
+      }
+    };
+    const decoder = new StringDecoder("utf8");
+    let progressBuf = "";
+    const consumeForProgress = (text) => {
+      if (!params.onProgress) return;
+      progressBuf += text;
+      let idx;
+      while ((idx = progressBuf.indexOf("\n")) >= 0) {
+        const lineStr = progressBuf.slice(0, idx).trim();
+        progressBuf = progressBuf.slice(idx + 1);
+        if (!lineStr) continue;
+        try {
+          const msg = formatProgressMessage(JSON.parse(lineStr));
+          if (msg) params.onProgress(msg);
+        } catch {
+        }
+      }
+    };
+    let logFinished = false;
+    const finishLog = (summary) => {
+      stopHeartbeat();
+      if (logFinished) return;
+      logFinished = true;
+      try {
+        logger.write(decoder.end());
+        logger.finish(summary);
+      } catch {
+      }
+    };
+    const stdoutChunks = [];
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdoutChunks.push(chunk);
+      const text = decoder.write(chunk);
+      try {
+        logger.write(text);
+      } catch {
+      }
+      consumeForProgress(text);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    if (sendStdinPrompt) {
+      child.stdin?.write(stdinPrompt);
+    }
+    child.stdin?.end();
+    const onClose = (exitCode) => {
+      clearTimeout_();
+      finishLog(exitCode === 0 || exitCode === null ? "ok" : `exit ${exitCode}`);
+      const stdout = Buffer.concat(stdoutChunks).toString();
+      if (exitCode === 0 || exitCode === null) {
+        try {
+          const result = parseCodexOutput(stdout);
+          resolve({ ...result, logPath: logger.path, durationMs: Date.now() - startedAt });
+        } catch (err) {
+          reject(err);
+        }
+        return;
+      }
+      reject(classifyError(exitCode, stderr));
+    };
+    child.on("close", onClose);
+    child.on("error", (err) => {
+      clearTimeout_();
+      finishLog("spawn error");
+      if (err.code === "ENOENT") {
+        reject(new CliNotFoundError());
+      } else {
+        reject(new BridgeError(`Failed to spawn codex: ${err.message}`, "SPAWN_ERROR", false));
+      }
+    });
+    timeoutPromise.catch((err) => {
+      finishLog("timeout");
+      reject(err);
+    });
+  });
+}
+
+// src/runner/retry.ts
+function getMaxRetries(override) {
+  if (override !== void 0) return override;
+  const envVal = process.env[MAX_RETRIES_ENV];
+  if (envVal) {
+    const parsed = parseInt(envVal, 10);
+    if (!isNaN(parsed) && parsed >= 0) return parsed;
+  }
+  return MAX_RETRIES;
+}
+function getDelay(attempt) {
+  const base = RETRY_DELAYS_MS[attempt] ?? RETRY_CAP_MS;
+  const capped = Math.min(base, RETRY_CAP_MS);
+  const jitter = 0.5 + Math.random();
+  return Math.round(capped * jitter);
+}
+function defaultShouldRetry(err) {
+  return err instanceof BridgeError && err.retryable;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, options = {}) {
+  const maxRetries = getMaxRetries(options.maxRetries);
+  const shouldRetry = options.shouldRetry ?? defaultShouldRetry;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const isRetryable = err instanceof Error && shouldRetry(err);
+      if (attempt < maxRetries && isRetryable) {
+        const delay = getDelay(attempt);
+        const errorName = err instanceof Error ? err.constructor.name : "UnknownError";
+        process.stderr.write(
+          `[skill-codex] ${errorName} (attempt ${attempt + 1}/${maxRetries}), retrying in ${delay}ms...
+`
+        );
+        await sleep(delay);
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+// src/tools/codex-exec.ts
+var TOOL_NAME = "codex_exec";
+var TOOL_DESCRIPTION = "Execute a task using OpenAI Codex CLI. Use for code review, implementation tasks, or getting a second opinion. Codex output is a SUGGESTION \u2014 evaluate it critically before applying.";
+var inputSchema = z.object({
+  prompt: z.string().optional().describe("The task description for Codex"),
+  mode: z.enum(["exec", "full-auto"]).default("exec").describe("exec = read-only with confirmation, full-auto = can write files"),
+  sandbox: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional().describe(
+    "Explicit Codex sandbox policy; overrides mode. read-only = no writes, workspace-write = write within cwd, danger-full-access = unrestricted (use with care)."
+  ),
+  sessionId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/, "sessionId must be a Codex thread id (letters, digits, '-', '_')").optional().describe(
+    "Resume a prior Codex session by its thread id (returned in a previous response) so Codex retains context across calls."
+  ),
+  model: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/).optional().describe(
+    "Codex model to use (e.g. gpt-5.5, gpt-5.4, gpt-5.4-mini). Omit to use Codex's configured default."
+  ),
+  reasoningEffort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional().describe("How much reasoning effort Codex spends. Omit for the model's default."),
+  review: z.boolean().optional().describe(
+    "Run Codex's native diff-scoped review (`codex exec review`) instead of a freeform prompt. The prompt becomes optional custom review instructions."
+  ),
+  reviewBase: z.string().regex(/^[A-Za-z0-9._\/-]{1,128}$/).optional().describe("With review: diff against this base branch (default: uncommitted changes)."),
+  reviewCommit: z.string().regex(/^[0-9a-fA-F]{4,64}$/).optional().describe("With review: review the changes introduced by this commit SHA."),
+  cwd: z.string().optional().describe("Working directory (defaults to server cwd)"),
+  timeoutMs: z.number().optional().describe("Override default timeout in milliseconds"),
+  requireGit: z.boolean().default(false).describe("Fail if not inside a git repository")
+});
+var TOOL_INPUT_JSON_SCHEMA = {
+  type: "object",
+  properties: {
+    prompt: { type: "string", description: "The task description for Codex" },
+    mode: {
+      type: "string",
+      enum: ["exec", "full-auto"],
+      default: "exec",
+      description: "exec = read-only, full-auto = can write files"
+    },
+    sandbox: {
+      type: "string",
+      enum: ["read-only", "workspace-write", "danger-full-access"],
+      description: "Explicit Codex sandbox policy; overrides mode. read-only = no writes, workspace-write = write within cwd, danger-full-access = unrestricted (use with care)."
+    },
+    sessionId: {
+      type: "string",
+      pattern: "^[A-Za-z0-9_-]{1,128}$",
+      description: "Resume a prior Codex session by its thread id (returned in a previous response) so Codex retains context across calls."
+    },
+    model: {
+      type: "string",
+      pattern: "^[A-Za-z0-9._-]{1,64}$",
+      description: "Codex model to use (e.g. gpt-5.5, gpt-5.4, gpt-5.4-mini). Omit to use Codex's configured default."
+    },
+    reasoningEffort: {
+      type: "string",
+      enum: ["minimal", "low", "medium", "high", "xhigh"],
+      description: "How much reasoning effort Codex spends. Omit for the model's default."
+    },
+    review: {
+      type: "boolean",
+      description: "Run Codex's native diff-scoped review (`codex exec review`) instead of a freeform prompt. The prompt becomes optional custom review instructions."
+    },
+    reviewBase: {
+      type: "string",
+      pattern: "^[A-Za-z0-9._\\/-]{1,128}$",
+      description: "With review: diff against this base branch (default: uncommitted changes)."
+    },
+    reviewCommit: {
+      type: "string",
+      pattern: "^[0-9a-fA-F]{4,64}$",
+      description: "With review: review the changes introduced by this commit SHA."
+    },
+    cwd: { type: "string", description: "Working directory (defaults to server cwd)" },
+    timeoutMs: { type: "number", description: "Override default timeout in milliseconds" },
+    requireGit: {
+      type: "boolean",
+      default: false,
+      description: "Fail if not inside a git repository"
+    }
+  },
+  required: []
+};
+function formatError(err) {
+  if (err instanceof BridgeError) {
+    return `[skill-codex error: ${err.code}] ${err.message}`;
+  }
+  if (err instanceof Error) {
+    return `[skill-codex error] ${err.message}`;
+  }
+  return `[skill-codex error] Unknown error: ${String(err)}`;
+}
+function formatRichResponse(result, input, cwd) {
+  const lines = [];
+  const sandboxLabel = input.sandbox ?? (input.mode === "full-auto" ? "workspace-write" : "read-only");
+  const label = input.review ? "review" : input.sessionId ? "resumed" : sandboxLabel;
+  const metaParts = [label];
+  if (input.model) {
+    metaParts.push(input.model);
+  }
+  if (input.reasoningEffort) {
+    metaParts.push(`effort:${input.reasoningEffort}`);
+  }
+  metaParts.push(cwd);
+  if (typeof result.durationMs === "number") {
+    metaParts.push(`${(result.durationMs / 1e3).toFixed(1)}s`);
+  }
+  if (result.usage) {
+    const {
+      input_tokens: inp,
+      output_tokens: out,
+      cached_input_tokens: cached,
+      reasoning_output_tokens: reasoning
+    } = result.usage;
+    metaParts.push(
+      `${inp} tok in${cached > 0 ? ` (${cached} cached)` : ""} \u2192 ${out} out${reasoning > 0 ? ` (+${reasoning} reasoning)` : ""}`
+    );
+  }
+  lines.push(`[${metaParts.join(" \u2502 ")}]`);
+  if (result.sessionId) {
+    lines.push(`  session: ${result.sessionId} (pass as sessionId to continue this conversation)`);
+  }
+  if (result.logPath) {
+    lines.push(`  live log: ${result.logPath}`);
+  }
+  if (result.activity.length > 0) {
+    for (const a of result.activity) {
+      if (a.type === "exec") {
+        lines.push(`  ${a.icon} exec: ${a.command}  (${a.status})`);
+      } else if (a.type === "read") {
+        lines.push(`  \u25B6 read: ${a.path}`);
+      } else if (a.type === "write") {
+        lines.push(`  \u270E write: ${a.path}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push(result.content);
+  return lines.join("\n");
+}
+async function handleCodexExec(input, serverCwd, onProgress) {
+  const rawCwd = input.cwd ?? serverCwd;
+  const cwd = path12.resolve(rawCwd);
+  if (!fs10.existsSync(cwd) || !fs10.statSync(cwd).isDirectory()) {
+    return {
+      content: [{ type: "text", text: `[skill-codex error: INVALID_CWD] cwd is not an existing directory: ${cwd}` }],
+      isError: true
+    };
+  }
+  const optError = (msg) => ({
+    content: [{ type: "text", text: `[skill-codex error: INVALID_OPTIONS] ${msg}` }],
+    isError: true
+  });
+  if (input.review && input.sessionId) return optError("review and sessionId are mutually exclusive");
+  if (input.reviewBase && input.reviewCommit) return optError("reviewBase and reviewCommit are mutually exclusive");
+  if ((input.reviewBase ?? input.reviewCommit) && !input.review) {
+    return optError("reviewBase/reviewCommit require review: true");
+  }
+  if (input.review && (input.reviewBase ?? input.reviewCommit) && input.prompt?.trim()) {
+    return optError(
+      "a review target (reviewBase/reviewCommit) can't be combined with a prompt \u2014 Codex review takes a target OR instructions, not both"
+    );
+  }
+  if (!input.review && !input.prompt?.trim()) {
+    return {
+      content: [{ type: "text", text: "[skill-codex error: MISSING_PROMPT] prompt is required unless review is set" }],
+      isError: true
+    };
+  }
+  let lockRelease = null;
+  try {
+    const { lockHandle } = await runPreflight({
+      cwd,
+      requireGit: input.requireGit
+    });
+    lockRelease = lockHandle?.release ?? null;
+    const result = await withRetry(
+      () => execCodex({
+        prompt: input.prompt ?? "",
+        cwd,
+        mode: input.mode,
+        sandbox: input.sandbox,
+        sessionId: input.sessionId,
+        model: input.model,
+        reasoningEffort: input.reasoningEffort,
+        review: input.review,
+        reviewBase: input.reviewBase,
+        reviewCommit: input.reviewCommit,
+        timeoutMs: input.timeoutMs,
+        onProgress
+      })
+    );
+    const formatted = formatRichResponse(result, input, cwd);
+    return {
+      content: [{ type: "text", text: formatted }]
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: formatError(err) }],
+      isError: true
+    };
+  } finally {
+    lockRelease?.();
+  }
+}
+
+// src/server.ts
+function createServer(cwd) {
+  const server = new Server(
+    { name: "skill-codex", version: "0.8.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: TOOL_NAME,
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_JSON_SCHEMA
+      }
+    ]
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    if (request.params.name !== TOOL_NAME) {
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+        isError: true
+      };
+    }
+    const parsed = inputSchema.safeParse(request.params.arguments);
+    if (!parsed.success) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Invalid input: ${parsed.error.issues.map((i) => i.message).join(", ")}`
+          }
+        ],
+        isError: true
+      };
+    }
+    const progressToken = request.params._meta?.progressToken;
+    let progressCounter = 0;
+    const onProgress = progressToken === void 0 ? void 0 : (message) => {
+      progressCounter += 1;
+      void extra.sendNotification({
+        method: "notifications/progress",
+        params: { progressToken, progress: progressCounter, message }
+      }).catch(() => {
+      });
+    };
+    return handleCodexExec(parsed.data, cwd, onProgress);
+  });
+  return server;
+}
+async function startServer() {
+  const cwd = process.cwd();
+  const server = createServer(cwd);
+  const transport = new StdioServerTransport();
+  process.stderr.write("[skill-codex] MCP server starting...\n");
+  await server.connect(transport);
+  process.stderr.write("[skill-codex] MCP server connected via stdio\n");
+  process.on("uncaughtException", (err) => {
+    process.stderr.write(`[skill-codex] Uncaught exception: ${err.message}
+`);
+  });
+  process.on("unhandledRejection", (reason) => {
+    process.stderr.write(`[skill-codex] Unhandled rejection: ${String(reason)}
+`);
+  });
+}
+
 // bin/skill-codex.ts
 var args = process.argv.slice(2);
 var command = args[0];
 function getVersion() {
-  const __dirname = path10.dirname(fileURLToPath(import.meta.url));
-  const pkgPath = path10.resolve(__dirname, "..", "package.json");
+  const __dirname = path13.dirname(fileURLToPath(import.meta.url));
+  const pkgPath = path13.resolve(__dirname, "..", "package.json");
   try {
-    const pkg = JSON.parse(fs8.readFileSync(pkgPath, "utf-8"));
+    const pkg = JSON.parse(fs11.readFileSync(pkgPath, "utf-8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -535,6 +1701,11 @@ Usage:
       await runUninstall();
       break;
     }
+    case "mcp":
+    case "serve": {
+      await startServer();
+      break;
+    }
     default: {
       const version = getVersion();
       process.stdout.write(`skill-codex v${version}