app-server: use permission ids and runtime workspace roots (#22611)

## Why This PR builds on [#22610](https://github.com/openai/codex/pull/22610) and is the app-server side of the migration from mutable per-turn `SandboxPolicy` replacement toward selecting immutable permission profiles by id plus mutable runtime workspace roots. Once permission profiles can carry their own immutable `workspace_roots`, app-server no longer needs to mutate the selected `PermissionProfile` just to represent thread-specific filesystem context. The mutable part now lives on the thread as explicit `runtimeWorkspaceRoots`, while `:workspace_roots` remains symbolic until the sandbox is realized for a turn. ## What Changed - Replaced the v2 permission-selection wrapper surface with plain profile ids for `thread/start`, `thread/resume`, `thread/fork`, and `turn/start`. - Removed the API surface for profile modifications (`PermissionProfileSelectionParams`, `PermissionProfileModificationParams`, `ActivePermissionProfileModification`). - Added experimental `runtimeWorkspaceRoots` fields to the thread lifecycle and turn-start APIs. - Threaded runtime workspace roots through core session/thread snapshots, turn overrides, app-server request handling, and command execution permission resolution. - Kept session permission state symbolic so later runtime root updates and cwd-only implicit-root retargeting rebind `:workspace_roots` correctly. - Updated the embedded clients just enough to send and restore the new thread state. - Refreshed the generated schema/TypeScript artifacts and the app-server README to match the new contract. ## Verification Targeted coverage for this layer lives in: - `codex-rs/app-server-protocol/src/protocol/v2/tests.rs` - `codex-rs/app-server/tests/suite/v2/thread_start.rs` - `codex-rs/app-server/tests/suite/v2/thread_resume.rs` - `codex-rs/app-server/tests/suite/v2/turn_start.rs` - `codex-rs/core/src/session/tests.rs` The key regression checks exercise that: - `runtimeWorkspaceRoots` resolve against the effective cwd on thread start. - Profile-declared workspace roots are excluded from the runtime workspace roots returned by app-server. - A turn-level runtime workspace-root update persists onto the thread and is returned by `thread/resume`. - A named permission profile selected on one turn remains symbolic so a later runtime-root-only turn update changes the actual sandbox writes. - A cwd-only turn update retargets the implicit runtime cwd root while preserving additional runtime roots. - The protocol fixtures and generated client artifacts stay in sync with the string-based permission selection contract. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22611). * #22612 * __->__ #22611
2026-07-01 00:31:56 +08:00 · 2026-05-14 23:00:05 -07:00
parent e6a7368810
commit 8a5306ff88
58 changed files with 1167 additions and 676 deletions
@@ -614,6 +614,7 @@ async fn skills_changed_notification_is_emitted_after_skill_change() -> Result<(
            model_provider: None,
            service_tier: None,
            cwd: None,
+            runtime_workspace_roots: None,
            approval_policy: None,
            approvals_reviewer: None,
            sandbox: None,
@@ -184,6 +184,79 @@ async fn thread_resume_rejects_unmaterialized_thread() -> Result<()> {
    Ok(())
 }

+#[tokio::test]
+async fn turn_start_updates_runtime_workspace_roots_for_loaded_thread() -> Result<()> {
+    let server = create_mock_responses_server_repeating_assistant("Done").await;
+    let codex_home = TempDir::new()?;
+    create_config_toml(codex_home.path(), &server.uri())?;
+
+    let extra_root_tmp = TempDir::new()?;
+    let extra_root = extra_root_tmp.path().join("extra-root");
+    std::fs::create_dir_all(&extra_root)?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let start_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            model: Some("gpt-5.4".to_string()),
+            ..Default::default()
+        })
+        .await?;
+    let start_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(start_resp)?;
+
+    let turn_id = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            input: vec![UserInput::Text {
+                text: "Hello".to_string(),
+                text_elements: Vec::new(),
+            }],
+            runtime_workspace_roots: Some(vec![extra_root.clone(), extra_root.join(".")]),
+            ..Default::default()
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(turn_id)),
+    )
+    .await??;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let resume_id = mcp
+        .send_thread_resume_request(ThreadResumeParams {
+            thread_id: thread.id,
+            exclude_turns: true,
+            ..Default::default()
+        })
+        .await?;
+    let resume_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(resume_id)),
+    )
+    .await??;
+    let ThreadResumeResponse {
+        runtime_workspace_roots,
+        ..
+    } = to_response::<ThreadResumeResponse>(resume_resp)?;
+
+    assert_eq!(
+        runtime_workspace_roots,
+        vec![AbsolutePathBuf::from_absolute_path(extra_root)?]
+    );
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn thread_goal_get_rejects_unmaterialized_thread() -> Result<()> {
    let server = create_mock_responses_server_repeating_assistant("Done").await;
@@ -236,6 +236,89 @@ async fn thread_start_creates_thread_and_emits_started() -> Result<()> {
    Ok(())
 }

+#[tokio::test]
+async fn thread_start_resolves_runtime_workspace_roots_against_cwd() -> Result<()> {
+    let server = create_mock_responses_server_repeating_assistant("Done").await;
+    let codex_home = TempDir::new()?;
+    create_config_toml_without_approval_policy(codex_home.path(), &server.uri())?;
+
+    let cwd_tmp = TempDir::new()?;
+    let cwd = cwd_tmp.path().to_path_buf();
+    let relative_root = PathBuf::from("extra-root");
+    std::fs::create_dir_all(cwd.join(&relative_root))?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let req_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            cwd: Some(cwd.to_string_lossy().to_string()),
+            runtime_workspace_roots: Some(vec![relative_root.clone()]),
+            ..Default::default()
+        })
+        .await?;
+
+    let resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(req_id)),
+    )
+    .await??;
+    let ThreadStartResponse {
+        cwd: response_cwd,
+        runtime_workspace_roots,
+        ..
+    } = to_response::<ThreadStartResponse>(resp)?;
+
+    assert_eq!(response_cwd, cwd.abs());
+    assert_eq!(
+        runtime_workspace_roots,
+        vec![cwd_tmp.path().join(relative_root).abs()]
+    );
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn thread_start_excludes_profile_workspace_roots_from_runtime_workspace_roots() -> Result<()>
+{
+    let server = create_mock_responses_server_repeating_assistant("Done").await;
+    let codex_home = TempDir::new()?;
+    let cwd = TempDir::new()?;
+    let profile_root = TempDir::new()?;
+    create_config_toml_with_profile_workspace_root(
+        codex_home.path(),
+        &server.uri(),
+        profile_root.path(),
+    )?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let req_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            cwd: Some(cwd.path().to_string_lossy().to_string()),
+            ..Default::default()
+        })
+        .await?;
+
+    let resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(req_id)),
+    )
+    .await??;
+    let ThreadStartResponse {
+        runtime_workspace_roots,
+        ..
+    } = to_response::<ThreadStartResponse>(resp)?;
+
+    assert_eq!(
+        runtime_workspace_roots,
+        vec![cwd.path().to_path_buf().abs()]
+    );
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn thread_start_rejects_unknown_environment_as_invalid_request() -> Result<()> {
    let server = create_mock_responses_server_repeating_assistant("Done").await;
@@ -980,6 +1063,42 @@ stream_max_retries = 0
    )
 }

