Improve codex remote-control CLI UX (#22878)

## Description

This PR makes `codex remote-control` behave like a foreground CLI
command by default. Running it now starts remote control, waits for
readiness, prints a clear status message with the machine name, and
stays alive until Ctrl-C.

Users who want daemon behavior can use `codex remote-control start`, and
`codex remote-control stop` now prints concise human-readable output.
`--json` remains available for scripts.

Implementation-wise, this now verifies the real app-server state instead
of just assuming startup worked. The CLI starts or connects to
app-server, probes its control socket, calls the `remoteControl/enable`
API, and waits for the remote-control status response/notification
before printing success.

For daemon mode, `codex remote-control start` also reports which managed
app-server binary was used, including its path and best-effort `codex
--version`, so failures are easier to diagnose.

## Examples

Example output:
```
> codex remote-control
Starting app-server with remote control enabled...
This machine is available for remote control as com-97826.
Press Ctrl-C to stop.
```

Error case using daemon (currently expected based on our publicly
released CLI version):
```
> ./target/debug/codex remote-control start
Starting app-server daemon with remote control enabled...
Error: app server did not become ready on /Users/owen/.codex/app-server-control/app-server-control.sock

Daemon used app-server:
  path: /Users/owen/.codex/packages/standalone/current/codex
  version: 0.130.0

Managed app-server stderr (/Users/owen/.codex/app-server-daemon/app-server.stderr.log):
  error: unexpected argument '--remote-control' found
  
  Usage: codex app-server [OPTIONS] [COMMAND]
  
  For more information, try '--help'.

Caused by:
    0: failed to connect to /Users/owen/.codex/app-server-control/app-server-control.sock
    1: No such file or directory (os error 2)
```

## What changed

- `codex remote-control` now runs remote control in the foreground and
prints a Ctrl-C stop hint.
- `codex remote-control start` starts the daemon and waits for remote
control readiness before reporting success.
- `codex remote-control stop` reports stopped/not-running status in
plain language.
- Startup failures now include recent managed app-server stderr to make
daemon issues easier to diagnose.
- Added coverage for CLI output, readiness waiting, foreground shutdown,
and stderr log tailing.
This commit is contained in:
Owen Lin authored and GitHub committed 2026-05-18 13:39:02 -07:00
1 parent 732b12b1ef
commit 1752f374a8
9 files changed
+1611 -158

No files matched your search

+205 -65
View File
@@ -1,6 +1,7 @@
mod backend;
mod client;
mod managed_install;
mod remote_control_client;
mod settings;
mod update_loop;
@@ -13,6 +14,7 @@ use anyhow::Result;
use anyhow::anyhow;
pub use backend::BackendKind;
use backend::BackendPaths;
use codex_app_server_protocol::RemoteControlConnectionStatus;
use codex_app_server_transport::app_server_control_socket_path;
use codex_utils_home_dir::find_codex_home;
use managed_install::managed_codex_bin;
@@ -58,6 +60,8 @@ pub struct LifecycleOutput {
pub backend: Option<BackendKind>,
#[serde(skip_serializing_if = "Option::is_none")]
pub pid: Option<u32>,
pub managed_codex_path: PathBuf,
pub managed_codex_version: Option<String>,
pub socket_path: PathBuf,
#[serde(skip_serializing_if = "Option::is_none")]
pub cli_version: Option<String>,
@@ -84,6 +88,7 @@ pub struct BootstrapOutput {
pub auto_update_enabled: bool,
pub remote_control_enabled: bool,
pub managed_codex_path: PathBuf,
pub managed_codex_version: Option<String>,
pub socket_path: PathBuf,
pub cli_version: String,
pub app_server_version: String,
@@ -96,6 +101,20 @@ pub enum RemoteControlStartOutput {
Start(LifecycleOutput),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RemoteControlReadyStatus {
pub status: RemoteControlConnectionStatus,
pub server_name: String,
pub environment_id: Option<String>,
pub timed_out: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RemoteControlReadyOutput {
pub daemon: RemoteControlStartOutput,
pub remote_control: RemoteControlReadyStatus,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RemoteControlMode {
Enabled,
@@ -179,6 +198,27 @@ pub async fn ensure_remote_control_started() -> Result<RemoteControlStartOutput>
.await
}
pub async fn ensure_remote_control_ready() -> Result<RemoteControlReadyOutput> {
ensure_supported_platform()?;
Daemon::from_environment()?
.ensure_remote_control_ready()
.await
}
pub async fn enable_remote_control_on_socket(
socket_path: &Path,
connect_timeout: Duration,
connect_retry_delay: Duration,
) -> Result<RemoteControlReadyStatus> {
ensure_supported_platform()?;
remote_control_client::enable_remote_control_with_connect_retry(
socket_path,
connect_timeout,
connect_retry_delay,
)
.await
}
pub async fn set_remote_control(mode: RemoteControlMode) -> Result<RemoteControlOutput> {
ensure_supported_platform()?;
Daemon::from_environment()?.set_remote_control(mode).await
@@ -248,33 +288,39 @@ impl Daemon {
async fn start(&self) -> Result<LifecycleOutput> {
let settings = self.load_settings().await?;
if let Ok(info) = client::probe(&self.socket_path).await {
return Ok(self.output(
LifecycleStatus::AlreadyRunning,
self.running_backend(&settings).await?,
/*pid*/ None,
Some(info.app_server_version),
));
return Ok(self
.output(
LifecycleStatus::AlreadyRunning,
self.running_backend(&settings).await?,
/*pid*/ None,
Some(info.app_server_version),
)
.await);
}
if self.running_backend_instance(&settings).await?.is_some() {
let info = self.wait_until_ready().await?;
return Ok(self.output(
LifecycleStatus::AlreadyRunning,
Some(BackendKind::Pid),
/*pid*/ None,
Some(info.app_server_version),
));
return Ok(self
.output(
LifecycleStatus::AlreadyRunning,
Some(BackendKind::Pid),
/*pid*/ None,
Some(info.app_server_version),
)
.await);
}
self.ensure_managed_codex_bin()?;
let pid = self.start_managed_backend(&settings).await?;
let info = self.wait_until_ready().await?;
Ok(self.output(
LifecycleStatus::Started,
Some(BackendKind::Pid),
pid,
Some(info.app_server_version),
))
Ok(self
.output(
LifecycleStatus::Started,
Some(BackendKind::Pid),
pid,
Some(info.app_server_version),
)
.await)
}
async fn restart(&self) -> Result<LifecycleOutput> {
@@ -294,12 +340,14 @@ impl Daemon {
let pid = self.start_managed_backend(&settings).await?;
let info = self.wait_until_ready().await?;
Ok(self.output(
LifecycleStatus::Restarted,
Some(BackendKind::Pid),
pid,
Some(info.app_server_version),
))
Ok(self
.output(
LifecycleStatus::Restarted,
Some(BackendKind::Pid),
pid,
Some(info.app_server_version),
)
.await)
}
#[cfg(unix)]
@@ -352,12 +400,14 @@ impl Daemon {
let settings = self.load_settings().await?;
if let Some(backend) = self.running_backend_instance(&settings).await? {
backend.stop().await?;
return Ok(self.output(
LifecycleStatus::Stopped,
Some(BackendKind::Pid),
/*pid*/ None,
/*app_server_version*/ None,
));
return Ok(self
.output(
LifecycleStatus::Stopped,
Some(BackendKind::Pid),
/*pid*/ None,
/*app_server_version*/ None,
)
.await);
}
if client::probe(&self.socket_path).await.is_ok() {
@@ -366,23 +416,27 @@ impl Daemon {
));
}
Ok(self.output(
LifecycleStatus::NotRunning,
/*backend*/ None,
/*pid*/ None,
/*app_server_version*/ None,
))
Ok(self
.output(
LifecycleStatus::NotRunning,
/*backend*/ None,
/*pid*/ None,
/*app_server_version*/ None,
)
.await)
}
async fn version(&self) -> Result<LifecycleOutput> {
let settings = self.load_settings().await?;
let info = client::probe(&self.socket_path).await?;
Ok(self.output(
LifecycleStatus::Running,
self.running_backend(&settings).await?,
/*pid*/ None,
Some(info.app_server_version),
))
Ok(self
.output(
LifecycleStatus::Running,
self.running_backend(&settings).await?,
/*pid*/ None,
Some(info.app_server_version),
)
.await)
}
async fn wait_until_ready(&self) -> Result<client::ProbeInfo> {
@@ -395,17 +449,34 @@ impl Daemon {
sleep(START_POLL_INTERVAL).await;
}
Err(err) => {
return Err(err).with_context(|| {
format!(
"app server did not become ready on {}",
self.socket_path.display()
)
});
let context = self.app_server_not_ready_context().await;
return Err(err).context(context);
}
}
}
}
async fn app_server_not_ready_context(&self) -> String {
let mut context = format!(
"app server did not become ready on {}",
self.socket_path.display()
);
self.append_daemon_app_server_context(&mut context).await;
backend::append_stderr_log_tail_context(&self.pid_file, &mut context).await;
context
}
async fn append_daemon_app_server_context(&self, context: &mut String) {
let managed_codex_version = self
.managed_codex_version_best_effort()
.await
.unwrap_or_else(|| "unknown".to_string());
context.push_str(&format!(
"\n\nDaemon used app-server:\n path: {}\n version: {managed_codex_version}",
self.managed_codex_bin.display()
));
}
async fn bootstrap(&self, options: BootstrapOptions) -> Result<BootstrapOutput> {
let _operation_lock = self.acquire_operation_lock().await?;
self.bootstrap_locked(options).await
@@ -430,6 +501,16 @@ impl Daemon {
Ok(RemoteControlStartOutput::Bootstrap(output))
}
async fn ensure_remote_control_ready(&self) -> Result<RemoteControlReadyOutput> {
let daemon = self.ensure_remote_control_started().await?;
let remote_control =
remote_control_client::enable_remote_control(&self.socket_path).await?;
Ok(RemoteControlReadyOutput {
daemon,
remote_control,
})
}
async fn set_remote_control(&self, mode: RemoteControlMode) -> Result<RemoteControlOutput> {
let _operation_lock = self.acquire_operation_lock().await?;
self.set_remote_control_locked(mode).await
@@ -512,12 +593,14 @@ impl Daemon {
updater.start().await?;
let info = self.wait_until_ready().await?;
let managed_codex_version = self.managed_codex_version_best_effort().await;
Ok(BootstrapOutput {
status: BootstrapStatus::Bootstrapped,
backend: BackendKind::Pid,
auto_update_enabled: true,
remote_control_enabled: settings.remote_control_enabled,
managed_codex_path: self.managed_codex_bin.clone(),
managed_codex_version,
socket_path: self.socket_path.clone(),
cli_version: env!("CARGO_PKG_VERSION").to_string(),
app_server_version: info.app_server_version,
@@ -577,6 +660,16 @@ impl Daemon {
))
}
#[cfg(unix)]
async fn managed_codex_version_best_effort(&self) -> Option<String> {
managed_codex_version(&self.managed_codex_bin).await.ok()
}
#[cfg(not(unix))]
async fn managed_codex_version_best_effort(&self) -> Option<String> {
None
}
fn backend_paths(&self, settings: &DaemonSettings) -> BackendPaths {
self.backend_paths_with_bin(settings, &self.managed_codex_bin)
}
@@ -636,17 +729,20 @@ impl Daemon {
})
}
fn output(
async fn output(
&self,
status: LifecycleStatus,
backend: Option<BackendKind>,
pid: Option<u32>,
app_server_version: Option<String>,
) -> LifecycleOutput {
let managed_codex_version = self.managed_codex_version_best_effort().await;
LifecycleOutput {
status,
backend,
pid,
managed_codex_path: self.managed_codex_bin.clone(),
managed_codex_version,
socket_path: self.socket_path.clone(),
cli_version: Some(env!("CARGO_PKG_VERSION").to_string()),
app_server_version,
@@ -735,10 +831,12 @@ fn try_lock_file(_file: &tokio::fs::File) -> Result<bool> {
#[cfg(all(test, unix))]
mod tests {
use pretty_assertions::assert_eq;
use tempfile::TempDir;
use super::BackendKind;
use super::BootstrapOutput;
use super::BootstrapStatus;
use super::Daemon;
use super::LifecycleOutput;
use super::LifecycleStatus;
use super::RemoteControlStartOutput;
@@ -751,22 +849,6 @@ mod tests {
use super::should_reexec_updater;
use crate::client::ProbeInfo;
#[test]
fn lifecycle_status_uses_camel_case_json() {
assert_eq!(
serde_json::to_string(&LifecycleStatus::AlreadyRunning).expect("serialize"),
"\"alreadyRunning\""
);
}
#[test]
fn bootstrap_status_uses_camel_case_json() {
assert_eq!(
serde_json::to_string(&BootstrapStatus::Bootstrapped).expect("serialize"),
"\"bootstrapped\""
);
}
#[test]
fn remote_control_status_uses_camel_case_json() {
assert_eq!(
@@ -847,12 +929,26 @@ mod tests {
status: LifecycleStatus::AlreadyRunning,
backend: Some(BackendKind::Pid),
pid: None,
managed_codex_path: "codex".into(),
managed_codex_version: Some("1.2.3".to_string()),
socket_path: "codex.sock".into(),
cli_version: Some("1.2.3".to_string()),
app_server_version: Some("1.2.4".to_string()),
};
let output = RemoteControlStartOutput::Start(lifecycle_output.clone());
assert_eq!(
serde_json::to_value(&lifecycle_output).expect("serialize"),
serde_json::json!({
"status": "alreadyRunning",
"backend": "pid",
"managedCodexPath": "codex",
"managedCodexVersion": "1.2.3",
"socketPath": "codex.sock",
"cliVersion": "1.2.3",
"appServerVersion": "1.2.4",
})
);
assert_eq!(
serde_json::to_value(output).expect("serialize"),
serde_json::to_value(lifecycle_output).expect("serialize")
@@ -864,15 +960,59 @@ mod tests {
auto_update_enabled: true,
remote_control_enabled: true,
managed_codex_path: "codex".into(),
managed_codex_version: Some("1.2.3".to_string()),
socket_path: "codex.sock".into(),
cli_version: "1.2.3".to_string(),
app_server_version: "1.2.4".to_string(),
};
let output = RemoteControlStartOutput::Bootstrap(bootstrap_output.clone());
assert_eq!(
serde_json::to_value(&bootstrap_output).expect("serialize"),
serde_json::json!({
"status": "bootstrapped",
"backend": "pid",
"autoUpdateEnabled": true,
"remoteControlEnabled": true,
"managedCodexPath": "codex",
"managedCodexVersion": "1.2.3",
"socketPath": "codex.sock",
"cliVersion": "1.2.3",
"appServerVersion": "1.2.4",
})
);
assert_eq!(
serde_json::to_value(output).expect("serialize"),
serde_json::to_value(bootstrap_output).expect("serialize")
);
}
#[tokio::test]
async fn not_ready_context_reports_daemon_app_server_before_stderr() {
let temp_dir = TempDir::new().expect("temp dir");
let daemon = Daemon {
socket_path: temp_dir.path().join("app-server-control.sock"),
pid_file: temp_dir.path().join("app-server.pid"),
update_pid_file: temp_dir.path().join("app-server-updater.pid"),
operation_lock_file: temp_dir.path().join("daemon.lock"),
settings_file: temp_dir.path().join("settings.json"),
managed_codex_bin: temp_dir.path().join("missing-codex"),
};
let stderr_log = daemon.pid_file.with_extension("stderr.log");
tokio::fs::write(&stderr_log, "unexpected argument")
.await
.expect("write stderr log");
assert_eq!(
daemon.app_server_not_ready_context().await,
format!(
"app server did not become ready on {}\n\n\
Daemon used app-server:\n path: {}\n version: unknown\n\n\
Managed app-server stderr ({}):\n unexpected argument",
daemon.socket_path.display(),
daemon.managed_codex_bin.display(),
stderr_log.display()
)
);
}
}