@minhspark/codex-mcp-bridge 1.11.3 → 1.12.1

package/src/native-relay-companion.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  MAX_FRAME_BYTES,
+  NATIVE_DISPATCH_METHOD,
+  RELAY_PROTOCOL_VERSION,
+  nativeDispatchParams,
+  relaySocketPath,
+  resolveRelayThreadId,
+} from "./native-relay.mjs";
+import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
+
+/**
+ * The companion half of the Codex Desktop native relay.
+ *
+ * Codex Desktop launches this as one of its own MCP servers, so the connection
+ * it answers on belongs to the app's real app-server - the one already holding
+ * the writer lock of every thread the human has open. Asking that app-server to
+ * deliver a message is therefore not a second writer, and the thread stays open
+ * and owned by Codex Desktop throughout.
+ *
+ * Everything else is deliberately small: a private socket, one accepted shape
+ * (`{ targetThreadId, message }`), one dispatch, one acknowledgement.
+ */
+
+const VERSION = "1.12.1";
+const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
+
+function errorResponse(code, message) {
+  return { ok: false, v: RELAY_PROTOCOL_VERSION, error: { code, message } };
+}
+
+/**
+ * A JSON-RPC error arrives with a numeric code, and passing that straight back
+ * would put `-32601` in a field whose other values read `RELAY_TIMEOUT`. Only a
+ * string code from this project's own errors is carried through.
+ */
+function errorCode(err) {
+  return typeof err?.code === "string" ? err.code : "NATIVE_DISPATCH_FAILED";
+}
+
+/**
+ * The whole request handler, kept free of sockets and of the MCP connection so
+ * the rules it enforces can be tested against a stub dispatcher rather than
+ * against a running Codex Desktop.
+ */
+export async function handleRelayRequest(
+  payload,
+  { dispatch, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
+) {
+  const targetThreadId = typeof payload?.targetThreadId === "string" ? payload.targetThreadId.trim() : "";
+  const message = typeof payload?.message === "string" ? payload.message : "";
+
+  if (!targetThreadId) return errorResponse("RELAY_BAD_REQUEST", "targetThreadId must be a non-empty string");
+  if (!message.trim()) return errorResponse("RELAY_BAD_REQUEST", "message must be a non-empty string");
+
+  let executorThreadId;
+  try {
+    executorThreadId = resolveExecutor(env).threadId;
+  } catch (err) {
+    return errorResponse(errorCode(err), err.message);
+  }
+
+  /**
+   * Codex validates the executor thread, so a destination that is also the
+   * executor would be dispatched rather than refused - and the message would
+   * land in the relay thread instead of the thread the human is watching.
+   * Nothing downstream can tell those two apart afterwards.
+   */
+  if (executorThreadId === targetThreadId) {
+    return errorResponse(
+      "RELAY_BAD_REQUEST",
+      `${targetThreadId} is the relay's own executor thread, not a destination. Bind the thread you are watching in Codex Desktop.`,
+    );
+  }
+
+  try {
+    const result = await dispatch({ executorThreadId, targetThreadId, message });
+    return { ok: true, v: RELAY_PROTOCOL_VERSION, targetThreadId, executorThreadId, result: result ?? null };
+  } catch (err) {
+    return errorResponse(errorCode(err), err?.message ?? String(err));
+  }
+}
+
+/**
+ * Listens on a private local socket or Windows named pipe and answers one NDJSON line per request.
+*
+ * POSIX sockets are mode 0600 inside the Codex home directory. Windows uses the
+ * Claude-compatible local named-pipe namespace instead of a filesystem mode.
+ */
+export class RelaySocketServer {
+  constructor({
+    socketPath,
+    dispatch,
+    resolveExecutor = resolveRelayThreadId,
+    restrictSocket = (target) => {
+      if (!IS_WINDOWS) fs.chmodSync(target, 0o600);
+    },
+    log: logFn = () => {},
+  } = {}) {
+    this.socketPath = socketPath;
+    this.dispatch = dispatch;
+    this.resolveExecutor = resolveExecutor;
+    this.restrictSocket = restrictSocket;
+    this.log = logFn;
+    this.server = null;
+    this.started = false;
+  }
+
+  async start() {
+    if (this.started) return this.socketPath;
+    if (!IS_WINDOWS) fs.mkdirSync(path.dirname(this.socketPath), { recursive: true });
+
+    this.server = net.createServer((socket) => this.#handleConnection(socket));
+    await this.#listen({ replaceStale: true });
+
+    /**
+     * The file mode is the whole security boundary, so a socket whose mode
+     * could not be set is not a degraded relay - it is an open one. Refuse it
+     * and let the caller fall back to the app-server path, rather than serving
+     * thread writes on an address anyone can open.
+     */
+    try {
+      this.restrictSocket(this.socketPath);
+    } catch (err) {
+      try {
+        this.server.close();
+      } catch {}
+      throw new Error(`refusing to serve on ${this.socketPath}: its mode could not be restricted (${err.message})`);
+    }
+    this.started = true;
+
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.on(signal, () => {
+        this.stop();
+        process.exit(0);
+      });
+    }
+    process.on("exit", () => this.stop());
+
+    this.log(`relay socket listening on ${this.socketPath}`);
+    return this.socketPath;
+  }
+
+  /**
+   * A companion killed with SIGKILL leaves its socket file behind, and the next
+   * one then fails to bind a path nothing is listening on. Removing it blindly
+   * would be worse: Codex Desktop can launch more than one companion, and the
+   * second would silently steal the address from the first. So an in-use path
+   * is probed - a refused connection means the owner is gone and the file is
+   * swept, an accepted one means a live companion already has the socket and
+   * this process leaves it alone.
+   */
+  async #listen({ replaceStale }) {
+    try {
+      await new Promise((resolve, reject) => {
+        this.server.once("error", reject);
+        this.server.listen(this.socketPath, () => {
+          this.server.off("error", reject);
+          resolve();
+        });
+      });
+    } catch (err) {
+      if (err.code !== "EADDRINUSE" || !replaceStale) throw err;
+      if (IS_WINDOWS) {
+        if (await this.#socketIsLive()) {
+          throw new Error(`another native relay companion already owns ${this.socketPath}`);
+        }
+        await new Promise((resolve) => globalThis.setTimeout(resolve, 100));
+        return this.#listen({ replaceStale: false });
+      }
+      if (await this.#socketIsLive()) {
+        throw new Error(`another native relay companion already owns ${this.socketPath}`);
+      }
+      this.log(`removing the stale relay socket left at ${this.socketPath}`);
+      fs.rmSync(this.socketPath, { force: true });
+      await this.#listen({ replaceStale: false });
+    }
+  }
+
+  #socketIsLive() {
+    return new Promise((resolve) => {
+      const probe = net.connect({ path: this.socketPath });
+      const timer = globalThis.setTimeout(() => done(false), 1000);
+      const done = (answer) => {
+        globalThis.clearTimeout(timer);
+        probe.destroy();
+        resolve(answer);
+      };
+      probe.on("connect", () => done(true));
+      probe.on("error", () => done(false));
+    });
+  }
+
+  #handleConnection(socket) {
+    let buffer = "";
+    socket.on("error", (err) => this.log(`relay socket error: ${err.message}`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+        this.#reply(socket, errorResponse("RELAY_MESSAGE_TOO_LARGE", `a relay frame may not exceed ${MAX_FRAME_BYTES} bytes`));
+        socket.destroy();
+        return;
+      }
+      let index;
+      while ((index = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+        void this.#handleLine(socket, line);
+      }
+    });
+  }
+
+  async #handleLine(socket, line) {
+    let payload;
+    try {
+      payload = JSON.parse(line);
+    } catch (err) {
+      this.#reply(socket, errorResponse("RELAY_BAD_REQUEST", `malformed JSON: ${err.message}`));
+      return;
+    }
+    const response = await handleRelayRequest(payload, {
+      dispatch: this.dispatch,
+      resolveExecutor: this.resolveExecutor,
+    });
+    if (!response.ok) this.log(`relay refused ${payload?.targetThreadId ?? "?"}: ${response.error.message}`);
+    else this.log(`relayed a message into thread ${response.targetThreadId}`);
+    this.#reply(socket, response);
+  }
+
+  #reply(socket, response) {
+    if (socket.destroyed) return;
+    socket.write(`${JSON.stringify(response)}\n`);
+  }
+
+  stop() {
+    try {
+      this.server?.close();
+    } catch {}
+    try {
+      if (this.started && !IS_WINDOWS) fs.rmSync(this.socketPath, { force: true });
+    } catch {}
+    this.started = false;
+  }
+}
+
+/**
+ * `import.meta.main` is Node 24 and up, and this project supports Node 22, so
+ * the entry point is detected by comparing the resolved argv path instead.
+ */
+const invokedDirectly =
+  Boolean(process.argv[1]) && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) {
+  const mcp = new McpServer(
+    { name: "codex-native-relay", version: VERSION },
+    {
+      instructions:
+        "Companion process for the Codex Desktop native relay. It carries no work of its own: it accepts " +
+        "messages from claude-bridge on a private local socket and asks the Codex Desktop app-server that " +
+        "launched it to deliver them into an already-open thread, so that thread keeps its writer lock.",
+    },
+  );
+
+  /**
+   * The dispatch goes back over the very connection Codex Desktop opened to
+   * launch this process, which is what keeps the app the single writer. Sent as
+   * a plain JSON-RPC request rather than through a typed helper because the
+   * method is an internal of the app, not part of the MCP specification.
+   */
+  const dispatch = ({ executorThreadId, targetThreadId, message }) =>
+    mcp.server.request(
+      {
+        method: process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
+        params: nativeDispatchParams({ executorThreadId, targetThreadId, message }),
+      },
+      z.any(),
+    );
+
+  const relay = new RelaySocketServer({ socketPath: relaySocketPath(), dispatch, log });
+
+  mcp.registerTool(
+    "native_relay_status",
+    {
+      title: "Check the Codex Desktop native relay",
+      description:
+        "Report the local socket this companion listens on, the executor thread it dispatches through, and " +
+        "whether the relay is ready to deliver messages into threads Codex Desktop has open.",
+      inputSchema: {},
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      let executor = "(unconfigured)";
+      try {
+        const resolved = resolveRelayThreadId();
+        executor = `${resolved.threadId}  (from ${resolved.source})`;
+      } catch (err) {
+        executor = err.message;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
+              `companion:      codex-native-relay ${VERSION}`,
+              `relay socket:   ${relay.started ? relay.socketPath : `${relay.socketPath} (not listening)`}`,
+              `executor:       ${executor}`,
+              `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
+            ].join("\n"),
+          },
+        ],
+      };
+    },
+  );
+
+  /**
+   * Never let the socket take the MCP server down. Codex Desktop waits on the
+   * `initialize` handshake, so a process that dies before answering reads as a
+   * hang rather than an error - the same failure mode `claude-bridge` already
+   * guards its peer endpoint against.
+   */
+  try {
+    await relay.start();
+  } catch (err) {
+    log(`relay socket unavailable (${err.message}) - claude-bridge will fall back to the app-server path`);
+  }
+
+  await mcp.connect(new StdioServerTransport());
+  log(`ready on ${PLATFORM_LABEL} (${relay.started ? relay.socketPath : "socket down"})`);
+}

package/src/native-relay.mjs

@@ -0,0 +1,327 @@
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+
+import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir } from "./platform.mjs";
+
+/**
+ * The Codex Desktop app owns the per-thread writer lock of every thread it has
+ * open, and it keeps it for as long as the thread is open. Anything that wants
+ * to write into such a thread by attaching a second app-server loses: the
+ * app-server answers `thread <id> already has an active writer`. Closing the
+ * thread first is not an answer either, because the whole point of binding a
+ * thread is that the human keeps watching it in Codex Desktop.
+ *
+ * The way through is to stop bringing a second writer. A companion MCP process
+ * launched by Codex Desktop's own app-server already sits inside the app's
+ * context, so it can ask that app-server to deliver the message on the app's
+ * behalf. No resume, no attach, no second app-server, no lock to fight over.
+ *
+ * This module is the client half - the part `claude-bridge` talks to. The
+ * companion half lives in `native-relay-companion.mjs`.
+ */
+
+/**
+ * Measured, not documented. `codex_app.send_message_to_thread` is an internal
+ * of the Codex Desktop native tools pipe, on the same footing as the Claude
+ * peer protocol in `peer-protocol.mjs`: it works today and carries no public
+ * contract. When Codex changes it, this constant and `nativeDispatchParams`
+ * below are the two places to fix, and `CODEX_NATIVE_RELAY_METHOD` overrides
+ * the name without a release.
+ */
+export const NATIVE_DISPATCH_METHOD = "codex_app.send_message_to_thread";
+
+export const RELAY_PROTOCOL_VERSION = 1;
+
+/**
+ * A relay frame carries one chat message, so a megabyte-scale line is either a
+ * bug or something trying to make the companion buffer without limit. The cap
+ * is applied on both halves: the client refuses to send an oversized message,
+ * and the companion refuses to accumulate one.
+ */
+export const MAX_FRAME_BYTES = 128 * 1024;
+
+const DEFAULT_TIMEOUT_MS = 30000;
+const RELAY_SOCKET_NAME = "native-relay.sock";
+const WINDOWS_RELAY_SOCKET = "\\\\.\\pipe\\LOCAL\\codex-native-relay";
+const RELAY_CONFIG_NAME = "native-relay.json";
+
+export class NativeRelayError extends Error {
+  /**
+   * `reachedCompanion` is what decides whether falling back to the app-server
+   * path is worth doing. A companion that never answered says nothing about
+   * the target thread, so the older path deserves its turn; a companion that
+   * answered with a refusal has already asked Codex, and asking again through
+   * a second app-server only adds a writer-lock failure on top.
+   */
+  constructor(message, code, { reachedCompanion = false } = {}) {
+    super(message);
+    this.name = "NativeRelayError";
+    this.code = code;
+    this.reachedCompanion = reachedCompanion;
+  }
+}
+
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME ?? path.join(homeDir(), ".codex");
+}
+
+export function relaySocketPath(env = process.env) {
+  return env.CODEX_NATIVE_RELAY_SOCKET ?? (IS_WINDOWS ? WINDOWS_RELAY_SOCKET : path.join(codexHome(env), RELAY_SOCKET_NAME));
+}
+
+export function relayConfigPath(env = process.env) {
+  return path.join(codexHome(env), RELAY_CONFIG_NAME);
+}
+
+function isSocketFile(target) {
+  try {
+    return fs.statSync(target).isSocket();
+  } catch {
+    return false;
+  }
+}
+
+function isRelayEndpoint(target) {
+  if (IS_WINDOWS) {
+    return typeof target === "string" && target.toLowerCase().startsWith("\\\\.\\pipe\\") && fs.existsSync(target);
+  }
+  return isSocketFile(target);
+}
+
+export function readRelayConfig(env = process.env) {
+  const file = relayConfigPath(env);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `codex_app.send_message_to_thread` runs against an executor thread, which has
+ * to be a real Codex thread and is not the destination: a synthetic UUID is
+ * rejected with `NATIVE_DISPATCH_FAILED`, so the id cannot be invented at call
+ * time. A thread dedicated to the relay keeps that requirement off the
+ * destination thread, which stays open in Codex Desktop and untouched.
+ *
+ * The order is deliberate: an explicit `CODEX_RELAY_ID` wins so a single run
+ * can be pointed elsewhere without editing state, then the id bootstrapped
+ * once into `~/.codex/native-relay.json`, and then an error. Never a guess -
+ * an invented executor fails inside Codex with a message that says nothing
+ * about the missing configuration that actually caused it.
+ */
+export function resolveRelayThreadId(env = process.env) {
+  const explicit = env.CODEX_RELAY_ID?.trim();
+  if (explicit) return { threadId: explicit, source: "CODEX_RELAY_ID" };
+
+  const persisted = readRelayConfig(env)?.relayThreadId;
+  if (typeof persisted === "string" && persisted.trim()) {
+    return { threadId: persisted.trim(), source: relayConfigPath(env) };
+  }
+
+  throw new NativeRelayError(
+    `No Codex relay thread is configured. Set CODEX_RELAY_ID, or bootstrap one into ${relayConfigPath(env)} ` +
+      "with: node scripts/install-native-relay.mjs",
+    "RELAY_THREAD_UNCONFIGURED",
+  );
+}
+
+/**
+ * Builds the parameters of the native dispatch. Kept apart from the transport
+ * so the one shape this project cannot verify against a published schema sits
+ * in a single named function with a single test, rather than inline in the
+ * middle of a request.
+ */
+export function nativeDispatchParams({ executorThreadId, targetThreadId, message }) {
+  return { executorThreadId, threadId: targetThreadId, message };
+}
+
+/**
+ * Whether the native path is usable right now, and when it is not, why. The
+ * reason is carried rather than dropped because "the relay did nothing" is the
+ * one answer nobody can act on: a missing companion socket, an unsupported
+ * platform and an operator switching the backend off all look identical from
+ * the outside, and they need three different responses.
+ */
+export function nativeRelayStatus(env = process.env) {
+  const mode = (env.CODEX_BRIDGE_NATIVE_RELAY ?? "auto").toLowerCase();
+  const socketPath = relaySocketPath(env);
+
+  if (mode === "0" || mode === "off") {
+    return { enabled: false, mode, socketPath, reason: "disabled by CODEX_BRIDGE_NATIVE_RELAY=0" };
+  }
+  const forced = mode === "1" || mode === "on";
+  if (!IS_MACOS && !IS_WINDOWS && !forced) {
+    return {
+      enabled: false,
+      mode,
+      socketPath,
+      reason: `the Codex Desktop native relay is unavailable on ${PLATFORM_LABEL}`,
+    };
+  }
+  if (!isRelayEndpoint(socketPath)) {
+    return {
+      enabled: false,
+      mode,
+      socketPath,
+      reason: `no companion socket at ${socketPath} - is the native relay installed and Codex Desktop running?`,
+    };
+  }
+  return { enabled: true, mode, socketPath, reason: null };
+}
+
+/**
+ * Speaks one request per connection to the companion: a single NDJSON line out,
+ * a single NDJSON line back. Connections are not pooled - a relayed message is
+ * a rare event bounded by the bridge's own ping-pong guard, and a short-lived
+ * socket cannot go stale while Codex Desktop restarts underneath it.
+ */
+export class NativeDesktopRelay {
+  constructor({ env = process.env, socketPath = null, timeoutMs = DEFAULT_TIMEOUT_MS, log = () => {} } = {}) {
+    this.env = env;
+    this.explicitSocketPath = socketPath;
+    this.timeoutMs = timeoutMs;
+    this.log = log;
+  }
+
+  get socketPath() {
+    return this.explicitSocketPath ?? relaySocketPath(this.env);
+  }
+
+  status() {
+    if (!this.explicitSocketPath) return nativeRelayStatus(this.env);
+    const status = nativeRelayStatus({ ...this.env, CODEX_NATIVE_RELAY_SOCKET: this.explicitSocketPath });
+    return { ...status, socketPath: this.explicitSocketPath };
+  }
+
+  get available() {
+    return this.status().enabled;
+  }
+
+  async sendMessage(targetThreadId, message, { timeoutMs = this.timeoutMs } = {}) {
+    const request = { v: RELAY_PROTOCOL_VERSION, targetThreadId, message };
+    const line = `${JSON.stringify(request)}\n`;
+    if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
+      throw new NativeRelayError(
+        `Relay message is larger than ${MAX_FRAME_BYTES} bytes; shorten it before relaying.`,
+        "RELAY_MESSAGE_TOO_LARGE",
+      );
+    }
+
+    const response = await this.#roundTrip(line, timeoutMs);
+    if (response?.ok) return response;
+    throw new NativeRelayError(
+      response?.error?.message ?? "the Codex Desktop relay refused the message",
+      response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
+      { reachedCompanion: true },
+    );
+  }
+
+  #roundTrip(line, timeoutMs) {
+    const socketPath = this.socketPath;
+    return new Promise((resolve, reject) => {
+      let buffer = "";
+      let settled = false;
+      const socket = net.connect({ path: socketPath });
+
+      const finish = (fn, value) => {
+        if (settled) return;
+        settled = true;
+        globalThis.clearTimeout(timer);
+        socket.destroy();
+        fn(value);
+      };
+
+      const timer = globalThis.setTimeout(
+        () =>
+          finish(
+            reject,
+            new NativeRelayError(
+              `The Codex Desktop relay did not answer within ${timeoutMs}ms`,
+              "RELAY_TIMEOUT",
+              { reachedCompanion: true },
+            ),
+          ),
+        timeoutMs,
+      );
+
+      socket.on("connect", () => socket.write(line));
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+          finish(
+            reject,
+            new NativeRelayError("The Codex Desktop relay answered with an oversized frame", "RELAY_BAD_RESPONSE", {
+              reachedCompanion: true,
+            }),
+          );
+          return;
+        }
+        const index = buffer.indexOf("\n");
+        if (index < 0) return;
+        try {
+          finish(resolve, JSON.parse(buffer.slice(0, index)));
+        } catch (err) {
+          finish(
+            reject,
+            new NativeRelayError(
+              `The Codex Desktop relay answered with malformed JSON: ${err.message}`,
+              "RELAY_BAD_RESPONSE",
+              { reachedCompanion: true },
+            ),
+          );
+        }
+      });
+      socket.on("error", (err) =>
+        finish(
+          reject,
+          new NativeRelayError(`Cannot reach the Codex Desktop relay at ${socketPath}: ${err.message}`, "RELAY_UNREACHABLE"),
+        ),
+      );
+      socket.on("close", () =>
+        finish(
+          reject,
+          new NativeRelayError(
+            `The Codex Desktop relay at ${socketPath} closed before answering`,
+            "RELAY_UNREACHABLE",
+          ),
+        ),
+      );
+    });
+  }
+}
+
+/**
+ * Creates the dedicated executor thread once and remembers it, using the
+ * ordinary app-server path - which is allowed to take a writer lock here
+ * precisely because this thread belongs to nobody else. The caller stops the
+ * app-server afterwards, so the lock is released and Codex Desktop is left
+ * with the state to itself.
+ */
+export async function bootstrapRelayThread(client, { cwd = homeDir(), env = process.env, name = "Native Relay" } = {}) {
+  const res = await client.call("thread/start", {
+    cwd,
+    approvalPolicy: "never",
+    sandbox: "read-only",
+  });
+  const threadId = res?.thread?.id;
+  if (!threadId) throw new NativeRelayError("Codex app-server created no relay thread id", "RELAY_BOOTSTRAP_FAILED");
+
+  try {
+    await client.call("thread/name/set", { threadId, name });
+  } catch {
+    // A thread without a title still works as an executor context.
+  }
+
+  writeRelayConfig({ relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
+  return { threadId, configPath: relayConfigPath(env) };
+}
+
+export function writeRelayConfig(config, env = process.env) {
+  const file = relayConfigPath(env);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}