+fn create_config_toml_with_profile_workspace_root(
+    codex_home: &Path,
+    server_uri: &str,
+    profile_root: &Path,
+) -> std::io::Result<()> {
+    let config_toml = codex_home.join("config.toml");
+    let profile_root_key = profile_root
+        .display()
+        .to_string()
+        .replace('\\', "\\\\")
+        .replace('"', "\\\"");
+    std::fs::write(
+        config_toml,
+        format!(
+            r#"
+model = "mock-model"
+default_permissions = "dev"
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+
+[permissions.dev.workspace_roots]
+"{profile_root_key}" = true
+
+[permissions.dev.filesystem.":workspace_roots"]
+"." = "write"
+"#,
+        ),
+    )
+}
+
 fn create_config_toml_with_chatgpt_base_url(
    codex_home: &Path,
    server_uri: &str,
@@ -34,7 +34,6 @@ use codex_app_server_protocol::JSONRPCNotification;
 use codex_app_server_protocol::JSONRPCResponse;
 use codex_app_server_protocol::PatchApplyStatus;
 use codex_app_server_protocol::PatchChangeKind;
-use codex_app_server_protocol::PermissionProfileSelectionParams;
 use codex_app_server_protocol::RequestId;
 use codex_app_server_protocol::ServerRequest;
 use codex_app_server_protocol::ServerRequestResolvedNotification;
@@ -780,10 +779,11 @@ async fn turn_start_rejects_invalid_permission_selection_before_starting_turn()
                text: "Hello".to_string(),
                text_elements: Vec::new(),
            }],
-            permissions: Some(PermissionProfileSelectionParams::Profile {
-                id: BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS.to_string(),
-                modifications: None,
-            }),
+            permissions: Some(
+                BUILT_IN_PERMISSION_PROFILE_DANGER_FULL_ACCESS
+                    .to_string()
+                    .into(),
+            ),
            ..Default::default()
        })
        .await?;
@@ -1891,6 +1891,7 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
            }],
            responsesapi_client_metadata: None,
            cwd: Some(first_cwd.clone()),
+            runtime_workspace_roots: None,
            approval_policy: Some(codex_app_server_protocol::AskForApproval::Never),
            approvals_reviewer: None,
            sandbox_policy: Some(codex_app_server_protocol::SandboxPolicy::WorkspaceWrite {
@@ -1932,6 +1933,7 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
            }],
            responsesapi_client_metadata: None,
            cwd: Some(second_cwd.clone()),
