@wyrd-company/async-codex-mcp 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# async-codex-mcp
+
+Async Codex MCP server.
+
+This package implements an MCP server that proxies a Codex MCP server and turns blocking `codex` calls into background sessions. Configured profile tools return immediately with an async session id; clients can poll `session-status`, receive `notifications/message` completion events, and resume completed Codex sessions with `continue-session`.
+
+## Why
+
+The Codex CLI can run as an MCP server with `codex mcp-server`, exposing blocking `codex` and `codex-reply` tools. This server wraps those tools to:
+
+- expose named, opinionated profile tools from YAML configuration;
+- restrict caller-controlled inputs to `prompt`, `model`, and `cwd`;
+- default Codex execution to `sandboxMode: danger-full-access` and `approvalPolicy: never` for devcontainer use;
+- return immediately while Codex runs in the background;
+- send MCP logging notifications when a background session completes or fails;
+- expose `continue-session` as a generic wrapper around `codex-reply`.
+
+## Install
+
+```bash
+npm install --global @wyrd-company/async-codex-mcp
+```
+
+## Configuration
+
+Pass a YAML file path as the first CLI argument, or set `ASYNC_CODEX_MCP_CONFIG`. If no config is provided, a single `codex` profile is created with `danger-full-access` sandboxing and `never` approval policy.
+
+Example:
+
+```yaml
+codex:
+  command: codex
+  args: [mcp-server]
+  env: {}
+
+tools:
+  codex-write:
+    description: Run Codex asynchronously with full filesystem access.
+    sandboxMode: danger-full-access
+    approvalPolicy: never
+  codex-review:
+    description: Ask Codex to review code without making edits.
+    sandboxMode: read-only
+    approvalPolicy: never
+```
+
+Tool `config` values are passed through to the underlying Codex MCP `codex` tool as Codex config overrides. For example, this exposes a separate tool that routes through an Azure/OpenAI-compatible provider:
+
+```yaml
+tools:
+  codex-azure-review:
+    description: Ask Codex to review code using Azure OpenAI.
+    sandboxMode: read-only
+    approvalPolicy: never
+    model: gpt-5-codex
+    config:
+      model_provider: azure
+      model_providers:
+        azure:
+          name: Azure
+          base_url: https://YOUR_RESOURCE_NAME.openai.azure.com/openai
+          wire_api: responses
+          query_params:
+            api-version: 2025-04-01-preview
+          env_key: AZURE_OPENAI_API_KEY
+```
+
+Keep API keys in environment variables, not YAML. In the example above, Codex reads the provider key from `AZURE_OPENAI_API_KEY`.
+
+Callbacks are enabled by default. For each async session, this wrapper injects a session-scoped MCP server into Codex with two tools:
+
+- `async_codex_ask_user`: blocking; Codex sends `message` plus optional `context` and waits until the async session is answered.
+- `async_codex_notify_user`: non-blocking; Codex sends `message` plus optional `topic` and keeps working.
+
+Use `answer-session` to respond when `session-status` reports `waiting_for_input`.
+
+Disable callbacks globally:
+
+```yaml
+callbacks:
+  enabled: false
+```
+
+Or disable them for one configured tool:
+
+```yaml
+tools:
+  codex-review:
+    description: Ask Codex to review code without making edits.
+    sandboxMode: read-only
+    approvalPolicy: never
+    callbacks:
+      enabled: false
+```
+
+## Run
+
+```bash
+node dist/src/cli.js ./fixtures/async-codex-mcp.yaml
+```
+
+Each configured profile becomes an MCP tool that accepts:
+
+- `prompt` (required): prompt to send to Codex;
+- `model` (optional): model override, for example `gpt-5.4-mini`;
+- `cwd` (optional): working directory for the run.
+
+The profile tool returns JSON with an async `session_id` and `running` status. Use `session-status` with that id to inspect completion state. When complete, use `continue-session` with the async session id and a new `prompt` to resume the underlying Codex session.
+
+If a session is waiting for input, answer it with:
+
+```json
+{
+  "session_id": "<async-session-id>",
+  "message": "Use staging."
+}
+```
+
+## Claude Code plugin
+
+This repo includes the `async-codex-mcp` Claude Code plugin under `plugins/async-codex-mcp`. The marketplace manifest lives in the dedicated Wyrd Company plugin marketplace repository.
+
+## Publishing
+
+The package is published publicly to npm as `@wyrd-company/async-codex-mcp`. Publishing is handled by the `Publish Package` GitHub Actions workflow, which runs tests, builds the package, and publishes with the repository `NPM_TOKEN` secret.
+
+Run it manually from GitHub Actions, or push a SemVer tag without a `v` prefix, for example `0.1.0`.
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+The test suite uses ThoughtSpot's `mcp-testing-kit` transport approach to exercise the MCP server directly and validates a `gpt-5.4-mini` model override without making network calls.

