skill-codex 0.2.0

package/dist/index.js

@@ -0,0 +1,722 @@
+// 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 fs2 from "fs";
+import path3 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 = 6e5;
+var TIMEOUT_ENV = "SKILL_CODEX_TIMEOUT_MS";
+var KILL_GRACE_MS = 5e3;
+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";
+
+// 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 which 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 which(binary);
+    cachedBinaryPath = resolved;
+    return { found: true, path: resolved };
+  } catch {
+    throw new CliNotFoundError(binary);
+  }
+}
+
+// src/guards/check-auth.ts
+import { execFile } from "child_process";
+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", "--skip-git-repo-check", "--ephemeral", "echo ok"],
+      { timeout: 15e3 },
+      (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 fs from "fs";
+import path from "path";
+import os from "os";
+function getLockPath(cwd) {
+  return path.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 = fs.readFileSync(lockPath, "utf-8");
+    const data = JSON.parse(raw);
+    if (isLockStale(data)) {
+      fs.unlinkSync(lockPath);
+      return true;
+    }
+    throw new LockConflictError(data.pid);
+  } catch (err) {
+    if (err instanceof LockConflictError) throw err;
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+    }
+    return true;
+  }
+}
+function acquireLock(cwd) {
+  const lockPath = getLockPath(cwd);
+  const lockData = {
+    pid: process.pid,
+    timestamp: Date.now(),
+    hostname: os.hostname()
+  };
+  const content = JSON.stringify(lockData, null, 2);
+  try {
+    fs.writeFileSync(lockPath, content, { flag: "wx" });
+  } catch (err) {
+    const fsErr = err;
+    if (fsErr.code === "EEXIST") {
+      tryRemoveStaleLock(lockPath);
+      try {
+        fs.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 {
+      fs.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 {
+      fs.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) {
+    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";
+
+// src/util/platform.ts
+import os2 from "os";
+import path2 from "path";
+function getPlatform() {
+  const p = os2.platform();
+  if (p === "win32" || p === "darwin" || p === "linux") return p;
+  return "linux";
+}
+function isWindows() {
+  return getPlatform() === "win32";
+}
+
+// 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 = [];
+  let resultContent = null;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      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 === "agent_message" && typeof parsed.item.text === "string") {
+        messages.push(parsed.item.text);
+        continue;
+      }
+      if (parsed.itemType === "agent_message" && typeof parsed.text === "string") {
+        messages.push(parsed.text);
+        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),
+    raw
+  };
+}
+
+// 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);
+    const args = ["exec", "--json", "--skip-git-repo-check"];
+    if (params.mode === "full-auto") {
+      args.push("--full-auto");
+    } else {
+      args.push("--sandbox", "read-only");
+    }
+    const stdinPrompt = params.prompt;
+    args.push("-");
+    const env = {
+      ...process.env,
+      [BRIDGE_DEPTH_ENV]: String(getNextDepth())
+    };
+    const child = spawn(codexPath, args, {
+      cwd: params.cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: false,
+      windowsHide: true
+    });
+    const { clear: clearTimeout_, promise: timeoutPromise } = setupTimeout(child, timeoutMs);
+    const stdoutChunks = [];
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdoutChunks.push(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.stdin?.write(stdinPrompt);
+    child.stdin?.end();
+    const onClose = (exitCode) => {
+      clearTimeout_();
+      const stdout = Buffer.concat(stdoutChunks).toString();
+      if (exitCode === 0 || exitCode === null) {
+        try {
+          const result = parseCodexOutput(stdout);
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+        return;
+      }
+      reject(classifyError(exitCode, stderr));
+    };
+    child.on("close", onClose);
+    child.on("error", (err) => {
+      clearTimeout_();
+      if (err.code === "ENOENT") {
+        reject(new CliNotFoundError());
+      } else {
+        reject(new BridgeError(`Failed to spawn codex: ${err.message}`, "SPAWN_ERROR", false));
+      }
+    });
+    timeoutPromise.catch((err) => {
+      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().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"),
+  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")
+});
+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)}`;
+}
+async function handleCodexExec(input, serverCwd) {
+  const rawCwd = input.cwd ?? serverCwd;
+  const cwd = path3.resolve(rawCwd);
+  if (!fs2.existsSync(cwd) || !fs2.statSync(cwd).isDirectory()) {
+    return {
+      content: [{ type: "text", text: `[skill-codex error: INVALID_CWD] cwd is not an existing directory: ${cwd}` }],
+      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,
+        timeoutMs: input.timeoutMs
+      })
+    );
+    return {
+      content: [{ type: "text", text: result.content }]
+    };
+  } 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.2.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: TOOL_NAME,
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+          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"
+            },
+            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: ["prompt"]
+        }
+      }
+    ]
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    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
+      };
+    }
+    return handleCodexExec(parsed.data, cwd);
+  });
+  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)}
+`);
+  });
+}
+
+// src/index.ts
+startServer().catch((err) => {
+  process.stderr.write(`[skill-codex] Fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map