codex-octopus 1.0.0

package/src/index.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * Codex Octopus — one brain, many arms.
+ *
+ * Wraps the OpenAI Codex SDK as MCP servers, letting you spawn multiple
+ * specialized Codex agents — each with its own model, sandbox, effort,
+ * and personality.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import { envStr, envBool, sanitizeToolName } from "./lib.js";
+import { buildBaseConfig } from "./config.js";
+import { registerQueryTools } from "./tools/query.js";
+import { registerFactoryTool } from "./tools/factory.js";
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require("../package.json");
+
+// ── Configuration ──────────────────────────────────────────────────
+
+const BASE_CONFIG = buildBaseConfig();
+const API_KEY = envStr("CODEX_API_KEY");
+
+const TOOL_NAME = sanitizeToolName(envStr("CODEX_TOOL_NAME") || "codex");
+const REPLY_TOOL_NAME = `${TOOL_NAME}_reply`;
+const SERVER_NAME = envStr("CODEX_SERVER_NAME") || "codex-octopus";
+const FACTORY_ONLY = envBool("CODEX_FACTORY_ONLY", false);
+
+const DEFAULT_DESCRIPTION = [
+  "Send a task to an autonomous Codex agent.",
+  "It reads/writes files, runs shell commands, searches codebases,",
+  "and handles complex software engineering tasks end-to-end.",
+  `Returns the result text plus a thread_id for follow-ups via ${REPLY_TOOL_NAME}.`,
+].join(" ");
+
+const TOOL_DESCRIPTION = envStr("CODEX_DESCRIPTION") || DEFAULT_DESCRIPTION;
+
+// ── Server ─────────────────────────────────────────────────────────
+
+const server = new McpServer({ name: SERVER_NAME, version: PKG_VERSION });
+
+if (!FACTORY_ONLY) {
+  registerQueryTools(server, BASE_CONFIG, TOOL_NAME, TOOL_DESCRIPTION, API_KEY);
+}
+
+if (FACTORY_ONLY) {
+  registerFactoryTool(server);
+}
+
+// ── Start ──────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  const toolList = FACTORY_ONLY
+    ? ["create_codex_mcp"]
+    : BASE_CONFIG.persistSession !== false
+      ? [TOOL_NAME, REPLY_TOOL_NAME]
+      : [TOOL_NAME];
+  console.error(`${SERVER_NAME}: running on stdio (tools: ${toolList.join(", ")})`);
+}
+
+main().catch((error) => {
+  console.error(`${SERVER_NAME}: fatal:`, error);
+  process.exit(1);
+});

