Extract codex-instructions crate (#15744)

## Summary
- extract instruction fragment and user-instruction types into
codex-instructions
- update codex-core to consume the new crate

## Testing
- CI

---------

Co-authored-by: Codex <noreply@openai.com>

codex-rs/instructions/src/fragment.rs

@@ -0,0 +1,61 @@
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+
+pub(crate) const AGENTS_MD_START_MARKER: &str = "# AGENTS.md instructions for ";
+pub(crate) const AGENTS_MD_END_MARKER: &str = "</INSTRUCTIONS>";
+pub(crate) const SKILL_OPEN_TAG: &str = "<skill>";
+pub(crate) const SKILL_CLOSE_TAG: &str = "</skill>";
+
+#[derive(Clone, Copy)]
+pub struct ContextualUserFragmentDefinition {
+    start_marker: &'static str,
+    end_marker: &'static str,
+}
+
+impl ContextualUserFragmentDefinition {
+    pub const fn new(start_marker: &'static str, end_marker: &'static str) -> Self {
+        Self {
+            start_marker,
+            end_marker,
+        }
+    }
+
+    pub fn matches_text(&self, text: &str) -> bool {
+        let trimmed = text.trim_start();
+        let starts_with_marker = trimmed
+            .get(..self.start_marker.len())
+            .is_some_and(|candidate| candidate.eq_ignore_ascii_case(self.start_marker));
+        let trimmed = trimmed.trim_end();
+        let ends_with_marker = trimmed
+            .get(trimmed.len().saturating_sub(self.end_marker.len())..)
+            .is_some_and(|candidate| candidate.eq_ignore_ascii_case(self.end_marker));
+        starts_with_marker && ends_with_marker
+    }
+
+    pub const fn start_marker(&self) -> &'static str {
+        self.start_marker
+    }
+
+    pub const fn end_marker(&self) -> &'static str {
+        self.end_marker
+    }
+
+    pub fn wrap(&self, body: String) -> String {
+        format!("{}\n{}\n{}", self.start_marker, body, self.end_marker)
+    }
+
+    pub fn into_message(self, text: String) -> ResponseItem {
+        ResponseItem::Message {
+            id: None,
+            role: "user".to_string(),
+            content: vec![ContentItem::InputText { text }],
+            end_turn: None,
+            phase: None,
+        }
+    }
+}
+
+pub const AGENTS_MD_FRAGMENT: ContextualUserFragmentDefinition =
+    ContextualUserFragmentDefinition::new(AGENTS_MD_START_MARKER, AGENTS_MD_END_MARKER);
+pub const SKILL_FRAGMENT: ContextualUserFragmentDefinition =
+    ContextualUserFragmentDefinition::new(SKILL_OPEN_TAG, SKILL_CLOSE_TAG);

codex-rs/instructions/src/lib.rs

@@ -0,0 +1,11 @@
+//! User and skill instruction payloads and contextual user fragment markers for Codex prompts.
+
+mod fragment;
+mod user_instructions;
+
+pub use fragment::AGENTS_MD_FRAGMENT;
+pub use fragment::ContextualUserFragmentDefinition;
+pub use fragment::SKILL_FRAGMENT;
+pub use user_instructions::SkillInstructions;
+pub use user_instructions::USER_INSTRUCTIONS_PREFIX;
+pub use user_instructions::UserInstructions;

codex-rs/instructions/src/user_instructions.rs

@@ -0,0 +1,56 @@
+use serde::Deserialize;
+use serde::Serialize;
+
+use codex_protocol::models::ResponseItem;
+
+use crate::fragment::AGENTS_MD_FRAGMENT;
+use crate::fragment::AGENTS_MD_START_MARKER;
+use crate::fragment::SKILL_FRAGMENT;
+
+pub const USER_INSTRUCTIONS_PREFIX: &str = AGENTS_MD_START_MARKER;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename = "user_instructions", rename_all = "snake_case")]
+pub struct UserInstructions {
+    pub directory: String,
+    pub text: String,
+}
+
+impl UserInstructions {
+    pub fn serialize_to_text(&self) -> String {
+        format!(
+            "{prefix}{directory}\n\n<INSTRUCTIONS>\n{contents}\n{suffix}",
+            prefix = AGENTS_MD_FRAGMENT.start_marker(),
+            directory = self.directory,
+            contents = self.text,
+            suffix = AGENTS_MD_FRAGMENT.end_marker(),
+        )
+    }
+}
+
+impl From<UserInstructions> for ResponseItem {
+    fn from(ui: UserInstructions) -> Self {
+        AGENTS_MD_FRAGMENT.into_message(ui.serialize_to_text())
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename = "skill_instructions", rename_all = "snake_case")]
+pub struct SkillInstructions {
+    pub name: String,
+    pub path: String,
+    pub contents: String,
+}
+
+impl From<SkillInstructions> for ResponseItem {
+    fn from(si: SkillInstructions) -> Self {
+        SKILL_FRAGMENT.into_message(SKILL_FRAGMENT.wrap(format!(
+            "<name>{}</name>\n<path>{}</path>\n{}",
+            si.name, si.path, si.contents
+        )))
+    }
+}
+
+#[cfg(test)]
+#[path = "user_instructions_tests.rs"]
+mod tests;

codex-rs/instructions/src/user_instructions_tests.rs

@@ -0,0 +1,72 @@
+use super::*;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use pretty_assertions::assert_eq;
+
+use crate::fragment::AGENTS_MD_FRAGMENT;
+use crate::fragment::SKILL_FRAGMENT;
+
+#[test]
+fn test_user_instructions() {
+    let user_instructions = UserInstructions {
+        directory: "test_directory".to_string(),
+        text: "test_text".to_string(),
+    };
+    let response_item: ResponseItem = user_instructions.into();
+
+    let ResponseItem::Message { role, content, .. } = response_item else {
+        panic!("expected ResponseItem::Message");
+    };
+
+    assert_eq!(role, "user");
+
+    let [ContentItem::InputText { text }] = content.as_slice() else {
+        panic!("expected one InputText content item");
+    };
+
+    assert_eq!(
+        text,
+        "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>",
+    );
+}
+
+#[test]
+fn test_is_user_instructions() {
+    assert!(AGENTS_MD_FRAGMENT.matches_text(
+        "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>"
+    ));
+    assert!(!AGENTS_MD_FRAGMENT.matches_text("test_text"));
+}
+
+#[test]
+fn test_skill_instructions() {
+    let skill_instructions = SkillInstructions {
+        name: "demo-skill".to_string(),
+        path: "skills/demo/SKILL.md".to_string(),
+        contents: "body".to_string(),
+    };
+    let response_item: ResponseItem = skill_instructions.into();
+
+    let ResponseItem::Message { role, content, .. } = response_item else {
+        panic!("expected ResponseItem::Message");
+    };
+
+    assert_eq!(role, "user");
+
+    let [ContentItem::InputText { text }] = content.as_slice() else {
+        panic!("expected one InputText content item");
+    };
+
+    assert_eq!(
+        text,
+        "<skill>\n<name>demo-skill</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>",
+    );
+}
+
+#[test]
+fn test_is_skill_instructions() {
+    assert!(SKILL_FRAGMENT.matches_text(
+        "<skill>\n<name>demo-skill</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>"
+    ));
+    assert!(!SKILL_FRAGMENT.matches_text("regular text"));
+}