feat: add one off commands to app-server v2 (#7452)

codex-rs/app-server-protocol/src/protocol/common.rs

@@ -164,6 +164,12 @@ client_request_definitions! {
         response: v2::FeedbackUploadResponse,
     },
 
+    /// Execute a command (argv vector) under the server's sandbox.
+    OneOffCommandExec => "command/exec" {
+        params: v2::CommandExecParams,
+        response: v2::CommandExecResponse,
+    },
+
     ConfigRead => "config/read" {
         params: v2::ConfigReadParams,
         response: v2::ConfigReadResponse,

codex-rs/app-server-protocol/src/protocol/mappers.rs

@@ -0,0 +1,13 @@
+use crate::protocol::v1;
+use crate::protocol::v2;
+
+impl From<v1::ExecOneOffCommandParams> for v2::CommandExecParams {
+    fn from(value: v1::ExecOneOffCommandParams) -> Self {
+        Self {
+            command: value.command,
+            timeout_ms: value.timeout_ms,
+            cwd: value.cwd,
+            sandbox_policy: value.sandbox_policy.map(std::convert::Into::into),
+        }
+    }
+}

codex-rs/app-server-protocol/src/protocol/mod.rs

@@ -2,6 +2,7 @@
 // Exposes protocol pieces used by `lib.rs` via `pub use protocol::common::*;`.
 
 pub mod common;
+mod mappers;
 pub mod thread_history;
 pub mod v1;
 pub mod v2;

codex-rs/app-server-protocol/src/protocol/v2.rs

@@ -632,6 +632,25 @@ pub struct FeedbackUploadResponse {
     pub thread_id: String,
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct CommandExecParams {
+    pub command: Vec<String>,
+    pub timeout_ms: Option<u64>,
+    pub cwd: Option<PathBuf>,
+    pub sandbox_policy: Option<SandboxPolicy>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct CommandExecResponse {
+    pub exit_code: i32,
+    pub stdout: String,
+    pub stderr: String,
+}
+
 // === Threads, Turns, and Items ===
 // Thread APIs
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema, TS)]

codex-rs/app-server/README.md

@@ -66,6 +66,7 @@ The JSON-RPC API exposes dedicated methods for managing Codex conversations. Thr
 - `turn/start` — add user input to a thread and begin Codex generation; responds with the initial `turn` object and streams `turn/started`, `item/*`, and `turn/completed` notifications.
 - `turn/interrupt` — request cancellation of an in-flight turn by `(thread_id, turn_id)`; success is an empty `{}` response and the turn finishes with `status: "interrupted"`.
 - `review/start` — kick off Codex’s automated reviewer for a thread; responds like `turn/start` and emits `item/started`/`item/completed` notifications with `enteredReviewMode` and `exitedReviewMode` items, plus a final assistant `agentMessage` containing the review.
+- `command/exec` — run a single command under the server sandbox without starting a thread/turn (handy for utilities and validation).
 
 ### 1) Start or resume a thread
 
@@ -241,6 +242,25 @@ containing an `exitedReviewMode` item with the final review text:
 
 The `review` string is plain text that already bundles the overall explanation plus a bullet list for each structured finding (matching `ThreadItem::ExitedReviewMode` in the generated schema). Use this notification to render the reviewer output in your client.
 
+### 7) One-off command execution
+
+Run a standalone command (argv vector) in the server’s sandbox without creating a thread or turn:
+
+```json
+{ "method": "command/exec", "id": 32, "params": {
+    "command": ["ls", "-la"],
+    "cwd": "/Users/me/project",                    // optional; defaults to server cwd
+    "sandboxPolicy": { "type": "workspaceWrite" }, // optional; defaults to user config
+    "timeoutMs": 10000                             // optional; ms timeout; defaults to server timeout
+} }
+{ "id": 32, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }
+```
+
+Notes:
+- Empty `command` arrays are rejected.
+- `sandboxPolicy` accepts the same shape used by `turn/start` (e.g., `dangerFullAccess`, `readOnly`, `workspaceWrite` with flags).
+- When omitted, `timeoutMs` falls back to the server default.
+
 ## Events (work-in-progress)
 
 Event notifications are the server-initiated event stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading stdout for `thread/started`, `turn/*`, and `item/*` notifications.

codex-rs/app-server/src/codex_message_processor.rs

@@ -21,9 +21,9 @@ use codex_app_server_protocol::CancelLoginAccountParams;
 use codex_app_server_protocol::CancelLoginAccountResponse;
 use codex_app_server_protocol::CancelLoginChatGptResponse;
 use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::CommandExecParams;
 use codex_app_server_protocol::ConversationGitInfo;
 use codex_app_server_protocol::ConversationSummary;
-use codex_app_server_protocol::ExecOneOffCommandParams;
 use codex_app_server_protocol::ExecOneOffCommandResponse;
 use codex_app_server_protocol::FeedbackUploadParams;
 use codex_app_server_protocol::FeedbackUploadResponse;
@@ -447,9 +447,12 @@ impl CodexMessageProcessor {
             ClientRequest::FuzzyFileSearch { request_id, params } => {
                 self.fuzzy_file_search(request_id, params).await;
             }
-            ClientRequest::ExecOneOffCommand { request_id, params } => {
+            ClientRequest::OneOffCommandExec { request_id, params } => {
                 self.exec_one_off_command(request_id, params).await;
             }
+            ClientRequest::ExecOneOffCommand { request_id, params } => {
+                self.exec_one_off_command(request_id, params.into()).await;
+            }
             ClientRequest::ConfigRead { .. }
             | ClientRequest::ConfigValueWrite { .. }
             | ClientRequest::ConfigBatchWrite { .. } => {
@@ -1134,7 +1137,7 @@ impl CodexMessageProcessor {
         }
     }
 
-    async fn exec_one_off_command(&self, request_id: RequestId, params: ExecOneOffCommandParams) {
+    async fn exec_one_off_command(&self, request_id: RequestId, params: CommandExecParams) {
         tracing::debug!("ExecOneOffCommand params: {params:?}");
 
         if params.command.is_empty() {
@@ -1162,6 +1165,7 @@ impl CodexMessageProcessor {
 
         let effective_policy = params
             .sandbox_policy
+            .map(|policy| policy.to_core())
             .unwrap_or_else(|| self.config.sandbox_policy.clone());
 
         let codex_linux_sandbox_exe = self.config.codex_linux_sandbox_exe.clone();