package/src/lib.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect } from "vitest";
+import {
+  envStr,
+  envList,
+  envNum,
+  envBool,
+  sanitizeToolName,
+  MAX_TOOL_NAME_LEN,
+  isDescendantPath,
+  validateSandboxMode,
+  narrowSandboxMode,
+  VALID_SANDBOX_MODES,
+  validateApprovalPolicy,
+  narrowApprovalPolicy,
+  VALID_APPROVAL_POLICIES,
+  validateEffort,
+  VALID_EFFORTS,
+  deriveServerName,
+  deriveToolName,
+  serializeArrayEnv,
+  formatErrorMessage,
+} from "./lib.js";
+
+// ── envStr ────────────────────────────────────────────────────────
+
+describe("envStr", () => {
+  it("returns the value when set", () => {
+    expect(envStr("FOO", { FOO: "bar" })).toBe("bar");
+  });
+
+  it("returns undefined for missing keys", () => {
+    expect(envStr("MISSING", {})).toBeUndefined();
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(envStr("EMPTY", { EMPTY: "" })).toBeUndefined();
+  });
+});
+
+// ── envList ───────────────────────────────────────────────────────
+
+describe("envList", () => {
+  it("splits comma-separated values", () => {
+    expect(envList("X", { X: "a,b,c" })).toEqual(["a", "b", "c"]);
+  });
+
+  it("trims whitespace", () => {
+    expect(envList("X", { X: " a , b " })).toEqual(["a", "b"]);
+  });
+
+  it("parses JSON arrays", () => {
+    expect(envList("X", { X: '["a,b","c"]' })).toEqual(["a,b", "c"]);
+  });
+
+  it("returns undefined for missing keys", () => {
+    expect(envList("MISSING", {})).toBeUndefined();
+  });
+
+  it("falls back to comma-split on bad JSON", () => {
+    expect(envList("X", { X: "[bad" })).toEqual(["[bad"]);
+  });
+
+  it("filters empty strings", () => {
+    expect(envList("X", { X: "a,,b," })).toEqual(["a", "b"]);
+  });
+});
+
+// ── envNum ────────────────────────────────────────────────────────
+
+describe("envNum", () => {
+  it("parses valid numbers", () => {
+    expect(envNum("X", { X: "42" })).toBe(42);
+    expect(envNum("X", { X: "3.14" })).toBeCloseTo(3.14);
+  });
+
+  it("returns undefined for missing keys", () => {
+    expect(envNum("MISSING", {})).toBeUndefined();
+  });
+
+  it("returns undefined for NaN", () => {
+    expect(envNum("X", { X: "abc" })).toBeUndefined();
+  });
+});
+
+// ── envBool ───────────────────────────────────────────────────────
+
+describe("envBool", () => {
+  it("returns true for 'true' and '1'", () => {
+    expect(envBool("X", false, { X: "true" })).toBe(true);
+    expect(envBool("X", false, { X: "1" })).toBe(true);
+  });
+
+  it("returns false for other values", () => {
+    expect(envBool("X", true, { X: "false" })).toBe(false);
+    expect(envBool("X", true, { X: "0" })).toBe(false);
+  });
+
+  it("returns fallback when missing", () => {
+    expect(envBool("MISSING", true, {})).toBe(true);
+    expect(envBool("MISSING", false, {})).toBe(false);
+  });
+});
+
+// ── sanitizeToolName ──────────────────────────────────────────────
+
+describe("sanitizeToolName", () => {
+  it("passes through valid names", () => {
+    expect(sanitizeToolName("my_tool")).toBe("my_tool");
+  });
+
+  it("replaces invalid characters with underscore", () => {
+    expect(sanitizeToolName("my-tool.v2")).toBe("my_tool_v2");
+  });
+
+  it("truncates to MAX_TOOL_NAME_LEN", () => {
+    const long = "a".repeat(100);
+    expect(sanitizeToolName(long).length).toBe(MAX_TOOL_NAME_LEN);
+  });
+
+  it("falls back to 'codex' for empty result", () => {
+    expect(sanitizeToolName("")).toBe("codex");
+  });
+});
+
+// ── isDescendantPath ──────────────────────────────────────────────
+
+describe("isDescendantPath", () => {
+  it("accepts subdirectories", () => {
+    expect(isDescendantPath("subdir", "/srv/app")).toBe(true);
+    expect(isDescendantPath("a/b/c", "/srv/app")).toBe(true);
+  });
+
+  it("accepts same directory", () => {
+    expect(isDescendantPath(".", "/srv/app")).toBe(true);
+    expect(isDescendantPath("/srv/app", "/srv/app")).toBe(true);
+  });
+
+  it("rejects parent traversal", () => {
+    expect(isDescendantPath("..", "/srv/app")).toBe(false);
+    expect(isDescendantPath("../other", "/srv/app")).toBe(false);
+  });
+
+  it("rejects sibling paths", () => {
+    expect(isDescendantPath("/srv/other", "/srv/app")).toBe(false);
+  });
+
+  it("rejects prefix attacks", () => {
+    expect(isDescendantPath("/srv/app-escape", "/srv/app")).toBe(false);
+  });
+});
+
+// ── validateSandboxMode ───────────────────────────────────────────
+
+describe("validateSandboxMode", () => {
+  it("passes valid modes through", () => {
+    for (const mode of VALID_SANDBOX_MODES) {
+      expect(validateSandboxMode(mode)).toBe(mode);
+    }
+  });
+
+  it("falls back to read-only for invalid modes", () => {
+    expect(validateSandboxMode("garbage")).toBe("read-only");
+    expect(validateSandboxMode("")).toBe("read-only");
+  });
+});
+
+// ── narrowSandboxMode ─────────────────────────────────────────────
+
+describe("narrowSandboxMode", () => {
+  it("allows tightening from danger-full-access", () => {
+    expect(narrowSandboxMode("danger-full-access", "workspace-write")).toBe("workspace-write");
+    expect(narrowSandboxMode("danger-full-access", "read-only")).toBe("read-only");
+  });
+
+  it("allows tightening from workspace-write", () => {
+    expect(narrowSandboxMode("workspace-write", "read-only")).toBe("read-only");
+  });
+
+  it("rejects loosening", () => {
+    expect(narrowSandboxMode("read-only", "danger-full-access")).toBe("read-only");
+    expect(narrowSandboxMode("read-only", "workspace-write")).toBe("read-only");
+    expect(narrowSandboxMode("workspace-write", "danger-full-access")).toBe("workspace-write");
+  });
+
+  it("same mode returns same mode", () => {
+    expect(narrowSandboxMode("read-only", "read-only")).toBe("read-only");
+  });
+
+  it("invalid override returns base", () => {
+    expect(narrowSandboxMode("workspace-write", "garbage")).toBe("workspace-write");
+  });
+});
+
+// ── validateApprovalPolicy ────────────────────────────────────────
+
+describe("validateApprovalPolicy", () => {
+  it("passes valid policies through", () => {
+    for (const policy of VALID_APPROVAL_POLICIES) {
+      expect(validateApprovalPolicy(policy)).toBe(policy);
+    }
+  });
+
+  it("falls back to on-failure for invalid policies", () => {
+    expect(validateApprovalPolicy("garbage")).toBe("on-failure");
+    expect(validateApprovalPolicy("")).toBe("on-failure");
+  });
+});
+
+// ── narrowApprovalPolicy ──────────────────────────────────────────
+
+describe("narrowApprovalPolicy", () => {
+  it("allows tightening from never", () => {
+    expect(narrowApprovalPolicy("never", "on-failure")).toBe("on-failure");
+    expect(narrowApprovalPolicy("never", "on-request")).toBe("on-request");
+    expect(narrowApprovalPolicy("never", "untrusted")).toBe("untrusted");
+  });
+
+  it("rejects loosening", () => {
+    expect(narrowApprovalPolicy("untrusted", "never")).toBe("untrusted");
+    expect(narrowApprovalPolicy("on-request", "never")).toBe("on-request");
+    expect(narrowApprovalPolicy("on-failure", "never")).toBe("on-failure");
+  });
+
+  it("same policy returns same", () => {
+    expect(narrowApprovalPolicy("never", "never")).toBe("never");
+    expect(narrowApprovalPolicy("untrusted", "untrusted")).toBe("untrusted");
+  });
+
+  it("invalid override returns base", () => {
+    expect(narrowApprovalPolicy("on-failure", "garbage")).toBe("on-failure");
+  });
+});
+
+// ── validateEffort ────────────────────────────────────────────────
+
+describe("validateEffort", () => {
+  it("passes valid efforts through", () => {
+    for (const effort of VALID_EFFORTS) {
+      expect(validateEffort(effort)).toBe(effort);
+    }
+  });
+
+  it("falls back to medium for invalid", () => {
+    expect(validateEffort("garbage")).toBe("medium");
+    expect(validateEffort("")).toBe("medium");
+  });
+});
+
+// ── deriveServerName ──────────────────────────────────────────────
+
+describe("deriveServerName", () => {
+  it("slugifies descriptions", () => {
+    expect(deriveServerName("A strict code reviewer")).toBe("a-strict-code-reviewer");
+  });
+
+  it("limits length to 30 chars", () => {
+    const long = "This is a very long description that should be truncated";
+    expect(deriveServerName(long).length).toBeLessThanOrEqual(30);
+  });
+
+  it("falls back for empty input", () => {
+    expect(deriveServerName("!!!")).toMatch(/^agent-\d+$/);
+  });
+});
+
+// ── deriveToolName ────────────────────────────────────────────────
+
+describe("deriveToolName", () => {
+  it("converts dashes to underscores", () => {
+    expect(deriveToolName("code-reviewer")).toBe("code_reviewer");
+  });
+
+  it("falls back for empty result", () => {
+    expect(deriveToolName("---")).toBe("agent");
+  });
+});
+
+// ── serializeArrayEnv ─────────────────────────────────────────────
+
+describe("serializeArrayEnv", () => {
+  it("joins with comma when no commas in values", () => {
+    expect(serializeArrayEnv(["a", "b"])).toBe("a,b");
+  });
+
+  it("uses JSON when values contain commas", () => {
+    expect(serializeArrayEnv(["a,b", "c"])).toBe('["a,b","c"]');
+  });
+});
+
+// ── formatErrorMessage ────────────────────────────────────────────
+
+describe("formatErrorMessage", () => {
+  it("extracts message from Error", () => {
+    expect(formatErrorMessage(new Error("boom"))).toBe("boom");
+  });
+
+  it("stringifies non-Error values", () => {
+    expect(formatErrorMessage("oops")).toBe("oops");
+    expect(formatErrorMessage(42)).toBe("42");
+  });
+});

