codex-relay 1.3.1 → 1.3.2

package/README.md

@@ -28,6 +28,26 @@ npx codex-relay@latest approve XXXX-XXXX
 
 After approval, the phone can list Codex threads, start new work, stream messages, and handle approval prompts from the local Codex runtime.
 
+## Shared Terminal and Mobile Sessions
+
+By default, Codex Relay starts a private app-server process. A terminal TUI that was started separately can resume the same saved thread, but it does not receive the relay process's live events.
+
+On macOS, Linux, or WSL, opt in to Codex's shared app-server socket:
+
+```sh
+npx codex-relay@latest --shared-app-server
+```
+
+Then connect a new terminal TUI to the shared app-server socket:
+
+```sh
+codex resume --remote unix://
+```
+
+Pass a thread ID after `unix://` to open a specific thread. The relay prints the attach command at startup. Mobile and the connected terminal can then observe the same live sessions through one socket-backed app-server. An already-running standalone TUI cannot be converted in place; exit it and reconnect with `--remote`.
+
+Shared mode requires a recent Codex CLI with Unix-socket app-server and `resume --remote` support. If those features are unavailable, update Codex or omit `--shared-app-server` to keep the existing private mode. Native Windows is not currently supported; use WSL or private mode there.
+
 ## Background Mode
 
 To keep the relay running after the command returns:
@@ -69,6 +89,12 @@ npx codex-relay@latest --bg
 
 Start the relay in the background.
 
+```sh
+npx codex-relay@latest --shared-app-server
+```
+
+Start the relay through Codex's shared app-server socket.
+
 ```sh
 npx codex-relay@latest qr
 ```
@@ -99,6 +125,7 @@ The relay listens on `0.0.0.0:8787` by default. Configure it with environment va
 | `CODEX_RELAY_AUTH_DB_PATH`             | Pairing and session database path. Defaults to `.codex-relay/auth.db`.                             |
 | `CODEX_RELAY_APPROVAL_SECRET`          | Secret used by the local approve command. Usually generated automatically.                         |
 | `CODEX_RELAY_DANGEROUSLY_AUTO_APPROVE` | Set to `1` to auto-approve mobile pairing requests. Prefer the CLI flag for local use.             |
+| `CODEX_RELAY_APP_SERVER_MODE`          | Set to `socket` for shared terminal/mobile sessions. Defaults to `stdio`.                          |
 | `CODEX_HOME`                           | Codex home directory, used when reading Codex session metadata.                                    |
 | `CODEX_BIN`                            | Codex CLI executable path.                                                                         |
 

package/dist/cli.js

