codex-octopus 1.0.0

package/src/tools/factory.ts

@@ -0,0 +1,153 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { OPTION_CATALOG } from "../constants.js";
+import {
+  sanitizeToolName,
+  deriveServerName,
+  deriveToolName,
+  serializeArrayEnv,
+} from "../lib.js";
+
+function buildEnvFromParams(
+  params: Record<string, unknown>
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const opt of OPTION_CATALOG) {
+    const val = params[opt.key];
+    if (val === undefined || val === null) continue;
+
+    if (Array.isArray(val)) {
+      if (val.length > 0) env[opt.envVar] = serializeArrayEnv(val);
+    } else if (typeof val === "object") {
+      env[opt.envVar] = JSON.stringify(val);
+    } else if (typeof val === "boolean") {
+      env[opt.envVar] = String(val);
+    } else if (val !== "") {
+      env[opt.envVar] = String(val);
+    }
+  }
+
+  return env;
+}
+
+export function registerFactoryTool(
+  server: McpServer,
+) {
+  server.registerTool("create_codex_mcp", {
+    description: [
+      "Generate a .mcp.json config entry for a new Codex Octopus MCP server instance.",
+      "WHEN TO USE: user says 'codex octopus agent', 'codex octopus mcp',",
+      "'new codex octopus', 'add codex octopus', 'create codex octopus',",
+      "'codex octopus instance', 'codex octopus config', 'codex octopus server',",
+      "or any phrase combining 'codex octopus' with agent/mcp/new/add/create/config/server/setup.",
+      "This is a wizard: only a description is required.",
+      "Returns a ready-to-use .mcp.json config and lists all customization options.",
+      "Call again with more parameters to refine.",
+    ].join(" "),
+    inputSchema: z.object({
+      description: z.string().describe(
+        "What this agent should do, in plain language. Example: 'a code reviewer with read-only sandbox'"
+      ),
+      name: z.string().optional().describe("Server name / alias (derived from description if omitted)"),
+      toolName: z.string().optional().describe("Custom tool name prefix"),
+      model: z.string().optional(),
+      instructions: z.string().optional(),
+      appendInstructions: z.string().optional(),
+      sandboxMode: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
+      approvalPolicy: z.enum(["never", "on-request", "on-failure", "untrusted"]).optional(),
+      cwd: z.string().optional(),
+      additionalDirs: z.array(z.string()).optional(),
+      effort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
+      networkAccess: z.boolean().optional(),
+      webSearchMode: z.enum(["disabled", "cached", "live"]).optional(),
+      persistSession: z.boolean().optional(),
+      apiKey: z.string().optional().describe("OpenAI API key for this agent (leave unset to inherit)"),
+    }),
+  }, async (params) => {
+    const { description, name: nameParam, toolName: toolNameParam } = params;
+
+    const name = nameParam || deriveServerName(description);
+    const derivedToolName = toolNameParam
+      ? sanitizeToolName(toolNameParam)
+      : deriveToolName(name);
+
+    const env: Record<string, string> = {
+      CODEX_TOOL_NAME: derivedToolName,
+      CODEX_SERVER_NAME: name,
+      CODEX_DESCRIPTION: description,
+    };
+
+    const optionEnv = buildEnvFromParams(params);
+    Object.assign(env, optionEnv);
+
+    const configured = Object.keys(optionEnv);
+    const notConfigured = OPTION_CATALOG.filter(
+      (o) => !configured.includes(o.envVar)
+    );
+
+    const SENSITIVE_KEYS = new Set(["CODEX_API_KEY"]);
+
+    const displayEnv: Record<string, string> = {};
+    for (const [k, v] of Object.entries(env)) {
+      displayEnv[k] = SENSITIVE_KEYS.has(k) ? "<REDACTED>" : v;
+    }
+
+    const mcpEntry = {
+      [name]: {
+        command: "npx",
+        args: ["codex-octopus"],
+        env: displayEnv,
+      },
+    };
+
+    const sections: string[] = [];
+
+    sections.push(
+      "## Generated config",
+      "",
+      "Add to `mcpServers` in your `.mcp.json`:",
+      "",
+      "```json",
+      JSON.stringify(mcpEntry, null, 2),
+      "```"
+    );
+
+    sections.push("", "## What's configured");
+    sections.push("", `| Setting | Value |`, `|---|---|`);
+    sections.push(`| Name | \`${name}\` |`);
+    sections.push(`| Tool names | \`${derivedToolName}\`, \`${derivedToolName}_reply\` |`);
+    for (const key of configured) {
+      const opt = OPTION_CATALOG.find((o) => o.envVar === key);
+      if (opt) {
+        const val = SENSITIVE_KEYS.has(key) ? "<REDACTED>" : env[key];
+        sections.push(`| ${opt.label} | \`${val}\` |`);
+      }
+    }
+    if (configured.length === 0) {
+      sections.push(`| _(all defaults)_ | — |`);
+    }
+
+    if (notConfigured.length > 0) {
+      sections.push(
+        "",
+        "## Available customizations",
+        "",
+        "These options are not yet set. Ask the user if they'd like to configure any:",
+        ""
+      );
+      for (const opt of notConfigured) {
+        sections.push(`- **${opt.label}** — ${opt.hint}`);
+        sections.push(`  Example: ${opt.example}`);
+      }
+      sections.push(
+        "",
+        "_Call this tool again with additional parameters to refine the config._"
+      );
+    }
+
+    return {
+      content: [{ type: "text" as const, text: sections.join("\n") }],
+    };
+  });
+}