package/src/lib.ts

@@ -0,0 +1,187 @@
+/**
+ * Pure, testable logic extracted from index.ts.
+ */
+
+import { normalize, resolve, sep } from "node:path";
+
+// ── Env helpers ────────────────────────────────────────────────────
+
+export function envStr(
+  key: string,
+  env: Record<string, string | undefined> = process.env
+): string | undefined {
+  return env[key] || undefined;
+}
+
+export function envList(
+  key: string,
+  env: Record<string, string | undefined> = process.env
+): string[] | undefined {
+  const val = env[key];
+  if (!val) return undefined;
+  if (val.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(val);
+      if (Array.isArray(parsed)) return parsed.map(String).filter(Boolean);
+    } catch {
+      // fall through to comma-split
+    }
+  }
+  return val
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function envNum(
+  key: string,
+  env: Record<string, string | undefined> = process.env
+): number | undefined {
+  const val = env[key];
+  if (!val) return undefined;
+  const n = Number(val);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+export function envBool(
+  key: string,
+  fallback: boolean,
+  env: Record<string, string | undefined> = process.env
+): boolean {
+  const val = env[key];
+  if (val === undefined) return fallback;
+  return val === "true" || val === "1";
+}
+
+// ── Tool name sanitization ─────────────────────────────────────────
+
+export const MAX_TOOL_NAME_LEN = 64 - "_reply".length;
+
+export function sanitizeToolName(raw: string): string {
+  const sanitized = raw
+    .replace(/[^a-zA-Z0-9_]/g, "_")
+    .slice(0, MAX_TOOL_NAME_LEN);
+  return sanitized || "codex";
+}
+
+// ── cwd security check ────────────────────────────────────────────
+
+export function isDescendantPath(
+  requested: string,
+  baseCwd: string
+): boolean {
+  const normalBase = normalize(baseCwd);
+  const normalReq = normalize(resolve(normalBase, requested));
+  if (normalReq === normalBase) return true;
+  const baseWithSep = normalBase.endsWith(sep)
+    ? normalBase
+    : normalBase + sep;
+  return normalReq.startsWith(baseWithSep);
+}
+
+// ── Sandbox mode validation ───────────────────────────────────────
+
+export const VALID_SANDBOX_MODES = new Set([
+  "read-only",
+  "workspace-write",
+  "danger-full-access",
+]);
+
+export function validateSandboxMode(mode: string): string {
+  return VALID_SANDBOX_MODES.has(mode) ? mode : "read-only";
+}
+
+// Strictness order: most permissive → most restrictive
+const SANDBOX_STRICTNESS: Record<string, number> = {
+  "danger-full-access": 0,
+  "workspace-write": 1,
+  "read-only": 2,
+};
+
+/**
+ * Narrow sandbox mode: returns the stricter of base and override.
+ * Callers can tighten but never loosen.
+ */
+export function narrowSandboxMode(base: string, override: string): string {
+  if (!VALID_SANDBOX_MODES.has(override)) return base;
+  const baseLevel = SANDBOX_STRICTNESS[base] ?? 2;
+  const overrideLevel = SANDBOX_STRICTNESS[override] ?? 2;
+  return overrideLevel >= baseLevel ? override : base;
+}
+
+// ── Approval policy validation ────────────────────────────────────
+
+export const VALID_APPROVAL_POLICIES = new Set([
+  "never",
+  "on-request",
+  "on-failure",
+  "untrusted",
+]);
+
+export function validateApprovalPolicy(policy: string): string {
+  return VALID_APPROVAL_POLICIES.has(policy) ? policy : "on-failure";
+}
+
+const APPROVAL_STRICTNESS: Record<string, number> = {
+  never: 0,
+  "on-failure": 1,
+  "on-request": 2,
+  untrusted: 3,
+};
+
+/**
+ * Narrow approval policy: returns the stricter of base and override.
+ * Callers can tighten but never loosen.
+ */
+export function narrowApprovalPolicy(base: string, override: string): string {
+  if (!VALID_APPROVAL_POLICIES.has(override)) return base;
+  const baseLevel = APPROVAL_STRICTNESS[base] ?? 1;
+  const overrideLevel = APPROVAL_STRICTNESS[override] ?? 1;
+  return overrideLevel >= baseLevel ? override : base;
+}
+
+// ── Effort validation ─────────────────────────────────────────────
+
+export const VALID_EFFORTS = new Set([
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+]);
+
+export function validateEffort(effort: string): string {
+  return VALID_EFFORTS.has(effort) ? effort : "medium";
+}
+
+// ── Factory name derivation ────────────────────────────────────────
+
+export function deriveServerName(description: string): string {
+  const slug = description
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 30);
+  return slug || `agent-${Date.now()}`;
+}
+
+export function deriveToolName(name: string): string {
+  const slug = name
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .replace(/^_|_$/g, "")
+    .slice(0, MAX_TOOL_NAME_LEN);
+  return slug || "agent";
+}
+
+// ── Factory env serialization ──────────────────────────────────────
+
+export function serializeArrayEnv(val: unknown[]): string {
+  const hasComma = val.some((v) => String(v).includes(","));
+  return hasComma ? JSON.stringify(val) : val.join(",");
+}
+
+// ── Formatters ─────────────────────────────────────────────────────
+
+export function formatErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}