feat(ecosystem): discover and import bundled Codex pets

Author: kev1n77

scripts/core-boundaries/rules/feature-rules.mjs

@@ -93,7 +93,7 @@ export const optionalDependencyFeatureOwnerRules = [
       },
       { depName: 'which', ownerFeatures: ['process-runtime'] },
       { depName: 'win32job', ownerFeatures: ['process-runtime'] },
-      { depName: 'windows', ownerFeatures: ['json-io', 'local-storage', 'process-runtime'] },
+      { depName: 'windows', ownerFeatures: ['installed-apps', 'json-io', 'local-storage', 'process-runtime'] },
       {
         depName: 'tokio',
         ownerFeatures: [

scripts/core-boundaries/rules/source/public-api-rules.mjs

@@ -541,17 +541,17 @@ export const codexAdapterPublicApiEntries = [
 ))).concat([
   'load_codex_user_instructions',
   'CodexInstructionSourceOptions',
-].map((symbol) => userInstructionSourceAdapterEntry(symbol, 'Codex'))).concat([{
-  symbol: 'pet_source_root',
+].map((symbol) => userInstructionSourceAdapterEntry(symbol, 'Codex'))).concat(['pet_source_root', 'builtin_pet_sources', 'BuiltinPetCatalog', 'BuiltinPetSource'].map((symbol) => ({
+  symbol,
   owner: 'Codex adapter static pet source owner',
   consumer: 'openbitfun-core external source composition facade',
-  verification: 'Codex configured root test and services-core pet package fixtures',
-  p0: 'local custom pet source root discovery without execution or installation',
+  verification: 'Codex pet source fixtures, installed bundle smoke test, and services-core pet package tests',
+  p0: 'local custom and bundled pet source discovery without execution or installation',
   contractSlice: contractSlices.externalSourcePetContract,
   wireImpact: false,
-  rationale: 'the adapter resolves CODEX_HOME; the host supplies the native destination to the portable pet package service',
+  rationale: 'the adapter translates Codex package metadata; portable services own bounded resource IO and native copying',
   exit: 'remove only when an equivalent typed pet source provider owns this root',
-}]);
+})));
 
 export const staticHookSupportPublicApiEntries = [
   // Shared by DSH/PI only for validated, redacted source/event construction.
@@ -1224,6 +1224,8 @@ export const externalSourceCorePublicApiEntries = [
     'native_prompt_command_conflicts',
     'instruction_source_catalog',
     'external_pet_source_root',
+    'external_builtin_pet_sources',
+    'ExternalBuiltinPetCatalog',
     'InstructionSourceCatalog',
     'set_native_prompt_command_conflict_choice',
     'external_source_conflict_choices',

src/apps/desktop/src/api/commands.rs

@@ -482,6 +482,8 @@ pub struct ImportAgentCompanionPetPackageRequest {
     pub path: String,
     #[serde(default)]
     pub expected_fingerprint: Option<String>,
+    #[serde(default)]
+    pub builtin_id: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -497,13 +499,16 @@ pub use openbitfun_services_core::pet_packages::PetPackage as AgentCompanionPetP
 pub struct ListAgentCompanionPetsRequest {
     #[serde(default)]
     pub include_external: bool,
+    #[serde(default)]
+    pub builtin_import_version: Option<u32>,
 }
 
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ListAgentCompanionPetsResponse {
     pub pets: Vec<AgentCompanionPetPackageDto>,
     pub import_operations_version: u32,
+    pub builtin_import_version: u32,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub external: Option<openbitfun_services_core::pet_packages::PetCatalog>,
 }
@@ -2525,11 +2530,57 @@ mod pet_package_tests {
         let old: ImportAgentCompanionPetPackageRequest =
             serde_json::from_value(serde_json::json!({"path": "legacy-pet"})).unwrap();
         assert!(old.expected_fingerprint.is_none());
+        assert!(old.builtin_id.is_none());
         let request: ListAgentCompanionPetsRequest =
             serde_json::from_value(serde_json::json!({})).unwrap();
         assert!(!request.include_external);
+        assert!(request.builtin_import_version.is_none());
+    }
+
+    #[test]
+    fn bundled_pet_request_requires_review() {
+        let temp = tempfile::tempdir().unwrap();
+        let request =
+            serde_json::from_value(serde_json::json!({"path":"app.asar", "builtinId":"codex"}))
+                .unwrap();
+        assert!(import_pet_request(temp.path(), request)
+            .unwrap_err()
+            .contains("reviewed fingerprint"));
     }
 
+    #[test]
+    #[ignore = "Imports installed Codex pets into an isolated temporary directory"]
+    fn installed_builtin_pets_can_be_previewed_and_imported() {
+        let temp = tempfile::tempdir().unwrap();
+        let sources =
+            openbitfun_core::external_sources::external_builtin_pet_sources("codex", None);
+        assert!(sources.diagnostics.is_empty(), "{:?}", sources.diagnostics);
+        assert!(!sources.pets.is_empty());
+        for source in sources.pets {
+            let identity = format!("codex:builtin:{}", source.id);
+            let candidate = openbitfun_services_core::pet_packages::candidate_from_bytes(
+                temp.path(),
+                &identity,
+                &source.archive_path,
+                &source.manifest,
+                source.image,
+            )
+            .unwrap();
+            assert!(candidate
+                .preview_data_url
+                .starts_with("data:image/png;base64,"));
+            let request = serde_json::from_value(serde_json::json!({
+                "path": source.archive_path, "builtinId":source.id, "expectedFingerprint":candidate.fingerprint,
+            })).unwrap();
+            let imported = import_pet_request(temp.path(), request).unwrap();
+            assert!(Path::new(&imported.spritesheet_path).is_file());
+            assert_eq!(
+                imported.sprite_version_number,
+                candidate.pet.sprite_version_number
+            );
+            println!("Validated bundled pet: {}", imported.display_name);
+        }
+    }
     #[test]
     fn pet_manifest_versions_are_validated_and_exported() {
         for version in [None, Some(1), Some(2)] {
@@ -2656,14 +2707,43 @@ pub async fn list_agent_companion_pets(
     state: State<'_, AppState>,
     request: Option<ListAgentCompanionPetsRequest>,
 ) -> Result<ListAgentCompanionPetsResponse, String> {
+    let include_builtins = request
+        .as_ref()
+        .is_some_and(|r| r.builtin_import_version == Some(1));
     let mut response = list_agent_companion_pets_impl(&state).await?;
     if request.is_some_and(|r| r.include_external) {
         let source_root = openbitfun_core::external_sources::external_pet_source_root("codex")
             .ok_or("Pet source is unavailable")?;
         let installed_root = companion_user_packages_dir(&state);
         response.external = Some(
             tokio::task::spawn_blocking(move || {
-                openbitfun_services_core::pet_packages::catalog(&source_root, &installed_root)
+                let mut catalog =
+                    openbitfun_services_core::pet_packages::catalog(&source_root, &installed_root);
+                if !include_builtins {
+                    return catalog;
+                }
+                let bundled =
+                    openbitfun_core::external_sources::external_builtin_pet_sources("codex", None);
+                catalog.diagnostics.extend(bundled.diagnostics);
+                for source in bundled.pets {
+                    let identity = format!("codex:builtin:{}", source.id);
+                    match openbitfun_services_core::pet_packages::candidate_from_bytes(
+                        &installed_root,
+                        &identity,
+                        &source.archive_path,
+                        &source.manifest,
+                        source.image,
+                    ) {
+                        Ok(mut candidate) => {
+                            candidate.builtin_id = Some(source.id);
+                            catalog.candidates.push(candidate);
+                        }
+                        Err(error) => catalog
+                            .diagnostics
+                            .push(format!("Codex built-in pet {}: {error}", source.id)),
+                    }
+                }
+                catalog
             })
             .await
             .map_err(|e| e.to_string())?,
@@ -2679,6 +2759,7 @@ pub(crate) async fn list_agent_companion_pets_impl(
     Ok(ListAgentCompanionPetsResponse {
         pets,
         import_operations_version: 1,
+        builtin_import_version: 1,
         external: None,
     })
 }
@@ -2689,15 +2770,42 @@ pub async fn import_agent_companion_pet_package(
     request: ImportAgentCompanionPetPackageRequest,
 ) -> Result<AgentCompanionPetPackageDto, String> {
     let root = companion_user_packages_dir(&state);
-    tokio::task::spawn_blocking(move || {
-        openbitfun_services_core::pet_packages::import(
+    tokio::task::spawn_blocking(move || import_pet_request(&root, request))
+        .await
+        .map_err(|e| e.to_string())?
+}
+
+fn import_pet_request(
+    root: &Path,
+    request: ImportAgentCompanionPetPackageRequest,
+) -> Result<AgentCompanionPetPackageDto, String> {
+    if let Some(id) = request.builtin_id {
+        let expected = request
+            .expected_fingerprint
+            .as_deref()
+            .ok_or("Built-in pet import requires a reviewed fingerprint")?;
+        let mut catalog =
+            openbitfun_core::external_sources::external_builtin_pet_sources("codex", Some(&id));
+        let source = catalog.pets.pop().ok_or_else(|| {
+            if catalog.diagnostics.is_empty() {
+                "Built-in pet is unavailable".to_string()
+            } else {
+                catalog.diagnostics.join("; ")
+            }
+        })?;
+        return openbitfun_services_core::pet_packages::import_bytes(
             &root,
-            Path::new(&request.path),
-            request.expected_fingerprint.as_deref(),
-        )
-    })
-    .await
-    .map_err(|e| e.to_string())?
+            &format!("codex:builtin:{id}"),
+            &source.manifest,
+            source.image,
+            expected,
+        );
+    }
+    openbitfun_services_core::pet_packages::import(
+        &root,
+        Path::new(&request.path),
+        request.expected_fingerprint.as_deref(),
+    )
 }
 
 pub(crate) async fn import_agent_companion_pet_package_impl(

src/crates/adapters/codex-adapter/AGENTS.md

@@ -5,3 +5,11 @@
 - Preserve native Codex event and handler names. Map only reviewed OpenBitFun Hook points; report every other event as native-only.
 - Preserve Codex configuration-layer and field-overlay semantics inside each typed provider. Unknown behavior fields must block explicitly; do not invent Codex Command or standalone Tool sources.
 - Do not depend on another ecosystem adapter. Shared product behavior belongs in contracts or assembly.
+
+## Pet source verification
+
+```bash
+cargo test -p openbitfun-codex-adapter --lib pet_source
+# Optional read-only verification on a host with the Codex desktop app installed:
+cargo test -p openbitfun-codex-adapter --lib installed_builtin_pet_catalog -- --ignored --nocapture
+```

src/crates/adapters/codex-adapter/Cargo.toml

@@ -12,7 +12,7 @@ crate-type = ["rlib"]
 
 [dependencies]
 openbitfun-product-domains = { path = "../../contracts/product-domains", features = ["external-sources"] }
-openbitfun-services-core = { path = "../../services/services-core" }
+openbitfun-services-core = { path = "../../services/services-core", features = ["asar", "installed-apps"] }
 openbitfun-static-hook-support = { path = "../static-hook-support" }
 dirs = { workspace = true }
 dunce = { workspace = true }

src/crates/adapters/codex-adapter/src/lib.rs

@@ -4,6 +4,9 @@ mod agent_source;
 mod hook_source;
 mod instruction_source;
 mod mcp_source;
+mod pet_source;
+
+pub use pet_source::{builtin_pet_sources, BuiltinPetCatalog, BuiltinPetSource};
 
 pub use agent_source::{CodexSubagentProvider, CodexSubagentProviderOptions};
 pub use hook_source::{CodexHookProvider, CodexHookProviderOptions};