package/dist/src/callback-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/callback-cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const options = parseArgs(process.argv.slice(2));
+const server = new McpServer({ name: "async-codex-mcp-callback", version: "0.1.0" }, {
+    instructions: "Use async_codex_ask_user only when you need a user answer before continuing. Use async_codex_notify_user for non-blocking progress updates or FYIs.",
+});
+server.tool("async_codex_ask_user", "Ask the user a blocking question. Codex waits until the user responds to the async session.", {
+    message: z.string().min(1).describe("The question or problem that needs a user response."),
+    context: z.string().optional().describe("Optional context explaining why the answer is needed."),
+}, async ({ message, context }) => {
+    const result = await postCallback("/ask", { message, context });
+    return textResult(result.answer);
+});
+server.tool("async_codex_notify_user", "Send a non-blocking progress update or FYI to the user.", {
+    message: z.string().min(1).describe("The progress update or FYI to send."),
+    topic: z.string().optional().describe("Optional free-text topic for the notification."),
+}, async ({ message, topic }) => {
+    await postCallback("/notify", { message, topic });
+    return textResult("Notification delivered.");
+});
+await server.connect(new StdioServerTransport());
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+async function postCallback(path, body) {
+    const response = await fetch(`${options.url}${path}`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${options.token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({ ...body, session_id: options.sessionId }),
+    });
+    const json = (await response.json());
+    if (!response.ok) {
+        throw new Error(json.error ?? `Callback failed with HTTP ${response.status}.`);
+    }
+    return json;
+}
+function parseArgs(args) {
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 2) {
+        const key = args[index];
+        const value = args[index + 1];
+        if (!key?.startsWith("--") || !value) {
+            throw new Error(`Invalid callback argument near ${key ?? "<end>"}.`);
+        }
+        values.set(key.slice(2), value);
+    }
+    const url = values.get("url");
+    const token = values.get("token");
+    const sessionId = values.get("session-id");
+    if (!url || !token || !sessionId) {
+        throw new Error("--url, --token, and --session-id are required.");
+    }
+    return { url, token, sessionId };
+}

package/dist/src/callback-hub.d.ts

@@ -0,0 +1,28 @@
+export type CallbackHubHandlers = {
+    ask(input: {
+        sessionId: string;
+        message: string;
+        context?: string;
+    }): Promise<string>;
+    notify(input: {
+        sessionId: string;
+        message: string;
+        topic?: string;
+    }): Promise<void>;
+};
+export type CallbackHubConnection = {
+    url: string;
+    token: string;
+};
+export declare class CallbackHub {
+    private readonly handlers;
+    private server?;
+    private connection?;
+    private readonly token;
+    private readonly sockets;
+    constructor(handlers: CallbackHubHandlers);
+    ensureStarted(): Promise<CallbackHubConnection>;
+    close(): Promise<void>;
+    private handle;
+    private writeJson;
+}

package/dist/src/callback-hub.js