@@ -48,16 +48,18 @@ function isRelayProcessCommand(command) {
 //#endregion
 //#region src/cli.ts
 const npxCommand = "npx codex-relay@latest";
-const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").option("--debug", "write verbose relay diagnostics to debug.log").option("--dangerously-auto-approve", "automatically approve mobile pairing requests without a local approval command").addHelpText("after", `
+const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").option("--debug", "write verbose relay diagnostics to debug.log").option("--shared-app-server", "use a shared Codex app-server socket so terminal and mobile can share live sessions").option("--dangerously-auto-approve", "automatically approve mobile pairing requests without a local approval command").addHelpText("after", `
 
 Examples:
   ${npxCommand}              Start the relay and print a pairing QR
+  ${npxCommand} --shared-app-server Share live sessions with a connected terminal
   ${npxCommand} --bg         Start the relay in the background
   ${npxCommand} qr           Print the current pairing QR
   ${npxCommand} clear        Sign out every paired mobile app
   ${npxCommand} approve CODE Approve a pending mobile pairing request`).action(async (options) => {
 	if (options.debug) process.env.CODEX_RELAY_DEBUG = "1";
 	if (options.dangerouslyAutoApprove) process.env.CODEX_RELAY_DANGEROUSLY_AUTO_APPROVE = "1";
+	if (options.sharedAppServer) process.env.CODEX_RELAY_APP_SERVER_MODE = "socket";
 	if (options.bg) {
 		await startBackgroundServer();
 		return;

package/dist/src.js

@@ -6,6 +6,7 @@ import { execFile, spawn } from "node:child_process";
 import fs, { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { access, appendFile, copyFile, mkdir, open, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
 import path, { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { promisify } from "node:util";
@@ -19,6 +20,7 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import * as pty from "@lydell/node-pty";
 import { createInterface } from "node:readline";
+import WebSocket from "ws";
 import { Codex } from "@openai/codex-sdk";
 import { gcm } from "@noble/ciphers/aes.js";
 import { randomBytes as randomBytes$1, utf8ToBytes } from "@noble/ciphers/utils.js";
@@ -26,23 +28,49 @@ import { ed25519, x25519 } from "@noble/curves/ed25519.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 //#region src/codex-binary.ts
-const appServerArgs = [
+const stdioAppServerArgs = [
 	"app-server",
 	"--listen",
 	"stdio://"
 ];
+const sharedServerArgs = [
+	"app-server",
+	"--listen",
+	"unix://"
+];
 const windowsShellExtensions = new Set([".bat", ".cmd"]);
+function resolveCodexAppServerMode(env = process.env) {
+	const configuredMode = env.CODEX_RELAY_APP_SERVER_MODE?.trim().toLowerCase();
+	if (!configuredMode || configuredMode === "stdio") return "stdio";
+	if (configuredMode === "socket") return "socket";
+	throw new Error(`Unsupported CODEX_RELAY_APP_SERVER_MODE ${JSON.stringify(configuredMode)}. Expected "stdio" or "socket".`);
+}
 function resolveCodexAppServerSpawn(input = {}) {
 	const platform$1 = input.platform ?? platform();
 	const command = resolveCodexBinary(input.env ?? process.env);
 	const isWindows = platform$1 === "win32";
 	return {
 		command,
-		args: [...appServerArgs],
+		args: [...stdioAppServerArgs],
 		shell: isWindows && shouldUseWindowsShell(command),
 		windowsHide: isWindows
 	};
 }
+function resolveCodexSharedAppServerSpawn(input = {}) {
+	const platform$2 = input.platform ?? platform();
+	assertAppServerModeSupported("socket", platform$2);
+	const command = resolveCodexBinary(input.env ?? process.env);
+	const isWindows = platform$2 === "win32";
+	return {
+		command,
+		args: [...sharedServerArgs],
+		shell: isWindows && shouldUseWindowsShell(command),
+		windowsHide: isWindows
+	};
+}
+function assertAppServerModeSupported(mode, platform) {
+	if (mode === "socket" && platform === "win32") throw new Error("Shared Codex app-server mode requires macOS, Linux, or WSL.");
+}
 function resolveCodexBinary(env) {
 	return env.CODEX_BIN?.trim() || "codex";
 }
@@ -60,6 +88,11 @@ var CodexAppServerClient = class {
 	pending = /* @__PURE__ */ new Map();
 	requestHandlers = /* @__PURE__ */ new Set();
 	readline;
+	sharedServer;
+	socket;
+	initialize() {
+		return this.ensureInitialized();
+	}
 	async listThreads(limit = 80) {
 		return (await this.request("thread/list", {
 			limit,
@@ -136,8 +169,12 @@ var CodexAppServerClient = class {
 		this.pending.clear();
 		this.readline?.close();
 		this.child?.kill();
+		this.socket?.close();
+		this.sharedServer?.kill();
 		this.readline = void 0;
 		this.child = void 0;
+		this.socket = void 0;
+		this.sharedServer = void 0;
 		this.initialized = void 0;
 	}
 	async request(method, params) {
@@ -150,15 +187,12 @@ var CodexAppServerClient = class {
 				resolve: (value) => resolve(value),
 				reject
 			});
-			this.child.stdin.write(`${JSON.stringify({
+			this.writeJson({
 				id,
 				method,
 				params
-			})}\n`, (error) => {
-				if (error) {
-					this.pending.delete(id);
-					reject(error);
-				}
+			}).catch((error) => {
+				if (this.pending.delete(id)) reject(error);
 			});
 		});
 	}
@@ -166,7 +200,33 @@ var CodexAppServerClient = class {
 		if (!this.initialized) this.initialized = this.start();
 		return this.initialized;
 	}
-	start() {
+	async start() {
+		try {
+			if (resolveCodexAppServerMode() === "socket") {
+				this.sharedServer = await startSharedCodexAppServer();
+				await this.connectSharedCodexAppServer();
+			} else this.startStdioCodexAppServer();
+			await this.requestRaw("initialize", {
+				clientInfo: {
+					name: "codex-relay",
+					title: "Codex Relay Mobile Server",
+					version: "1.2.0"
+				},
+				capabilities: { experimentalApi: true }
+			});
+		} catch (error) {
+			this.readline?.close();
+			this.readline = void 0;
+			this.child?.kill();
+			this.child = void 0;
+			this.socket?.close();
+			this.socket = void 0;
+			this.sharedServer?.kill();
+			this.sharedServer = void 0;
+			throw error;
+		}
+	}
+	startStdioCodexAppServer() {
 		const spawnConfig = resolveCodexAppServerSpawn();
 		this.child = spawn(spawnConfig.command, spawnConfig.args, {
 			env: process.env,
@@ -187,14 +247,31 @@ var CodexAppServerClient = class {
 			this.child = void 0;
 			this.initialized = void 0;
 		});
-		return this.requestRaw("initialize", {
-			clientInfo: {
-				name: "codex-relay",
-				title: "Codex Relay Mobile Server",
-				version: "1.2.0"
-			},
-			capabilities: { experimentalApi: true }
-		}).then(() => void 0);
+	}
+	async connectSharedCodexAppServer() {
+		const socket = new WebSocket(`ws+unix://${sharedCodexAppServerSocketPath()}:/`, { perMessageDeflate: false });
+		this.socket = socket;
+		await new Promise((resolve, reject) => {
+			const handleOpen = () => {
+				socket.off("error", handleInitialError);
+				resolve();
+			};
+			const handleInitialError = (error) => {
+				socket.off("open", handleOpen);
+				reject(error);
+			};
+			socket.once("open", handleOpen);
+			socket.once("error", handleInitialError);
+		});
+		socket.on("message", (data) => this.handleLine(String(data)));
+		socket.on("error", (error) => this.rejectAll(error));
+		socket.once("close", (code, reason) => {
+			this.rejectAll(/* @__PURE__ */ new Error(`Codex app-server socket closed with ${code}${reason.length > 0 ? `: ${String(reason)}` : "."}`));
+			this.socket = void 0;
+			this.sharedServer?.kill();
+			this.sharedServer = void 0;
+			this.initialized = void 0;
+		});
 	}
 	requestRaw(method, params) {
 		const id = this.nextId++;
@@ -210,11 +287,8 @@ var CodexAppServerClient = class {
 				resolve: (value) => resolve(value),
 				reject
 			});
-			this.child.stdin.write(`${request}\n`, (error) => {
-				if (error) {
-					this.pending.delete(id);
-					reject(error);
-				}
+			this.writeSerializedJson(request).catch((error) => {
+				if (this.pending.delete(id)) reject(error);
 			});
 		});
 	}
@@ -256,12 +330,22 @@ var CodexAppServerClient = class {
 		} else pending.resolve(message.result);
 	}
 	writeJson(payload) {
+		return this.writeSerializedJson(JSON.stringify(payload));
+	}
+	writeSerializedJson(payload) {
 		return new Promise((resolve, reject) => {
+			if (this.socket) {
+				this.socket.send(payload, (error) => {
+					if (error) reject(error);
+					else resolve();
+				});
+				return;
+			}
 			if (!this.child?.stdin) {
 				reject(/* @__PURE__ */ new Error("Codex app-server is not running."));
 				return;
 			}
-			this.child.stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+			this.child.stdin.write(`${payload}\n`, (error) => {
 				if (error) reject(error);
 				else resolve();
 			});
@@ -272,6 +356,46 @@ var CodexAppServerClient = class {
 		this.pending.clear();
 	}
 };
+async function startSharedCodexAppServer() {
+	const spawnConfig = resolveCodexSharedAppServerSpawn();
+	const child = spawn(spawnConfig.command, spawnConfig.args, {
+		env: process.env,
+		shell: spawnConfig.shell,
+		windowsHide: spawnConfig.windowsHide
+	});
+	let spawnError;
+	let exitReason;
+	let stderr = "";
+	child.stdout.resume();
+	child.stderr.on("data", (chunk) => {
+		if (stderr.length < 8192) stderr += String(chunk).slice(0, 8192 - stderr.length);
+	});
+	child.once("error", (error) => {
+		spawnError = error;
+	});
+	child.once("exit", (code, signal) => {
+		exitReason = signal ?? code ?? 1;
+	});
+	const socketPath = sharedCodexAppServerSocketPath();
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		if (spawnError) throw new Error(`Failed to start the shared Codex app-server: ${spawnError.message}`);
+		try {
+			await access(socketPath);
+			return child;
+		} catch {
+			if (exitReason !== void 0) {
+				const detail = stderr.trim();
+				throw new Error(`Failed to start the shared Codex app-server (exit ${exitReason})${detail ? `: ${detail}` : "."}`);
+			}
+			await setTimeout$1(25);
+		}
+	}
+	child.kill();
+	throw new Error(`Timed out waiting for the shared Codex app-server socket at ${socketPath}.`);
+}
+function sharedCodexAppServerSocketPath() {
+	return join(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "app-server-control", "app-server-control.sock");
+}
 function debugAppServer(kind, method, id, detail) {
 	if (process.env.CODEX_RELAY_DEBUG_APP_SERVER !== "1") return;
 	console.log(`[app-server] ${kind}${id === void 0 ? "" : ` #${id}`}${method ? ` ${method}` : ""}${detail ? ` ${detail}` : ""}`);
@@ -6274,8 +6398,17 @@ const color = {
 const npxCommand = "npx codex-relay@latest";
 const sessionStore = await createTursoPairingSessionStore(process.env.CODEX_RELAY_AUTH_DB_PATH ?? await prepareCodexRelayDataPath("auth.db", ["auth.db-shm", "auth.db-wal"]));
 const preferencesStore = createFileRuntimePreferencesStore(process.env.CODEX_RELAY_PREFERENCES_PATH ?? await prepareCodexRelayDataPath("preferences.json"));
+const appServerMode = resolveCodexAppServerMode();
+const sharedAppServer = appServerMode === "socket" ? new CodexAppServerClient() : void 0;
+if (sharedAppServer) {
+	await sharedAppServer.initialize();
+	process.once("SIGINT", () => stopSharedAppServer(130));
+	process.once("SIGTERM", () => stopSharedAppServer(143));
+	process.once("exit", () => sharedAppServer.close());
+}
 serve({
 	fetch: createApp({
+		appServer: sharedAppServer,
 		pairing: {
 			approvalSecret,
 			dangerouslyAutoApprove,
@@ -6346,9 +6479,14 @@ serve({
 		dangerouslyAutoApprove,
 		listenUrl,
 		pairingPayload,
-		port: info.port
+		port: info.port,
+		sharedAppServer: appServerMode === "socket"
 	}));
 });
+function stopSharedAppServer(exitCode) {
+	sharedAppServer?.close();
+	process.exit(exitCode);
+}
 function formatStartupInstructions(details) {
 	return [
 		"",
@@ -6361,6 +6499,11 @@ function formatStartupInstructions(details) {
 			`${color.prompt("›")} Server: ${color.muted(details.listenUrl)}`,
 			"",
 			`${color.prompt("›")} Pairing: ${color.url(details.pairingPayload)}`,
+			...details.sharedAppServer ? [
+				"",
+				`${color.prompt("›")} Terminal: ${color.command("codex resume --remote unix://")}`,
+				`  ${color.muted("Connect through the shared Codex app-server to follow and steer the same live sessions.")}`
+			] : [],
 			"",
 			`${color.prompt("›")} Commands`,
 			`  ${color.command(npxCommand)}              Start and print a pairing QR`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-relay",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Local Codex Relay CLI bridge for the Codex Relay mobile app.",
   "license": "Apache-2.0",
   "repository": {
@@ -41,7 +41,7 @@
     "@noble/ciphers": "2.2.0",
     "@noble/curves": "2.2.0",
     "@noble/hashes": "2.2.0",
-    "@openai/codex-sdk": "0.144.1",
+    "@openai/codex-sdk": "0.144.5",
     "base64-js": "1.5.1",
     "commander": "^14.0.3",
     "es-git": "^0.6.0",