[codex] Adopt global instructions contributors

codex-rs/Cargo.toml

@@ -37,8 +37,8 @@ members = [
     "core-api",
     "core-plugins",
     "core-skills",
-    "home",
     "hooks",
+    "home",
     "secrets",
     "exec",
     "file-system",
@@ -170,7 +170,6 @@ codex-execpolicy = { path = "execpolicy" }
 codex-extension-api = { path = "ext/extension-api" }
 codex-goal-extension = { path = "ext/goal" }
 codex-guardian = { path = "ext/guardian" }
-codex-home = { path = "home" }
 codex-image-generation-extension = { path = "ext/image-generation" }
 codex-external-agent-migration = { path = "external-agent-migration" }
 codex-external-agent-sessions = { path = "external-agent-sessions" }
@@ -182,6 +181,7 @@ codex-file-search = { path = "file-search" }
 codex-file-watcher = { path = "file-watcher" }
 codex-git-utils = { path = "git-utils" }
 codex-hooks = { path = "hooks" }
+codex-home = { path = "home" }
 codex-keyring-store = { path = "keyring-store" }
 codex-linux-sandbox = { path = "linux-sandbox" }
 codex-lmstudio = { path = "lmstudio" }

codex-rs/app-server/Cargo.toml

@@ -46,6 +46,7 @@ codex-guardian = { workspace = true }
 codex-git-utils = { workspace = true }
 codex-file-watcher = { workspace = true }
 codex-hooks = { workspace = true }
+codex-home = { workspace = true }
 codex-otel = { workspace = true }
 codex-plugin = { workspace = true }
 codex-shell-command = { workspace = true }

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

@@ -14,12 +14,14 @@ use codex_extension_api::ExtensionEventSink;
 use codex_extension_api::ExtensionRegistry;
 use codex_extension_api::ExtensionRegistryBuilder;
 use codex_goal_extension::GoalService;
+use codex_home::CodexHomeInstructionsContributor;
 use codex_login::AuthManager;
 use codex_protocol::ThreadId;
 use codex_protocol::error::CodexErr;
 use codex_protocol::protocol::Event;
 use codex_protocol::protocol::EventMsg;
 use codex_rollout::state_db::StateDbHandle;
+use codex_utils_absolute_path::AbsolutePathBuf;
 
 use crate::outgoing_message::OutgoingMessageSender;
 use crate::thread_state::ThreadListenerCommand;
@@ -32,11 +34,15 @@ pub(crate) fn thread_extensions<S>(
     state_db: Option<StateDbHandle>,
     thread_manager: Weak<ThreadManager>,
     goal_service: Arc<GoalService>,
+    codex_home: AbsolutePathBuf,
 ) -> Arc<ExtensionRegistry<Config>>
 where
     S: AgentSpawner<StartThreadOptions, Spawned = NewThread, Error = CodexErr> + 'static,
 {
     let mut builder = ExtensionRegistryBuilder::<Config>::with_event_sink(event_sink);
+    builder.global_instructions_contributor(Arc::new(CodexHomeInstructionsContributor::new(
+        codex_home,
+    )));
     if let Some(state_db) = state_db {
         codex_goal_extension::install_with_backend(
             &mut builder,

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

@@ -194,6 +194,7 @@ mod tests {
                     Some(state_db.clone()),
                     thread_manager.clone(),
                     Arc::new(codex_goal_extension::GoalService::new()),
+                    good_config.codex_home.clone(),
                 ),
                 /*analytics_events_client*/ None,
                 Arc::clone(&thread_store),

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

@@ -320,6 +320,7 @@ impl MessageProcessor {
                     state_db.clone(),
                     thread_manager.clone(),
                     Arc::clone(&goal_service),
+                    config.codex_home.clone(),
                 ),
                 Some(analytics_events_client.clone()),
                 Arc::clone(&thread_store),

codex-rs/app-server/tests/suite/v2/thread_start.rs

@@ -30,6 +30,7 @@ use codex_login::REFRESH_TOKEN_URL_OVERRIDE_ENV_VAR;
 use codex_protocol::config_types::SERVICE_TIER_DEFAULT_REQUEST_VALUE;
 use codex_protocol::config_types::TrustLevel;
 use codex_protocol::openai_models::ReasoningEffort;
+use codex_utils_absolute_path::AbsolutePathBuf;
 use pretty_assertions::assert_eq;
 use serde_json::Value;
 use serde_json::json;
@@ -400,11 +401,13 @@ async fn thread_start_response_excludes_empty_project_instruction_source() -> Re
 }
 
 #[tokio::test]
-async fn thread_start_without_selected_environment_excludes_instruction_sources() -> Result<()> {
+async fn thread_start_without_selected_environment_includes_global_instruction_source() -> 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())?;
-    std::fs::write(codex_home.path().join("AGENTS.md"), "global instructions")?;
+    let global_agents_path = codex_home.path().join("AGENTS.md");
+    std::fs::write(&global_agents_path, "global instructions")?;
     let workspace = TempDir::new()?;
     std::fs::write(workspace.path().join("AGENTS.md"), "project instructions")?;
 
@@ -428,7 +431,12 @@ async fn thread_start_without_selected_environment_excludes_instruction_sources(
         ..
     } = to_response::<ThreadStartResponse>(response)?;
 
-    assert!(instruction_sources.is_empty());
+    assert_eq!(
+        instruction_sources,
+        vec![AbsolutePathBuf::try_from(std::fs::canonicalize(
+            global_agents_path
+        )?)?]
+    );
 
     Ok(())
 }

codex-rs/core-api/Cargo.toml

@@ -20,9 +20,9 @@ codex-analytics = { workspace = true }
 codex-config = { workspace = true }
 codex-core = { workspace = true }
 codex-extension-api = { workspace = true }
+codex-home = { workspace = true }
 codex-exec-server = { workspace = true }
 codex-features = { workspace = true }
-codex-home = { workspace = true }
 codex-login = { workspace = true }
 codex-model-provider-info = { workspace = true }
 codex-models-manager = { workspace = true }

codex-rs/core-api/src/lib.rs

@@ -26,7 +26,6 @@ pub use codex_config::types::TuiPetAnchor;
 pub use codex_config::types::UriBasedFileOpener;
 pub use codex_core::CodexThread;
 pub use codex_core::ForkSnapshot;
-pub use codex_core::LoadedAgentsMd;
 pub use codex_core::McpManager;
 pub use codex_core::NewThread;
 pub use codex_core::StartThreadOptions;

codex-rs/core/Cargo.toml

@@ -48,6 +48,7 @@ codex-shell-command = { workspace = true }
 codex-execpolicy = { workspace = true }
 codex-git-utils = { workspace = true }
 codex-hooks = { workspace = true }
+codex-home = { workspace = true }
 codex-install-context = { workspace = true }
 codex-network-proxy = { workspace = true }
 codex-otel = { workspace = true }

codex-rs/core/src/agents_md.rs

@@ -55,36 +55,6 @@ impl<'a> AgentsMdManager<'a> {
         Self { config }
     }
 
-    pub(crate) async fn load_global_instructions(
-        fs: &dyn ExecutorFileSystem,
-        codex_dir: Option<&AbsolutePathBuf>,
-        startup_warnings: &mut Vec<String>,
-    ) -> Option<LoadedAgentsMd> {
-        let base = codex_dir?;
-        for candidate in [LOCAL_AGENTS_MD_FILENAME, DEFAULT_AGENTS_MD_FILENAME] {
-            let path = base.join(candidate);
-            let data = match fs.read_file(&path, /*sandbox*/ None).await {
-                Ok(data) => data,
-                Err(err) if err.kind() == io::ErrorKind::NotFound => continue,
-                Err(err) if err.kind() == io::ErrorKind::IsADirectory => continue,
-                Err(err) => {
-                    startup_warnings.push(format!(
-                        "Failed to read global AGENTS.md instructions from `{}`: {err}",
-                        path.display()
-                    ));
-                    continue;
-                }
-            };
-            warn_invalid_utf8(&path, &data, "Global", startup_warnings);
-            let contents = String::from_utf8_lossy(&data);
-            let trimmed = contents.trim();
-            if !trimmed.is_empty() {
-                return Some(LoadedAgentsMd::new_user(trimmed.to_string(), path));
-            }
-        }
-        None
-    }
-
     /// Combines global instructions and project AGENTS.md content into a
     /// single model-visible instruction snapshot.
     pub(crate) async fn user_instructions(
@@ -321,27 +291,25 @@ impl<'a> AgentsMdManager<'a> {
 /// Model-visible instructions loaded from AGENTS.md files and internal
 /// guidance.
 #[derive(Clone, Debug, Default, PartialEq, Eq)]
-pub struct LoadedAgentsMd {
+pub(crate) struct LoadedAgentsMd {
     /// Ordered instructions and their provenance.
     entries: Vec<InstructionEntry>,
 }
 
 impl LoadedAgentsMd {
-    pub fn new_user(contents: String, path: AbsolutePathBuf) -> Self {
-        if contents.trim().is_empty() {
-            return Self::default();
-        }
-        let mut loaded = Self {
-            entries: vec![InstructionEntry {
+    #[cfg(test)]
+    pub(crate) fn new_user(contents: String, path: AbsolutePathBuf) -> Self {
+        Self::from_global(codex_extension_api::GlobalInstructions {
+            instructions: vec![codex_extension_api::GlobalInstruction::new(
                 contents,
-                provenance: InstructionProvenance::Global(Some(path)),
-            }],
-        };
-        loaded.enforce_model_context_limit();
-        loaded
+                Some(path),
+            )],
+            warnings: Vec::new(),
+        })
     }
 
-    pub fn from_text_for_testing(contents: impl Into<String>) -> Self {
+    #[cfg(test)]
+    pub(crate) fn from_text_for_testing(contents: impl Into<String>) -> Self {
         let contents = contents.into();
         if contents.trim().is_empty() {
             return Self::default();
@@ -354,6 +322,22 @@ impl LoadedAgentsMd {
         }
     }
 
+    pub(crate) fn from_global(instructions: codex_extension_api::GlobalInstructions) -> Self {
+        let mut loaded = Self {
+            entries: instructions
+                .instructions
+                .into_iter()
+                .filter(|instruction| !instruction.contents.trim().is_empty())
+                .map(|instruction| InstructionEntry {
+                    contents: instruction.contents,
+                    provenance: InstructionProvenance::Global(instruction.source),
+                })
+                .collect(),
+        };
+        loaded.enforce_model_context_limit();
+        loaded
+    }
+
     pub(crate) fn from_snapshot(snapshot: UserInstructionsSnapshot) -> Self {
         let mut loaded = Self {
             entries: snapshot
@@ -403,14 +387,14 @@ impl LoadedAgentsMd {
         }
     }
 
-    pub(crate) fn replace_global(&mut self, instructions: LoadedAgentsMd) {
+    pub(crate) fn replace_global(&mut self, instructions: codex_extension_api::GlobalInstructions) {
         let first_non_global = self
             .entries
             .iter()
             .position(|entry| !matches!(entry.provenance, InstructionProvenance::Global(_)))
             .unwrap_or(self.entries.len());
         self.entries
-            .splice(..first_non_global, instructions.entries);
+            .splice(..first_non_global, Self::from_global(instructions).entries);
         self.enforce_model_context_limit();
     }
 
@@ -421,7 +405,7 @@ impl LoadedAgentsMd {
     }
 
     /// Returns the concatenated model-visible instruction text.
-    pub fn text(&self) -> String {
+    pub(crate) fn text(&self) -> String {
         let mut output = String::new();
         let mut previous_provenance: Option<&InstructionProvenance> = None;
         for entry in &self.entries {
@@ -445,7 +429,7 @@ impl LoadedAgentsMd {
     }
 
     /// Returns the AGENTS.md files that supplied instruction entries.
-    pub fn sources(&self) -> impl Iterator<Item = &AbsolutePathBuf> {
+    pub(crate) fn sources(&self) -> impl Iterator<Item = &AbsolutePathBuf> {
         self.entries
             .iter()
             .filter_map(|entry| entry.provenance.path())

codex-rs/core/src/agents_md_tests.rs

@@ -188,15 +188,15 @@ fn loaded_instructions_with_only_empty_or_whitespace_entries_are_empty() {
 }
 
 #[test]
-fn configured_and_persisted_instructions_are_bounded_for_model_context() {
+fn contributor_and_persisted_instructions_are_bounded_for_model_context() {
     let oversized = "x".repeat(approx_bytes_for_tokens(MAX_USER_INSTRUCTIONS_TOKENS + 100));
-    let mut global = LoadedAgentsMd {
-        entries: vec![InstructionEntry {
-            contents: oversized.clone(),
-            provenance: InstructionProvenance::Global(None),
-        }],
-    };
-    global.enforce_model_context_limit();
+    let global = LoadedAgentsMd::from_global(codex_extension_api::GlobalInstructions {
+        instructions: vec![codex_extension_api::GlobalInstruction::new(
+            oversized.clone(),
+            /*source*/ None,
+        )],
+        warnings: Vec::new(),
+    });
     let restored = LoadedAgentsMd::from_snapshot(UserInstructionsSnapshot {
         instructions: vec![InstructionSnapshot {
             contents: oversized,
@@ -227,7 +227,13 @@ fn replacing_global_instructions_preserves_project_entries_within_the_bound() {
         provenance: InstructionProvenance::Project(Some(project_source.clone())),
     });
 
-    loaded.replace_global(LoadedAgentsMd::from_text_for_testing("new global"));
+    loaded.replace_global(codex_extension_api::GlobalInstructions {
+        instructions: vec![codex_extension_api::GlobalInstruction::new(
+            "new global",
+            /*source*/ None,
+        )],
+        warnings: Vec::new(),
+    });
 
     assert_eq!(
         loaded,