@@ -0,0 +1,128 @@
+import http from "node:http";
+export class CallbackHub {
+    handlers;
+    server;
+    connection;
+    token = crypto.randomUUID();
+    sockets = new Set();
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
+    async ensureStarted() {
+        if (this.connection)
+            return this.connection;
+        this.server = http.createServer((request, response) => {
+            void this.handle(request, response);
+        });
+        this.server.on("connection", (socket) => {
+            this.sockets.add(socket);
+            socket.on("close", () => this.sockets.delete(socket));
+        });
+        await new Promise((resolve, reject) => {
+            this.server?.once("error", reject);
+            this.server?.listen(0, "127.0.0.1", () => resolve());
+        });
+        const address = this.server.address();
+        if (!address || typeof address === "string") {
+            throw new Error("Callback hub did not bind to a TCP port.");
+        }
+        this.connection = {
+            url: `http://127.0.0.1:${address.port}`,
+            token: this.token,
+        };
+        return this.connection;
+    }
+    async close() {
+        if (!this.server)
+            return;
+        const server = this.server;
+        this.server = undefined;
+        this.connection = undefined;
+        for (const socket of this.sockets) {
+            socket.destroy();
+        }
+        this.sockets.clear();
+        await new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        });
+    }
+    async handle(request, response) {
+        try {
+            if (request.method !== "POST") {
+                this.writeJson(response, 405, { error: "Only POST is supported." });
+                return;
+            }
+            if (request.headers.authorization !== `Bearer ${this.token}`) {
+                this.writeJson(response, 401, { error: "Invalid callback token." });
+                return;
+            }
+            const body = await readJson(request);
+            const parsed = parseCallbackRequest(body);
+            if (!parsed.ok) {
+                this.writeJson(response, 400, { error: parsed.error });
+                return;
+            }
+            if (request.url === "/ask") {
+                const answer = await this.handlers.ask({
+                    sessionId: parsed.value.session_id,
+                    message: parsed.value.message,
+                    context: parsed.value.context,
+                });
+                this.writeJson(response, 200, { answer });
+                return;
+            }
+            if (request.url === "/notify") {
+                await this.handlers.notify({
+                    sessionId: parsed.value.session_id,
+                    message: parsed.value.message,
+                    topic: parsed.value.topic,
+                });
+                this.writeJson(response, 200, { delivered: true });
+                return;
+            }
+            this.writeJson(response, 404, { error: "Unknown callback endpoint." });
+        }
+        catch (error) {
+            this.writeJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    writeJson(response, statusCode, body) {
+        response.writeHead(statusCode, { "content-type": "application/json" });
+        response.end(JSON.stringify(body));
+    }
+}
+async function readJson(request) {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const text = Buffer.concat(chunks).toString("utf8");
+    return text ? JSON.parse(text) : {};
+}
+function parseCallbackRequest(body) {
+    if (!body || typeof body !== "object") {
+        return { ok: false, error: "Request body must be an object." };
+    }
+    const value = body;
+    if (typeof value.session_id !== "string" || !value.session_id) {
+        return { ok: false, error: "session_id is required." };
+    }
+    if (typeof value.message !== "string" || !value.message) {
+        return { ok: false, error: "message is required." };
+    }
+    if (value.context !== undefined && typeof value.context !== "string") {
+        return { ok: false, error: "context must be a string." };
+    }
+    if (value.topic !== undefined && typeof value.topic !== "string") {
+        return { ok: false, error: "topic must be a string." };
+    }
+    return {
+        ok: true,
+        value: {
+            session_id: value.session_id,
+            message: value.message,
+            context: value.context,
+            topic: value.topic,
+        },
+    };
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+const configPath = process.argv[2];
+const config = loadConfig(configPath);
+const server = createServer(config);
+await server.connect(new StdioServerTransport());

package/dist/src/codex-client.d.ts

@@ -0,0 +1,22 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { AsyncCodexConfig, ToolProfile } from "./config.js";
+export type CodexToolArguments = {
+    prompt: string;
+    model?: string;
+    cwd?: string;
+};
+export type CodexClientLike = {
+    callCodex(profile: ToolProfile, args: CodexToolArguments): Promise<CallToolResult>;
+    continueSession(sessionId: string, prompt: string, cwd?: string): Promise<CallToolResult>;
+    close(): Promise<void>;
+};
+export declare class CodexMcpClient implements CodexClientLike {
+    private readonly config;
+    private client?;
+    private transport?;
+    constructor(config: AsyncCodexConfig);
+    callCodex(profile: ToolProfile, args: CodexToolArguments): Promise<CallToolResult>;
+    continueSession(sessionId: string, prompt: string, cwd?: string): Promise<CallToolResult>;
+    close(): Promise<void>;
+    private getClient;
+}

package/dist/src/codex-client.js

@@ -0,0 +1,59 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+export class CodexMcpClient {
+    config;
+    client;
+    transport;
+    constructor(config) {
+        this.config = config;
+    }
+    async callCodex(profile, args) {
+        const client = await this.getClient();
+        const codexArgs = {
+            prompt: args.prompt,
+            sandbox: profile.sandboxMode,
+            "approval-policy": profile.approvalPolicy,
+        };
+        const model = args.model ?? profile.model;
+        if (model)
+            codexArgs.model = model;
+        if (args.cwd)
+            codexArgs.cwd = args.cwd;
+        if (profile.baseInstructions)
+            codexArgs["base-instructions"] = profile.baseInstructions;
+        if (profile.compactPrompt)
+            codexArgs["compact-prompt"] = profile.compactPrompt;
+        if (profile.developerInstructions)
+            codexArgs["developer-instructions"] = profile.developerInstructions;
+        if (Object.keys(profile.config).length > 0)
+            codexArgs.config = profile.config;
+        return client.callTool({ name: "codex", arguments: codexArgs });
+    }
+    async continueSession(sessionId, prompt, cwd) {
+        const client = await this.getClient();
+        const args = { threadId: sessionId, prompt };
+        if (cwd)
+            args.cwd = cwd;
+        return client.callTool({ name: "codex-reply", arguments: args });
+    }
+    async close() {
+        await this.client?.close();
+        await this.transport?.close();
+        this.client = undefined;
+        this.transport = undefined;
+    }
+    async getClient() {
+        if (this.client)
+            return this.client;
+        this.client = new Client({ name: "async-codex-mcp-client", version: "0.1.0" });
+        this.transport = new StdioClientTransport({
+            command: this.config.codex.command,
+            args: this.config.codex.args,
+            env: { ...process.env, ...this.config.codex.env },
+            cwd: this.config.codex.cwd,
+            stderr: "inherit",
+        });
+        await this.client.connect(this.transport);
+        return this.client;
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+declare const profileSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    approvalPolicy: z.ZodDefault<z.ZodString>;
+    sandboxMode: z.ZodDefault<z.ZodString>;
+    baseInstructions: z.ZodOptional<z.ZodString>;
+    compactPrompt: z.ZodOptional<z.ZodString>;
+    developerInstructions: z.ZodOptional<z.ZodString>;
+    config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    callbacks: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const configSchema: z.ZodObject<{
+    codex: z.ZodDefault<z.ZodObject<{
+        command: z.ZodDefault<z.ZodString>;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    callbacks: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    tools: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        approvalPolicy: z.ZodDefault<z.ZodString>;
+        sandboxMode: z.ZodDefault<z.ZodString>;
+        baseInstructions: z.ZodOptional<z.ZodString>;
+        compactPrompt: z.ZodOptional<z.ZodString>;
+        developerInstructions: z.ZodOptional<z.ZodString>;
+        config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        callbacks: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>;
+export type AsyncCodexConfig = z.infer<typeof configSchema>;
+export type ToolProfile = z.infer<typeof profileSchema>;
+export declare function loadConfig(configPath?: string): AsyncCodexConfig;
+export {};

package/dist/src/config.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+import { z } from "zod";
+const stringRecordSchema = z.record(z.string(), z.string());
+const unknownRecordSchema = z.record(z.string(), z.unknown());
+const codexServerSchema = z.object({
+    command: z.string().default("codex"),
+    args: z.array(z.string()).default(["mcp-server"]),
+    env: stringRecordSchema.default({}),
+    cwd: z.string().optional(),
+});
+const callbacksSchema = z.object({
+    enabled: z.boolean().default(true),
+}).strict();
+const profileCallbacksSchema = z.object({
+    enabled: z.boolean(),
+}).strict();
+const profileSchema = z.object({
+    description: z.string().optional(),
+    model: z.string().optional(),
+    approvalPolicy: z.string().default("never"),
+    sandboxMode: z.string().default("danger-full-access"),
+    baseInstructions: z.string().optional(),
+    compactPrompt: z.string().optional(),
+    developerInstructions: z.string().optional(),
+    config: unknownRecordSchema.default({}),
+    callbacks: profileCallbacksSchema.optional(),
+}).strict();
+const configSchema = z.object({
+    codex: codexServerSchema.default({ command: "codex", args: ["mcp-server"], env: {} }),
+    callbacks: callbacksSchema.default({ enabled: true }),
+    tools: z.record(z.string(), profileSchema).default({
+        codex: {
+            description: "Run Codex asynchronously with danger-full-access sandboxing.",
+            sandboxMode: "danger-full-access",
+            approvalPolicy: "never",
+            config: {},
+        },
+    }),
+});
+export function loadConfig(configPath) {
+    const resolvedPath = configPath ?? process.env.ASYNC_CODEX_MCP_CONFIG;
+    if (!resolvedPath) {
+        return configSchema.parse({});
+    }
+    const file = fs.readFileSync(resolvedPath, "utf8");
+    const loaded = yaml.load(file) ?? {};
+    const parsed = configSchema.parse(loaded);
+    if (parsed.codex.cwd && !path.isAbsolute(parsed.codex.cwd)) {
+        parsed.codex.cwd = path.resolve(path.dirname(resolvedPath), parsed.codex.cwd);
+    }
+    return parsed;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { loadConfig, type AsyncCodexConfig, type ToolProfile } from "./config.js";
+export { createServer, type CreateServerOptions } from "./server.js";
+export { CodexMcpClient, type CodexClientLike } from "./codex-client.js";
+export { SessionStore, type SessionRecord, type SessionStatus } from "./session-store.js";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { loadConfig } from "./config.js";
+export { createServer } from "./server.js";
+export { CodexMcpClient } from "./codex-client.js";
+export { SessionStore } from "./session-store.js";

package/dist/src/server.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CodexClientLike } from "./codex-client.js";
+import type { AsyncCodexConfig } from "./config.js";
+import { SessionStore } from "./session-store.js";
+export type CreateServerOptions = {
+    client?: CodexClientLike;
+    store?: SessionStore;
+};
+export declare function createServer(config: AsyncCodexConfig, options?: CreateServerOptions): McpServer;

package/dist/src/server.js

@@ -0,0 +1,231 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { CallbackHub } from "./callback-hub.js";
+import { CodexMcpClient } from "./codex-client.js";
+import { SessionStore } from "./session-store.js";
+const runShape = {
+    prompt: z.string().min(1).describe("Prompt to send to Codex."),
+    model: z.string().optional().describe("Optional model override for this run."),
+    cwd: z.string().optional().describe("Optional working directory for Codex."),
+};
+const continueShape = {
+    session_id: z.string().min(1).describe("Async session id returned by a profile tool."),
+    prompt: z.string().min(1).describe("Prompt to continue the completed Codex session."),
+    cwd: z.string().optional().describe("Optional working directory for Codex."),
+};
+const answerShape = {
+    session_id: z.string().min(1).describe("Async session id waiting for user input."),
+    message: z.string().min(1).describe("User response to return to Codex."),
+};
+export function createServer(config, options = {}) {
+    const server = new McpServer({ name: "async-codex-mcp", version: "0.1.0" }, {
+        capabilities: { logging: {} },
+        instructions: "Starts Codex sub-agent sessions asynchronously. Profile tools return immediately with an async session id; use continue-session after completion to resume.",
+    });
+    const client = options.client ?? new CodexMcpClient(config);
+    const store = options.store ?? new SessionStore();
+    const callbackHub = new CallbackHub({
+        ask: async ({ sessionId, message, context }) => {
+            const ask = store.ask(sessionId, { message, context });
+            await sendCallbackNotification(server, sessionId, "ask", message, { context });
+            return ask.response;
+        },
+        notify: async ({ sessionId, message, topic }) => {
+            store.notify(sessionId, { message, topic });
+            await sendCallbackNotification(server, sessionId, "notify", message, { topic });
+        },
+    });
+    let closeServicesPromise;
+    const closeServices = () => {
+        closeServicesPromise ??= Promise.all([client.close(), callbackHub.close()]).then(() => undefined);
+        return closeServicesPromise;
+    };
+    const originalOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        originalOnClose?.();
+        void closeServices().catch((error) => {
+            server.server.onerror?.(error instanceof Error ? error : new Error(String(error)));
+        });
+    };
+    const originalServerClose = server.server.close.bind(server.server);
+    server.server.close = async () => {
+        await originalServerClose();
+        await closeServices();
+    };
+    const originalClose = server.close.bind(server);
+    server.close = async () => {
+        await originalClose();
+        await closeServices();
+    };
+    for (const [name, profile] of Object.entries(config.tools)) {
+        server.tool(name, profile.description ?? `Start an asynchronous Codex session using the ${name} profile.`, runShape, async ({ prompt, model, cwd }) => {
+            const session = store.create({ toolName: name, prompt, model, cwd });
+            const effectiveProfile = await prepareProfile(config, profile, session.id, callbackHub);
+            void client
+                .callCodex(effectiveProfile, { prompt, model, cwd })
+                .then(async (result) => {
+                if (result.isError) {
+                    const message = errorMessageFromResult(result);
+                    store.update(session.id, { status: "failed", result, error: message });
+                    await sendSessionNotification(server, session.id, "failed", undefined, message);
+                    return;
+                }
+                const codexSessionId = extractCodexSessionId(result);
+                store.update(session.id, { status: "completed", result, codexSessionId });
+                await sendSessionNotification(server, session.id, "completed", codexSessionId);
+            })
+                .catch(async (error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                store.update(session.id, { status: "failed", error: message });
+                await sendSessionNotification(server, session.id, "failed", undefined, message);
+            });
+            return textResult(JSON.stringify({
+                session_id: session.id,
+                status: session.status,
+                message: "Codex session started. Watch notifications/message for completion.",
+            }, null, 2));
+        });
+    }
+    server.tool("session-status", "Inspect an asynchronous Codex session by id.", { session_id: z.string().min(1).describe("Async session id returned by a profile tool.") }, async ({ session_id }) => {
+        const session = store.get(session_id);
+        if (!session) {
+            return textResult(`Unknown session: ${session_id}`, true);
+        }
+        return textResult(JSON.stringify({
+            id: session.id,
+            toolName: session.toolName,
+            status: session.status,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            codexSessionId: session.codexSessionId,
+            error: session.error,
+            messages: session.messages,
+            pendingAskId: session.pendingAskId,
+            result: session.result,
+        }, null, 2));
+    });
+    server.tool("continue-session", "Resume a completed async Codex session.", continueShape, async ({ session_id, prompt, cwd }) => {
+        const session = store.get(session_id);
+        if (!session)
+            return textResult(`Unknown session: ${session_id}`, true);
+        if (session.status !== "completed")
+            return textResult(`Session ${session_id} is ${session.status}; only completed sessions can be continued.`, true);
+        if (!session.codexSessionId)
+            return textResult(`Session ${session_id} did not expose a Codex session id.`, true);
+        try {
+            const result = await client.continueSession(session.codexSessionId, prompt, cwd ?? session.cwd);
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return textResult(message, true);
+        }
+    });
+    server.tool("answer-session", "Answer a Codex question for an async session waiting for input.", answerShape, async ({ session_id, message }) => {
+        const session = store.get(session_id);
+        if (!session)
+            return textResult(`Unknown session: ${session_id}`, true);
+        if (session.status !== "waiting_for_input")
+            return textResult(`Session ${session_id} is ${session.status}; only waiting_for_input sessions can be answered.`, true);
+        try {
+            const answered = store.answer(session_id, message);
+            return textResult(JSON.stringify({
+                session_id,
+                answered_message_id: answered.id,
+                status: store.get(session_id)?.status,
+            }, null, 2));
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return textResult(errorMessage, true);
+        }
+    });
+    return server;
+}
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+function errorMessageFromResult(result) {
+    const text = result.content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n")
+        .trim();
+    return text || "Codex returned an error result.";
+}
+async function sendSessionNotification(server, sessionId, status, codexSessionId, error) {
+    await server.server.sendLoggingMessage({
+        level: status === "completed" ? "notice" : "error",
+        logger: "async-codex-mcp",
+        data: { session_id: sessionId, status, codex_session_id: codexSessionId, error },
+    });
+}
+async function sendCallbackNotification(server, sessionId, type, message, extra) {
+    await server.server.sendLoggingMessage({
+        level: type === "ask" ? "warning" : "info",
+        logger: "async-codex-mcp",
+        data: { session_id: sessionId, type, message, ...extra },
+    });
+}
+async function prepareProfile(config, profile, sessionId, callbackHub) {
+    if (!callbacksEnabled(config, profile)) {
+        return profile;
+    }
+    const connection = await callbackHub.ensureStarted();
+    return {
+        ...profile,
+        developerInstructions: appendCallbackInstructions(profile.developerInstructions),
+        config: {
+            ...profile.config,
+            mcp_servers: {
+                ...recordValue(profile.config.mcp_servers),
+                async_codex_mcp_callback: {
+                    command: process.execPath,
+                    args: [
+                        callbackCliPath(),
+                        "--url",
+                        connection.url,
+                        "--token",
+                        connection.token,
+                        "--session-id",
+                        sessionId,
+                    ],
+                },
+            },
+        },
+    };
+}
+function callbacksEnabled(config, profile) {
+    return profile.callbacks?.enabled ?? config.callbacks.enabled;
+}
+function appendCallbackInstructions(existing) {
+    const callbackInstructions = "You have two callback tools for communicating with the user during this async Codex session. " +
+        "Call async_codex_ask_user with message and optional context only when you need a user answer before continuing; the tool blocks until the user answers. " +
+        "Call async_codex_notify_user with message and optional topic for non-blocking progress updates, warnings, or FYIs.";
+    return existing ? `${existing}\n\n${callbackInstructions}` : callbackInstructions;
+}
+function callbackCliPath() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "callback-cli.js");
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function extractCodexSessionId(result) {
+    const meta = result._meta;
+    for (const key of ["threadId", "session_id", "sessionId", "codex_session_id", "codexSessionId"]) {
+        const value = meta?.[key];
+        if (typeof value === "string")
+            return value;
+    }
+    const structured = result.structuredContent;
+    if (typeof structured?.threadId === "string")
+        return structured.threadId;
+    const text = result.content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n");
+    const match = text.match(/(?:thread[_ -]?id|session[_ -]?id|codex[_ -]?session[_ -]?id)["'`:\s]+([a-zA-Z0-9_-]+)/i);
+    return match?.[1];
+}

package/dist/src/session-store.d.ts

@@ -0,0 +1,47 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export type SessionStatus = "running" | "waiting_for_input" | "completed" | "failed";
+export type SessionMessage = {
+    id: string;
+    type: "ask" | "notify";
+    message: string;
+    context?: string;
+    topic?: string;
+    createdAt: string;
+    answeredAt?: string;
+    response?: string;
+};
+export type SessionRecord = {
+    id: string;
+    toolName: string;
+    prompt: string;
+    model?: string;
+    cwd?: string;
+    status: SessionStatus;
+    createdAt: string;
+    updatedAt: string;
+    codexSessionId?: string;
+    result?: CallToolResult;
+    error?: string;
+    messages: SessionMessage[];
+    pendingAskId?: string;
+};
+export declare class SessionStore {
+    readonly sessions: Map<string, SessionRecord>;
+    private readonly pendingAskResolvers;
+    create(input: Pick<SessionRecord, "toolName" | "prompt" | "model" | "cwd">): SessionRecord;
+    get(id: string): SessionRecord | undefined;
+    update(id: string, patch: Partial<Omit<SessionRecord, "id" | "createdAt">>): SessionRecord;
+    notify(sessionId: string, input: {
+        message: string;
+        topic?: string;
+    }): SessionMessage;
+    ask(sessionId: string, input: {
+        message: string;
+        context?: string;
+    }): {
+        message: SessionMessage;
+        response: Promise<string>;
+    };
+    answer(sessionId: string, response: string): SessionMessage;
+    private require;
+}

package/dist/src/session-store.js

@@ -0,0 +1,91 @@
+export class SessionStore {
+    sessions = new Map();
+    pendingAskResolvers = new Map();
+    create(input) {
+        const now = new Date().toISOString();
+        const session = {
+            ...input,
+            id: crypto.randomUUID(),
+            status: "running",
+            createdAt: now,
+            updatedAt: now,
+            messages: [],
+        };
+        this.sessions.set(session.id, session);
+        return session;
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    update(id, patch) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            throw new Error(`Unknown session: ${id}`);
+        }
+        Object.assign(session, patch, { updatedAt: new Date().toISOString() });
+        return session;
+    }
+    notify(sessionId, input) {
+        const session = this.require(sessionId);
+        const now = new Date().toISOString();
+        const message = {
+            id: crypto.randomUUID(),
+            type: "notify",
+            message: input.message,
+            topic: input.topic,
+            createdAt: now,
+        };
+        session.messages.push(message);
+        session.updatedAt = now;
+        return message;
+    }
+    ask(sessionId, input) {
+        const session = this.require(sessionId);
+        if (session.pendingAskId) {
+            throw new Error(`Session ${sessionId} is already waiting for input.`);
+        }
+        const now = new Date().toISOString();
+        const message = {
+            id: crypto.randomUUID(),
+            type: "ask",
+            message: input.message,
+            context: input.context,
+            createdAt: now,
+        };
+        session.messages.push(message);
+        session.pendingAskId = message.id;
+        session.status = "waiting_for_input";
+        session.updatedAt = now;
+        const response = new Promise((resolve) => {
+            this.pendingAskResolvers.set(message.id, resolve);
+        });
+        return { message, response };
+    }
+    answer(sessionId, response) {
+        const session = this.require(sessionId);
+        if (!session.pendingAskId) {
+            throw new Error(`Session ${sessionId} is not waiting for input.`);
+        }
+        const message = session.messages.find((item) => item.id === session.pendingAskId);
+        if (!message) {
+            throw new Error(`Session ${sessionId} pending question was not found.`);
+        }
+        const now = new Date().toISOString();
+        message.response = response;
+        message.answeredAt = now;
+        session.pendingAskId = undefined;
+        session.status = "running";
+        session.updatedAt = now;
+        const resolve = this.pendingAskResolvers.get(message.id);
+        this.pendingAskResolvers.delete(message.id);
+        resolve?.(response);
+        return message;
+    }
+    require(id) {
+        const session = this.sessions.get(id);
+        if (!session) {
+            throw new Error(`Unknown session: ${id}`);
+        }
+        return session;
+    }
+}

package/fixtures/async-codex-mcp.yaml

@@ -0,0 +1,12 @@
+codex:
+  command: codex
+  args: [mcp-server]
+tools:
+  codex-write:
+    description: Run Codex asynchronously with full filesystem access.
+    sandboxMode: danger-full-access
+    approvalPolicy: never
+  codex-review:
+    description: Ask Codex to review code without making edits.
+    sandboxMode: read-only
+    approvalPolicy: never

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@wyrd-company/async-codex-mcp",
+  "version": "0.1.0",
+  "description": "Async MCP proxy for Codex MCP server profiles",
+  "type": "module",
+  "bin": {
+    "async-codex-mcp": "dist/src/cli.js"
+  },
+  "main": "dist/src/index.js",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "start": "node dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "fixtures",
+    "plugins/async-codex-mcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wyrd-company/async-codex-mcp.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "js-yaml": "^4.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@openai/codex": "^0.135.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.15.3",
+    "mcp-testing-kit": "github:thoughtspot/mcp-testing-kit",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

package/plugins/async-codex-mcp/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "async-codex-mcp",
+  "displayName": "Async Codex MCP",
+  "version": "0.1.0",
+  "description": "Expose async Codex MCP profile tools to Claude Code.",
+  "author": {
+    "name": "Wyrd Company"
+  },
+  "repository": "https://github.com/wyrd-company/async-codex-mcp",
+  "keywords": ["codex", "mcp", "async"],
+  "mcpServers": "./.mcp.json"
+}

package/plugins/async-codex-mcp/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "async-codex-mcp": {
+      "command": "npx",
+      "args": [
+        "--yes",
+        "@wyrd-company/async-codex-mcp"
+      ],
+      "env": {}
+    }
+  }
+}