+            runtime_workspace_roots: None,
            approval_policy: Some(codex_app_server_protocol::AskForApproval::Never),
            approvals_reviewer: None,
            sandbox_policy: Some(codex_app_server_protocol::SandboxPolicy::DangerFullAccess),
@@ -1991,6 +1993,152 @@ async fn turn_start_updates_sandbox_and_cwd_between_turns_v2() -> Result<()> {
    Ok(())
 }

+#[cfg(unix)]
+#[tokio::test]
+async fn turn_start_permission_profile_rebinds_runtime_workspace_roots_between_turns() -> Result<()>
+{
+    skip_if_no_network!(Ok(()));
+
+    let tmp = TempDir::new()?;
+    let codex_home = tmp.path().join("codex_home");
+    std::fs::create_dir(&codex_home)?;
+    let old_root = tmp.path().join("old-root");
+    let new_root = tmp.path().join("new-root");
+    std::fs::create_dir(&old_root)?;
+    std::fs::create_dir(&new_root)?;
+    let old_root_text = old_root.to_string_lossy().into_owned();
+    let new_root_text = new_root.to_string_lossy().into_owned();
+
+    let server = responses::start_mock_server().await;
+    let response_mock = responses::mount_sse_sequence(
+        &server,
+        vec![
+            responses::sse(vec![
+                responses::ev_response_created("resp-1"),
+                responses::ev_assistant_message("msg-1", "done first"),
+                responses::ev_completed("resp-1"),
+            ]),
+            responses::sse(vec![
+                responses::ev_response_created("resp-2"),
+                responses::ev_assistant_message("msg-2", "done second"),
+                responses::ev_completed("resp-2"),
+            ]),
+        ],
+    )
+    .await;
+    let server_uri = server.uri();
+    std::fs::write(
+        codex_home.join("config.toml"),
+        format!(
+            r#"
+model = "mock-model"
+approval_policy = "never"
+default_permissions = "dev"
+model_provider = "mock_provider"
+
+[model_providers.mock_provider]
+name = "Mock provider for test"
+base_url = "{server_uri}/v1"
+wire_api = "responses"
+request_max_retries = 0
+stream_max_retries = 0
+
+[permissions.dev.filesystem.":workspace_roots"]
+"." = "write"
+"#
+        ),
+    )?;
+
+    let mut mcp = McpProcess::new(&codex_home).await?;
+    timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
+
+    let start_id = mcp
+        .send_thread_start_request(ThreadStartParams {
+            model: Some("mock-model".to_string()),
+            ..Default::default()
+        })
+        .await?;
+    let start_resp: JSONRPCResponse = timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(start_id)),
+    )
+    .await??;
+    let ThreadStartResponse { thread, .. } = to_response::<ThreadStartResponse>(start_resp)?;
+
+    let first_turn_id = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            input: vec![V2UserInput::Text {
+                text: "select dev profile".to_string(),
+                text_elements: Vec::new(),
+            }],
+            runtime_workspace_roots: Some(vec![old_root]),
+            permissions: Some("dev".to_string().into()),
+            ..Default::default()
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(first_turn_id)),
+    )
+    .await??;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let second_turn_id = mcp
+        .send_turn_start_request(TurnStartParams {
+            thread_id: thread.id.clone(),
+            input: vec![V2UserInput::Text {
+                text: "write in new root".to_string(),
+                text_elements: Vec::new(),
+            }],
+            runtime_workspace_roots: Some(vec![new_root]),
+            ..Default::default()
+        })
+        .await?;
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(second_turn_id)),
+    )
+    .await??;
+
+    timeout(
+        DEFAULT_READ_TIMEOUT,
+        mcp.read_stream_until_notification_message("turn/completed"),
+    )
+    .await??;
+
+    let requests = response_mock.requests();
+    assert_eq!(requests.len(), 2, "expected two Responses API requests");
+    let latest_permissions_instructions =
+        |request: &core_test_support::responses::ResponsesRequest| {
+            request
+                .message_input_texts("developer")
+                .into_iter()
+                .rev()
+                .find(|text| text.contains("<permissions instructions>"))
+                .expect("permissions instructions")
+        };
+    let first_permissions = latest_permissions_instructions(&requests[0]);
+    assert!(first_permissions.contains(&old_root_text));
+    assert!(
+        !first_permissions.contains(&new_root_text),
+        "first turn should materialize the initial runtime workspace root"
+    );
+
+    let second_permissions = latest_permissions_instructions(&requests[1]);
+    assert!(second_permissions.contains(&new_root_text));
+    assert!(
+        !second_permissions.contains(&old_root_text),
+        "second turn should rebind :workspace_roots to the updated runtime workspace root"
+    );
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn turn_start_resolves_sticky_thread_local_environment_and_turn_overrides() -> Result<()> {
    let tmp = TempDir::new()?;