package/src/tools/query.ts

@@ -0,0 +1,200 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod/v4";
+import { resolve } from "node:path";
+import { Codex } from "@openai/codex-sdk";
+import type { ThreadConfig, InvocationOverrides } from "../types.js";
+import {
+  narrowSandboxMode,
+  narrowApprovalPolicy,
+  formatErrorMessage,
+} from "../lib.js";
+
+interface RunResult {
+  threadId: string;
+  response: string;
+  usage: { input_tokens: number; cached_input_tokens: number; output_tokens: number };
+  isError: boolean;
+}
+
+async function runQuery(
+  prompt: string,
+  overrides: InvocationOverrides,
+  baseConfig: ThreadConfig,
+  apiKey?: string
+): Promise<RunResult> {
+  const codex = new Codex({
+    ...(apiKey ? { apiKey } : {}),
+  });
+
+  const threadOptions: Record<string, unknown> = {};
+
+  // Model
+  const model = overrides.model || baseConfig.model;
+  if (model) threadOptions.model = model;
+
+  // Working directory — accept any path, preserve agent's base access
+  let cwd = baseConfig.cwd || process.cwd();
+  if (overrides.cwd) {
+    const resolvedCwd = resolve(cwd, overrides.cwd);
+    if (resolvedCwd !== cwd) {
+      const dirs = new Set(baseConfig.additionalDirectories || []);
+      dirs.add(cwd);
+      threadOptions.additionalDirectories = [...dirs];
+      cwd = resolvedCwd;
+    }
+  }
+  threadOptions.workingDirectory = cwd;
+
+  // Per-invocation additionalDirs — unions with server-level + auto-added dirs
+  if (overrides.additionalDirs?.length) {
+    const existing = (threadOptions.additionalDirectories as string[]) || baseConfig.additionalDirectories || [];
+    const dirs = new Set(existing);
+    for (const dir of overrides.additionalDirs) {
+      dirs.add(dir);
+    }
+    threadOptions.additionalDirectories = [...dirs];
+  } else if (baseConfig.additionalDirectories && !threadOptions.additionalDirectories) {
+    threadOptions.additionalDirectories = baseConfig.additionalDirectories;
+  }
+
+  // Sandbox mode — can only tighten
+  const baseSandbox = baseConfig.sandboxMode || "read-only";
+  if (overrides.sandboxMode) {
+    threadOptions.sandboxMode = narrowSandboxMode(baseSandbox, overrides.sandboxMode);
+  } else {
+    threadOptions.sandboxMode = baseSandbox;
+  }
+
+  // Approval policy — can only tighten
+  const baseApproval = baseConfig.approvalPolicy || "on-failure";
+  if (overrides.approvalPolicy) {
+    threadOptions.approvalPolicy = narrowApprovalPolicy(baseApproval, overrides.approvalPolicy);
+  } else {
+    threadOptions.approvalPolicy = baseApproval;
+  }
+
+  // Effort
+  const effort = overrides.effort || baseConfig.effort;
+  if (effort) threadOptions.modelReasoningEffort = effort;
+
+  // Network access
+  if (overrides.networkAccess !== undefined) {
+    threadOptions.networkAccessEnabled = overrides.networkAccess;
+  } else if (baseConfig.networkAccess !== undefined) {
+    threadOptions.networkAccessEnabled = baseConfig.networkAccess;
+  }
+
+  // Web search
+  const webSearch = overrides.webSearchMode || baseConfig.webSearchMode;
+  if (webSearch) threadOptions.webSearchMode = webSearch;
+
+  // Start or resume thread
+  const thread = overrides.resumeThreadId
+    ? codex.resumeThread(overrides.resumeThreadId, threadOptions)
+    : codex.startThread(threadOptions);
+
+  // Build prompt with instructions
+  let fullPrompt = prompt;
+  if (!overrides.resumeThreadId) {
+    const instructions = overrides.instructions || baseConfig.instructions;
+    const appendInstructions = baseConfig.appendInstructions;
+    if (instructions) {
+      fullPrompt = `${instructions}\n\n${prompt}`;
+    } else if (appendInstructions) {
+      fullPrompt = `${appendInstructions}\n\n${prompt}`;
+    }
+  }
+
+  const turn = await thread.run(fullPrompt);
+
+  return {
+    threadId: thread.id || "",
+    response: turn.finalResponse || "",
+    usage: turn.usage || { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 },
+    isError: false,
+  };
+}
+
+function formatResult(result: RunResult) {
+  const payload = {
+    thread_id: result.threadId,
+    result: result.response,
+    usage: result.usage,
+    is_error: result.isError,
+  };
+  return {
+    content: [
+      { type: "text" as const, text: JSON.stringify(payload, null, 2) },
+    ],
+    isError: result.isError,
+  };
+}
+
+function formatError(error: unknown) {
+  return {
+    content: [
+      { type: "text" as const, text: `Error: ${formatErrorMessage(error)}` },
+    ],
+    isError: true,
+  };
+}
+
+export function registerQueryTools(
+  server: McpServer,
+  baseConfig: ThreadConfig,
+  toolName: string,
+  toolDescription: string,
+  apiKey?: string
+) {
+  const replyToolName = `${toolName}_reply`;
+
+  server.registerTool(toolName, {
+    description: toolDescription,
+    inputSchema: z.object({
+      prompt: z.string().describe("Task or question for Codex"),
+      cwd: z.string().optional().describe("Working directory (overrides CODEX_CWD)"),
+      model: z.string().optional().describe('Model override (e.g. "gpt-5-codex", "o3", "codex-1")'),
+      additionalDirs: z.array(z.string()).optional().describe("Extra directories the agent can access for this invocation"),
+      effort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional().describe("Reasoning effort override"),
+      sandboxMode: z.enum(["read-only", "workspace-write"]).optional().describe("Sandbox mode override (can only tighten, never loosen)"),
+      approvalPolicy: z.enum(["on-failure", "on-request", "untrusted"]).optional().describe("Approval policy override (can only tighten, never loosen)"),
+      networkAccess: z.boolean().optional().describe("Enable network access from sandbox"),
+      webSearchMode: z.enum(["disabled", "cached", "live"]).optional().describe("Web search mode"),
+      instructions: z.string().optional().describe("Additional instructions (prepended to prompt)"),
+    }),
+  }, async ({ prompt, cwd, model, additionalDirs, effort, sandboxMode, approvalPolicy, networkAccess, webSearchMode, instructions }) => {
+    try {
+      const result = await runQuery(prompt, {
+        cwd, model, additionalDirs, effort, sandboxMode, approvalPolicy, networkAccess, webSearchMode, instructions,
+      }, baseConfig, apiKey);
+      return formatResult(result);
+    } catch (error) {
+      return formatError(error);
+    }
+  });
+
+  if (baseConfig.persistSession !== false) {
+    server.registerTool(replyToolName, {
+      description: [
+        `Continue a previous ${toolName} conversation by thread ID.`,
+        "Use this for follow-up questions, iterative refinement,",
+        "or multi-step workflows that build on prior context.",
+      ].join(" "),
+      inputSchema: z.object({
+        thread_id: z.string().describe(`Thread ID from a prior ${toolName} response`),
+        prompt: z.string().describe("Follow-up instruction or question"),
+        cwd: z.string().optional().describe("Working directory override"),
+        model: z.string().optional().describe("Model override"),
+      }),
+    }, async ({ thread_id, prompt, cwd, model }) => {
+      try {
+        const result = await runQuery(prompt, {
+          cwd, model, resumeThreadId: thread_id,
+        }, baseConfig, apiKey);
+        return formatResult(result);
+      } catch (error) {
+        return formatError(error);
+      }
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+export interface ThreadConfig {
+  cwd?: string;
+  model?: string;
+  sandboxMode?: "read-only" | "workspace-write" | "danger-full-access";
+  approvalPolicy?: "never" | "on-request" | "on-failure" | "untrusted";
+  effort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  additionalDirectories?: string[];
+  networkAccess?: boolean;
+  webSearchMode?: "disabled" | "cached" | "live";
+  persistSession?: boolean;
+  instructions?: string;
+  appendInstructions?: string;
+}
+
+export interface InvocationOverrides {
+  cwd?: string;
+  model?: string;
+  sandboxMode?: string;
+  approvalPolicy?: string;
+  effort?: string;
+  additionalDirs?: string[];
+  networkAccess?: boolean;
+  webSearchMode?: string;
+  instructions?: string;
+  resumeThreadId?: string;
+}
+
+export interface OptionCatalogEntry {
+  key: string;
+  envVar: string;
+  label: string;
+  hint: string;
+  example: string;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}