Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Stabilize skill catalogs across executor availability changes (#48353)

vkg-oaie72da2b53805
diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock
index 13f4c2a6a0..f066c8f168 100644
--- a/codex-rs/Cargo.lock
+++ b/codex-rs/Cargo.lock
@@ -4547,6 +4547,7 @@ name = "codex-skills-extension"
version = "0.0.0"
dependencies = [
"assert_matches",
+ "blake3",
"codex-analytics",
"codex-config",
"codex-exec-server",
diff --git a/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs b/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs
index 2a1df2a0ea..aaa4d288fa 100644
--- a/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs
+++ b/codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs
@@ -68,6 +68,8 @@ const SKILL_DESCRIPTION: &str = "Deploy through the selected executor.";
const SKILL_BODY_MARKER: &str = "SELECTED_EXECUTOR_SKILL_BODY";
const LOCAL_SKILL_BODY_MARKER: &str = "COLLIDING_LOCAL_SKILL_BODY";
const NO_SELECTED_SKILLS_MESSAGE: &str = "No selected-environment skills are currently available.";
+const RESTORED_SELECTED_SKILLS_MESSAGE: &str =
+ "The previously listed selected-environment skills are available again.";
const MCP_SERVER_NAME: &str = "executor_probe";
const MCP_CALL_ID: &str = "selected-executor-mcp-call";
const CONNECTOR_ID: &str = "calendar";
@@ -473,6 +475,19 @@ async fn selected_capability_stack_tracks_environment_availability_and_resume()
}
assert_plugin_guidance_count(&requests[4], /*expected_count*/ 0);
assert_selected_skill_is_injected(&requests[5], /*expected_count*/ 2);
+ assert!(
+ latest_selected_skill_update(&requests[5])
+ .is_some_and(|text| text.contains(RESTORED_SELECTED_SKILLS_MESSAGE))
+ );
+ assert_eq!(
+ 1,
+ requests[5]
+ .message_input_texts("developer")
+ .into_iter()
+ .filter(|text| text.contains(SKILL_DESCRIPTION))
+ .count(),
+ "reattaching should retain the original catalog without repeating it"
+ );
assert_selected_plugin_tools(&requests[5]);
let output = requests[2].function_call_output(MCP_CALL_ID);
let output = output["output"]
@@ -1006,9 +1021,14 @@ fn assert_selected_skill_is_injected(request: &ResponsesRequest, expected_count:
}
fn assert_selected_skill_catalog_available(request: &ResponsesRequest) {
- let catalog_fragment = latest_selected_skill_update(request)
- .expect("selected skill catalog update should be model-visible");
- assert!(catalog_fragment.contains(SKILL_DESCRIPTION));
+ let latest_update = latest_selected_skill_update(request)
+ .expect("selected skill availability should be model-visible");
+ assert!(!latest_update.contains(NO_SELECTED_SKILLS_MESSAGE));
+ let catalog_fragment = request
+ .message_input_texts("developer")
+ .into_iter()
+ .rfind(|text| text.contains(SKILL_DESCRIPTION))
+ .expect("the full selected skill catalog should remain in history");
assert!(catalog_fragment.contains("executor package:"));
}
@@ -1016,7 +1036,11 @@ fn latest_selected_skill_update(request: &ResponsesRequest) -> Option<String> {
request
.message_input_texts("developer")
.into_iter()
- .rfind(|text| text.contains(SKILL_DESCRIPTION) || text.contains(NO_SELECTED_SKILLS_MESSAGE))
+ .rfind(|text| {
+ text.contains(SKILL_DESCRIPTION)
+ || text.contains(NO_SELECTED_SKILLS_MESSAGE)
+ || text.contains(RESTORED_SELECTED_SKILLS_MESSAGE)
+ })
}
fn assert_selected_plugin_tools(request: &ResponsesRequest) {
diff --git a/codex-rs/core/src/context/world_state/mod.rs b/codex-rs/core/src/context/world_state/mod.rs
index ef03b15503..1c4441f80e 100644
--- a/codex-rs/core/src/context/world_state/mod.rs
+++ b/codex-rs/core/src/context/world_state/mod.rs
@@ -400,6 +400,7 @@ impl WorldState {
}
/// Renders each section against the exact persisted snapshot when available.
+ #[cfg(test)]
pub(crate) fn render_diff(
&self,
previous: &WorldStateSnapshot,
diff --git a/codex-rs/core/src/context_manager/history.rs b/codex-rs/core/src/context_manager/history.rs
index 7e19dae6b3..44f8c06dfc 100644
--- a/codex-rs/core/src/context_manager/history.rs
+++ b/codex-rs/core/src/context_manager/history.rs
@@ -107,7 +107,8 @@ pub(crate) struct ContextManager {
/// also clear this when it trims a mixed initial-context developer bundle
/// whose non-diff fragments no longer exist in the surviving history.
reference_context_item: Option<TurnContextItem>,
- /// World state most recently appended to model-visible history.
+ /// World-state comparison checkpoint. After compaction this may contain only
+ /// extension metadata, with model-visible context still awaiting reinjection.
world_state_baseline: Option<WorldStateSnapshot>,
}
diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rs
index a04ce2fdf2..4611b155a0 100644
--- a/codex-rs/core/src/session/mod.rs
+++ b/codex-rs/core/src/session/mod.rs
@@ -31,6 +31,7 @@ use crate::context::MultiAgentRoleInstructions;
use crate::context::NetworkRuleSaved;
use crate::context::RecommendedPluginsInstructions;
use crate::context::world_state::WorldState;
+use crate::context::world_state::WorldStateSnapshot;
use crate::current_time::TimeProvider;
use crate::environment_selection::TurnEnvironmentSnapshot;
use crate::exec_policy::BANNED_PREFIX_SUGGESTIONS;
@@ -3689,8 +3690,12 @@ impl Session {
let world_state_item = world_state_snapshot
.merge_patch_from(&previous_snapshot)
.map(WorldStateItem::patch);
+ // A catalog may have left history during compaction even when its snapshot survives.
let items = crate::context_manager::updates::merge_contextual_fragments(
- world_state.render_diff(&previous_snapshot),
+ world_state.render_history_diff(
+ Some(&previous_snapshot),
+ self.state.lock().await.history.raw_items(),
+ ),
);
if !items.is_empty() {
self.record_conversation_items(turn_context, &step_context.settings.model_info, &items)
@@ -4098,10 +4103,23 @@ impl Session {
// Wait for accepted updates to finish persisting, then keep later updates from
// overtaking the current settings snapshot while its checkpoint is written.
let _settings_guard = thread_settings::acquire_persistence_lock(self).await;
- // Compaction starts a new history window, so its WorldState baseline must be full.
+ // A new history window needs a full checkpoint, even when it contains only
+ // extension metadata and model-visible context will be rebuilt on the next turn.
let mut world_state_item = None;
let compacted_item = {
let mut state = self.state.lock().await;
+ let snapshot = world_state_baseline
+ .map(|world_state| world_state.snapshot())
+ .or_else(|| {
+ let previous = state.history.world_state_checkpoint()?;
+ let mut retained = serde_json::Map::new();
+ for contributor in self.services.extensions.context_contributors() {
+ retained.extend(
+ contributor.retain_world_state_after_compaction(&previous.state),
+ );
+ }
+ (!retained.is_empty()).then(|| WorldStateSnapshot::from(&retained))
+ });
state.replace_annotated_history(
items,
reference_context_item.clone(),
@@ -4110,8 +4128,7 @@ impl Session {
},
);
state.reasoning_effort_pin = ReasoningEffortPin::Compacted;
- if let Some(world_state) = world_state_baseline {
- let snapshot = world_state.snapshot();
+ if let Some(snapshot) = snapshot {
world_state_item = Some(WorldStateItem::full(snapshot.clone().into_object()));
state.history.set_world_state_baseline(snapshot);
}
diff --git a/codex-rs/core/src/session/world_state.rs b/codex-rs/core/src/session/world_state.rs
index a50a36acb6..c3c417bacb 100644
--- a/codex-rs/core/src/session/world_state.rs
+++ b/codex-rs/core/src/session/world_state.rs
@@ -290,6 +290,7 @@ impl Session {
.iter()
.map(|root| root.selected_root().clone())
.collect::<Vec<_>>();
+ let previous_world_state = self.state.lock().await.history.world_state_checkpoint();
for contributor in self.services.extensions.context_contributors() {
for section in contributor
.contribute_world_state(WorldStateContributionInput {
@@ -305,6 +306,7 @@ impl Session {
session_store: &self.services.session_extension_data,
thread_store: &self.services.thread_extension_data,
turn_store: turn_context.extension_data.as_ref(),
+ previous_world_state: previous_world_state.as_ref().map(|state| &state.state),
})
.await
{
diff --git a/codex-rs/core/tests/suite/skills_extension.rs b/codex-rs/core/tests/suite/skills_extension.rs
index 833ab2c281..780fe3d3e5 100644
--- a/codex-rs/core/tests/suite/skills_extension.rs
+++ b/codex-rs/core/tests/suite/skills_extension.rs
@@ -11,6 +11,7 @@ use codex_config::ConfigRequirements;
use codex_config::ConfigRequirementsToml;
use codex_core::StartThreadOptions;
use codex_core::TurnInputRequest;
+use codex_core::WaitForEnvironmentToolConfig;
use codex_core::config::Config;
use codex_exec_server::CreateDirectoryOptions;
use codex_exec_server::EnvironmentManager;
@@ -24,6 +25,9 @@ use codex_extension_api::ExtensionWarning;
use codex_extension_api::SkillInvocationContributor;
use codex_extension_api::SkillInvocationInput;
use codex_features::Feature;
+use codex_history::InitialHistory;
+use codex_history::ResumedHistory;
+use codex_history::RolloutItem;
use codex_login::CodexAuth;
use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;
use codex_models_manager::bundled_models_response;
@@ -43,10 +47,12 @@ use codex_protocol::permissions::FileSystemSandboxEntry;
use codex_protocol::permissions::FileSystemSandboxPolicy;
use codex_protocol::permissions::FileSystemSpecialPath;
use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_protocol::protocol::EnvironmentConfigState;
use codex_protocol::protocol::Event;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::Op;
use codex_protocol::protocol::ThreadSettingsOverrides;
+use codex_protocol::protocol::TurnEnvironmentSelection;
use codex_protocol::protocol::TurnSettingsUpdate;
use codex_protocol::protocol::TurnSettingsUpdateOutcome;
use codex_protocol::user_input::UserInput;
@@ -71,11 +77,14 @@ use codex_skills_extension::provider::SkillListQuery;
use codex_skills_extension::provider::SkillProviderFuture;
use codex_skills_extension::provider::SkillReadRequest;
use codex_skills_extension::provider::SkillSearchRequest;
+use codex_thread_store::LoadThreadHistoryParams;
use codex_utils_absolute_path::AbsolutePathBuf;
use codex_utils_path_uri::PathUri;
use codex_utils_string::approx_token_count;
use core_test_support::apps_test_server::AppsTestServer;
use core_test_support::apps_test_server::apps_enabled_builder;
+use core_test_support::context_snapshot;
+use core_test_support::context_snapshot::ContextSnapshotOptions;
use core_test_support::responses;
use core_test_support::responses::ev_completed;
use core_test_support::responses::ev_response_created;
@@ -86,6 +95,7 @@ use core_test_support::skip_if_no_network;
use core_test_support::skip_if_remote;
use core_test_support::skip_if_target_windows;
use core_test_support::skip_if_wine_exec;
+use core_test_support::test_codex::environment_config_for_selection;
use core_test_support::test_codex::test_codex;
use core_test_support::test_codex::test_env;
use core_test_support::test_codex::turn_permission_fields;
@@ -1867,7 +1877,7 @@ async fn executor_skill_invocation_is_environment_scoped_and_deduplicated() -> R
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn production_turn_aliases_combined_skill_catalogs_under_shared_budget() -> Result<()> {
+async fn production_turn_aliases_catalogs_with_separate_cloud_budget() -> Result<()> {
const EXECUTOR_ROOT: &str =
"skill://integration-executor/workspace/plugins/cache/executor-plugin/1.0.0/skills";
const CLOUD_ROOT: &str = "skill://plugin_connector_1p_2330815c823c8191941e5dc465bb899f";
@@ -2856,23 +2866,11 @@ async fn production_turn_keeps_full_executor_only_catalog_when_it_fits() -> Resu
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn production_turn_keeps_cloud_world_state_incremental_across_turns() -> Result<()> {
+async fn production_turn_keeps_rebalanced_catalogs_stable_after_compaction_and_resume() -> Result<()>
+{
let server = responses::start_mock_server().await;
- let response = responses::mount_sse_sequence(
- &server,
- ["resp-1", "resp-2"]
- .into_iter()
- .map(|response_id| {
- sse(vec![
- ev_response_created(response_id),
- ev_completed(response_id),
- ])
- })
- .collect(),
- )
- .await;
let skill_name = "cloud-search";
- let skill_description = "Search available company knowledge.";
+ let skill_description = "Search available company knowledge. ".repeat(40);
let skill_resource = "skill://codex_apps/cloud-search/SKILL.md";
let catalog = SkillCatalog {
entries: vec![
@@ -2880,7 +2878,7 @@ async fn production_turn_keeps_cloud_world_state_incremental_across_turns() -> R
SkillPackageId("cloud/cloud-search".to_string()),
SkillAuthority::new(SkillSourceKind::Cloud, CODEX_APPS_MCP_SERVER_NAME),
skill_name,
- skill_description,
+ skill_description.as_str(),
SkillResourceId::new(skill_resource),
)
.with_display_path(skill_resource),
@@ -2890,7 +2888,11 @@ async fn production_turn_keeps_cloud_world_state_incremental_across_turns() -> R
let mut extensions = ExtensionRegistryBuilder::<Config>::new();
install_with_providers(
&mut extensions,
- SkillProviders::new().with_cloud_provider(Arc::new(CatalogSkillProvider { catalog })),
+ SkillProviders::new()
+ .with_cloud_provider(Arc::new(CatalogSkillProvider { catalog }))
+ .with_executor_provider(Arc::new(CatalogSkillProvider {
+ catalog: executor_catalog(&EXECUTOR_CATALOG),
+ })),
|config: &Config| SkillsExtensionConfig {
include_instructions: config.include_skill_instructions,
max_context_tokens: config.skill_max_context_tokens,
@@ -2900,24 +2902,129 @@ async fn production_turn_keeps_cloud_world_state_incremental_across_turns() -> R
},
);
let mut builder = test_codex()
+ .with_exec_server_url("none")
.with_extensions(Arc::new(extensions.build()))
+ .with_model_info_override("gpt-5.5", |model_info| {
+ model_info.context_window = Some(12_000);
+ model_info.max_context_window = None;
+ })
.with_config(|config| {
configure_catalog_test(config);
config.cloud_skill_enabled = true;
+ config.model_provider.name = "Skills compaction test".to_string();
+ config.model_post_turn_compact_threshold_percent = 50;
+ config
+ .features
+ .enable(Feature::DeferredExecutor)
+ .expect("enable deferred executor");
+ config
+ .features
+ .disable(Feature::ExecutorCapabilityDiscovery)
+ .expect("disable executor capability discovery");
});
- let test = builder.build_with_auto_env(&server).await?;
+ // The executor below runs in this process, so use host-local workspace paths.
+ let test = builder.build(&server).await?;
+ // Use a real remote transport: cloud skills are disabled for local attachments.
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
+ let executor_address = listener.local_addr()?;
+ let executor_url = format!("ws://{executor_address}");
+ drop(listener);
+ let runtime_paths = codex_exec_server::ExecServerRuntimePaths::new(
+ std::env::current_exe()?,
+ /*codex_linux_sandbox_exe*/ None,
+ )?;
+ let http_client_factory = test.config.http_client_factory();
+ let server_url = executor_url.clone();
+ let executor = tokio::spawn(async move {
+ codex_exec_server::run_main(&server_url, runtime_paths, http_client_factory).await
+ });
+ tokio::time::timeout(Duration::from_secs(5), async {
+ while tokio::net::TcpStream::connect(executor_address)
+ .await
+ .is_err()
+ {
+ tokio::task::yield_now().await;
+ }
+ })
+ .await?;
+ test.thread_manager
+ .environment_manager()
+ .upsert_environment(
+ "skills-executor".to_string(),
+ executor_url,
+ /*connect_timeout*/ None,
+ )?;
+ let pending_selection = TurnEnvironmentSelection {
+ environment_id: "skills-executor".to_string(),
+ cwd: PathUri::from_abs_path(&test.config.cwd),
+ workspace_roots: vec![PathUri::from_abs_path(&test.config.cwd)],
+ config: EnvironmentConfigState::Pending,
+ };
+ let mut thread_extension_init = ExtensionDataInit::default();
+ thread_extension_init.insert(WaitForEnvironmentToolConfig {
+ tool_description: "Wait for the selected environment.".to_string(),
+ environment_id_description: "Selected environment ID.".to_string(),
+ });
let cloud_thread = test
.thread_manager
.start_thread(StartThreadOptions {
- environments: Some(Vec::new()),
+ environments: Some(vec![pending_selection.clone()]),
+ thread_extension_init: thread_extension_init.clone(),
..StartThreadOptions::new(test.config.clone())
})
.await?;
+ let response = responses::mount_sse_sequence(
+ &server,
+ vec![
+ sse(vec![
+ ev_response_created("resp-1"),
+ responses::ev_function_call(
+ "wait-for-skills",
+ "wait_for_environment",
+ &json!({ "environment_id": pending_selection.environment_id }).to_string(),
+ ),
+ ev_completed("resp-1"),
+ ]),
+ sse(vec![ev_response_created("resp-2"), ev_completed("resp-2")]),
+ // Cross the post-turn threshold only after the allocation has stabilized.
+ sse(vec![
+ ev_response_created("resp-3"),
+ responses::ev_completed_with_tokens("resp-3", /*total_tokens*/ 7_000),
+ ]),
+ sse(vec![
+ ev_response_created("compact"),
+ responses::ev_assistant_message("summary", "The available skills were inspected."),
+ ev_completed("compact"),
+ ]),
+ sse(vec![
+ ev_response_created("resp-4"),
+ responses::ev_function_call(
+ "wait-for-resumed-skills",
+ "wait_for_environment",
+ &json!({ "environment_id": pending_selection.environment_id }).to_string(),
+ ),
+ ev_completed("resp-4"),
+ ]),
+ sse(vec![ev_response_created("resp-5"), ev_completed("resp-5")]),
+ ],
+ )
+ .await;
- for prompt in [
+ let mut ready_config = environment_config_for_selection(&test.config, &pending_selection);
+ ready_config.selected_capability_roots = vec![SelectedCapabilityRoot {
+ id: "skills".to_string(),
+ location: CapabilityRootLocation::Environment {
+ environment_id: pending_selection.environment_id.clone(),
+ path: pending_selection.cwd.clone(),
+ },
+ }];
+ for (turn_index, prompt) in [
"Inspect the available skills.",
"Inspect the available skills again.",
- ] {
+ ]
+ .into_iter()
+ .enumerate()
+ {
cloud_thread
.thread
.start_or_steer_turn(TurnInputRequest::user_input(vec![UserInput::Text {
@@ -2925,25 +3032,153 @@ async fn production_turn_keeps_cloud_world_state_incremental_across_turns() -> R
text_elements: Vec::new(),
}]))
.await?;
+ if turn_index == 0 {
+ tokio::time::timeout(Duration::from_secs(10), async {
+ while response.requests().is_empty() {
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ })
+ .await?;
+ assert!(
+ cloud_thread
+ .thread
+ .inspect_selected_capability_roots()
+ .ready_roots
+ .is_empty()
+ );
+ cloud_thread
+ .thread
+ .environment_ready(&pending_selection, ready_config.clone())
+ .await?;
+ }
core_test_support::wait_for_event(&cloud_thread.thread, |event| {
matches!(event, EventMsg::TurnComplete(_))
})
.await;
}
+ cloud_thread.thread.shutdown_and_wait().await?;
+ let history = test
+ .thread_store
+ .load_latest_model_context(LoadThreadHistoryParams {
+ thread_id: cloud_thread.session_configured.thread_id,
+ include_archived: true,
+ })
+ .await?;
+ let checkpoint = history
+ .items
+ .iter()
+ .rev()
+ .find_map(|item| match item {
+ RolloutItem::WorldState(checkpoint) => Some(checkpoint),
+ _ => None,
+ })
+ .expect("compaction retains an allocation checkpoint");
+ let allocation = checkpoint.state["cloud_skills"]["allocation"]
+ .as_object()
+ .expect("retained allocation");
+ assert_eq!(
+ serde_json::to_value(checkpoint)?,
+ json!({
+ "full": true,
+ "state": { "cloud_skills": { "allocation": allocation } },
+ }),
+ "compaction retains only allocation metadata, not rendered catalogs",
+ );
+ let resumed = test
+ .thread_manager
+ .start_thread(StartThreadOptions {
+ initial_history: InitialHistory::Resumed(ResumedHistory {
+ conversation_id: history.thread_id,
+ history: Arc::new(history.items),
+ rollout_path: cloud_thread.session_configured.rollout_path.clone(),
+ }),
+ environments: Some(vec![pending_selection.clone()]),
+ thread_extension_init,
+ ..StartThreadOptions::new(test.config.clone())
+ })
+ .await?;
+ resumed
+ .thread
+ .start_or_steer_turn(TurnInputRequest::user_input(vec![UserInput::Text {
+ text: "Inspect the skills after resuming.".to_string(),
+ text_elements: Vec::new(),
+ }]))
+ .await?;
+ tokio::time::timeout(Duration::from_secs(10), async {
+ while response.requests().len() < 5 {
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ })
+ .await?;
+ assert!(
+ resumed
+ .thread
+ .inspect_selected_capability_roots()
+ .ready_roots
+ .is_empty()
+ );
+ resumed
+ .thread
+ .environment_ready(&pending_selection, ready_config)
+ .await?;
+ wait_for_event(&resumed.thread, |event| {
+ matches!(event, EventMsg::TurnComplete(_))
+ })
+ .await;
+ resumed.thread.shutdown_and_wait().await?;
+ executor.abort();
let requests = response.requests();
- assert_eq!(requests.len(), 2);
- let expected_line =
- format!("- {skill_name}: {skill_description} (cloud package: cloud/cloud-search)");
+ assert_eq!(requests.len(), 6);
+ let first_developer_text = requests[0].message_input_texts("developer").join("\n");
+ let expected_line = first_developer_text
+ .lines()
+ .find(|line| line.starts_with("- cloud-search:"))
+ .unwrap_or_else(|| {
+ panic!("pending request should advertise cloud skill: {first_developer_text}")
+ });
+ let ready_developer_text = requests[1].message_input_texts("developer").join("\n");
+ let ready_line = ready_developer_text
+ .lines()
+ .rfind(|line| line.starts_with("- cloud-search:"))
+ .expect("ready cloud catalog");
+ let ready_executor_lines = ready_developer_text
+ .lines()
+ .filter(|line| line.starts_with("- exec-"))
+ .collect::<Vec<_>>();
+ assert_ne!(expected_line, ready_line);
+ assert!(
+ EXECUTOR_CATALOG
+ .iter()
+ .all(|(name, _)| ready_developer_text.contains(&format!("- {name}:")))
+ );
for (index, request) in requests.iter().enumerate() {
let developer_texts = request.message_input_texts("developer");
- let occurrences = developer_texts
+ let cloud_lines = developer_texts
.iter()
- .map(|text| text.matches(&expected_line).count())
- .sum::<usize>();
+ .flat_map(|text| text.lines())
+ .filter(|line| line.starts_with("- cloud-search:"))
+ .collect::<Vec<_>>();
assert_eq!(
- occurrences, 1,
- "request {index} should contain the cloud catalog exactly once: {developer_texts:?}"
+ cloud_lines,
+ match index {
+ 0 => vec![expected_line],
+ 1..=3 => vec![expected_line, ready_line],
+ _ => vec![ready_line],
+ },
+ "request {index} should only append cloud text when rebalancing prevents omissions",
+ );
+ assert_eq!(
+ developer_texts
+ .iter()
+ .flat_map(|text| text.lines())
+ .filter(|line| line.starts_with("- exec-"))
+ .collect::<Vec<_>>(),
+ if matches!(index, 0 | 4) {
+ Vec::new()
+ } else {
+ ready_executor_lines.clone()
+ },
);
assert!(
developer_texts
@@ -2952,6 +3187,17 @@ async fn production_turn_keeps_cloud_world_state_incremental_across_turns() -> R
);
}
+ insta::assert_snapshot!(
+ "cloud_skills_across_executor_readiness",
+ context_snapshot::format_request_history_snapshot(
+ "Cloud skills rebalance once to retain every executor skill. Post-turn compaction and resume restore the same cloud allocation before the executor reconnects; both catalogs are fully reinjected once into the new history.",
+ &requests,
+ &ContextSnapshotOptions::default()
+ .rewrite_known_segments()
+ .include_request_settings(),
+ )
+ );
+
Ok(())
}
diff --git a/codex-rs/core/tests/suite/skills_extension/cloud_skill_tests.rs b/codex-rs/core/tests/suite/skills_extension/cloud_skill_tests.rs
index 08d78329f1..a368661d5a 100644
--- a/codex-rs/core/tests/suite/skills_extension/cloud_skill_tests.rs
+++ b/codex-rs/core/tests/suite/skills_extension/cloud_skill_tests.rs
@@ -509,7 +509,7 @@ async fn production_turn_aliases_discovered_singleton_cloud_root() -> Result<()>
.with_exec_server_url("none")
.with_extensions(Arc::new(extensions.build()))
.with_model_info_override("gpt-5.5", |model_info| {
- model_info.context_window = Some(1_000);
+ model_info.context_window = Some(2_000);
model_info.max_context_window = None;
})
.with_config(|config| {
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__skills_extension__cloud_skills_across_executor_readiness.snap b/codex-rs/core/tests/suite/snapshots/all__suite__skills_extension__cloud_skills_across_executor_readiness.snap
new file mode 100644
index 0000000000..d15989f510
--- /dev/null
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__skills_extension__cloud_skills_across_executor_readiness.snap
@@ -0,0 +1,176 @@
+---
+source: core/tests/suite/skills_extension.rs
+assertion_line: 3190
+expression: "context_snapshot::format_request_history_snapshot(\"Cloud skills rebalance once to retain every executor skill. Post-turn compaction and resume restore the same cloud allocation before the executor reconnects; both catalogs are fully reinjected once into the new history.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"
+---
+Scenario: Cloud skills rebalance once to retain every executor skill. Post-turn compaction and resume restore the same cloud allocation before the executor reconnects; both catalogs are fully reinjected once into the new history.
+
+## Window 1
+Settings:
+ include: ["reasoning.encrypted_content"]
+ instructions: <MODEL_INSTRUCTIONS>
+ model: "gpt-5.5"
+ parallel_tool_calls: true
+ prompt_cache_key: "<PROMPT_CACHE_KEY 1>"
+ reasoning: {"effort":"medium"}
+ store: false
+ stream: true
+ text: {"verbosity":"low"}
+ tool_choice: "auto"
+ tools (5; hash=fb9143ee40054f2b):
+ - function/wait_for_environment: Wait for the selected environment.; args=[environment_id]; hash=aac8552da86b3b20
+ - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6
+ - namespace/skills: Tools in the skills namespace.; hash=998a720eb0f017bc
+ - function/list
+ - function/read
+ - tool_search: # Tool discovery Searches over deferred tool metadata with BM25 and exposes matching tools for t...; args=[limit, query]; hash=400cd6ac61d524a9
+ - web_search; hash=f103e327c6870a46
+-- request 1 (turn) --
+00:message/developer[3]:
+ [01] <PERMISSIONS_INSTRUCTIONS>
+ [02] <environments_instructions>
+ ## Execution environments
+ Execution environments are separate machines or workspaces with their own files, shell, and installed ca...text>` lists the environments selected for this task. [hash=bc910d398b9b4d83]
+
+ An environment marked `starting` is not yet usable. Its files, commands, AGENTS.md instructions, skills,...CP tools may become available when startup completes. [hash=42a360e5075e8edb]
+
+ Wait only when the current task needs that environment. Continue using tools that are already available for unrelated work.
+ </environments_instructions>
+ [03] <SKILLS_INSTRUCTIONS>
+01:message/user:
+ <ENVIRONMENT_CONTEXT>
+02:message/user:
+ Inspect the available skills.
+
+## Window 2 (after request 1)
+Settings: relative to window 1
+ tools (9; hash=1df9146cc32e8188):
+ + function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5
+ + function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2
+ + custom/apply_patch: The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the pat...; hash=dea9f12b0111a4ba
+ + function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[detail, path]; hash=3b766d5bdec5d50e
+-- request 2 (turn) --
+00:message/developer[3]:
+ [01] <PERMISSIONS_INSTRUCTIONS>
+ [02] <environments_instructions>
+ ## Execution environments
+ Execution environments are separate machines or workspaces with their own files, shell, and installed ca...text>` lists the environments selected for this task. [hash=bc910d398b9b4d83]
+
+ An environment marked `starting` is not yet usable. Its files, commands, AGENTS.md instructions, skills,...CP tools may become available when startup completes. [hash=42a360e5075e8edb]
+
+ Wait only when the current task needs that environment. Continue using tools that are already available for unrelated work.
+ </environments_instructions>
+ [03] <SKILLS_INSTRUCTIONS>
+01:message/user:
+ <ENVIRONMENT_CONTEXT>
+02:message/user:
+ Inspect the available skills.
+03:function_call/wait_for_environment:{"environment_id":"skills-executor"}
+04:function_call_output:{"environment_id":"skills-executor","status":"ready"}
+05:message/user:
+ <ENVIRONMENT_CONTEXT>
+06:message/developer[2]:
+ [01] <SKILLS_INSTRUCTIONS>
+ [02] <SKILLS_INSTRUCTIONS>
+-- request 3 (turn) --
+07:message/user:
+ Inspect the available skills again.
+
+## Window 3 (after request 3)
+Settings: relative to window 2
+ parallel_tool_calls: false
+ tools (0; hash=09612b07b5ecb5a5):
+ - removed function/exec_command
+ - removed function/write_stdin
+ - removed function/wait_for_environment
+ - removed function/request_user_input
+ - removed custom/apply_patch
+ - removed function/view_image
+ - removed namespace/skills
+ - removed tool_search
+ - removed web_search
+-- request 4 (compaction) --
+00:message/developer[3]:
+ [01] <PERMISSIONS_INSTRUCTIONS>
+ [02] <environments_instructions>
+ ## Execution environments
+ Execution environments are separate machines or workspaces with their own files, shell, and installed ca...text>` lists the environments selected for this task. [hash=bc910d398b9b4d83]
+
+ An environment marked `starting` is not yet usable. Its files, commands, AGENTS.md instructions, skills,...CP tools may become available when startup completes. [hash=42a360e5075e8edb]
+
+ Wait only when the current task needs that environment. Continue using tools that are already available for unrelated work.
+ </environments_instructions>
+ [03] <SKILLS_INSTRUCTIONS>
+01:message/user:
+ <ENVIRONMENT_CONTEXT>
+02:message/user:
+ Inspect the available skills.
+03:function_call/wait_for_environment:{"environment_id":"skills-executor"}
+04:function_call_output:{"environment_id":"skills-executor","status":"ready"}
+05:message/user:
+ <ENVIRONMENT_CONTEXT>
+06:message/developer[2]:
+ [01] <SKILLS_INSTRUCTIONS>
+ [02] <SKILLS_INSTRUCTIONS>
+07:message/user:
+ Inspect the available skills again.
+08:message/user:
+ <SUMMARIZATION_PROMPT>
+
+## Window 4 (after request 4: input diverged at item 00)
+Settings: same as window 1
+-- request 5 (turn) --
+00:message/user:
+ Inspect the available skills.
+01:message/user:
+ Inspect the available skills again.
+02:message/user:
+ <COMPACTION_SUMMARY>
+ The available skills were inspected.
+03:message/developer[3]:
+ [01] <PERMISSIONS_INSTRUCTIONS>
+ [02] <environments_instructions>
+ ## Execution environments
+ Execution environments are separate machines or workspaces with their own files, shell, and installed ca...text>` lists the environments selected for this task. [hash=bc910d398b9b4d83]
+
+ An environment marked `starting` is not yet usable. Its files, commands, AGENTS.md instructions, skills,...CP tools may become available when startup completes. [hash=42a360e5075e8edb]
+
+ Wait only when the current task needs that environment. Continue using tools that are already available for unrelated work.
+ </environments_instructions>
+ [03] <SKILLS_INSTRUCTIONS>
+04:message/user:
+ <ENVIRONMENT_CONTEXT>
+05:message/user:
+ Inspect the skills after resuming.
+
+## Window 5 (after request 5)
+Settings: same as window 2
+-- request 6 (turn) --
+00:message/user:
+ Inspect the available skills.
+01:message/user:
+ Inspect the available skills again.
+02:message/user:
+ <COMPACTION_SUMMARY>
+ The available skills were inspected.
+03:message/developer[3]:
+ [01] <PERMISSIONS_INSTRUCTIONS>
+ [02] <environments_instructions>
+ ## Execution environments
+ Execution environments are separate machines or workspaces with their own files, shell, and installed ca...text>` lists the environments selected for this task. [hash=bc910d398b9b4d83]
+
+ An environment marked `starting` is not yet usable. Its files, commands, AGENTS.md instructions, skills,...CP tools may become available when startup completes. [hash=42a360e5075e8edb]
+
+ Wait only when the current task needs that environment. Continue using tools that are already available for unrelated work.
+ </environments_instructions>
+ [03] <SKILLS_INSTRUCTIONS>
+04:message/user:
+ <ENVIRONMENT_CONTEXT>
+05:message/user:
+ Inspect the skills after resuming.
+06:function_call/wait_for_environment:{"environment_id":"skills-executor"}
+07:function_call_output:{"environment_id":"skills-executor","status":"ready"}
+08:message/user:
+ <ENVIRONMENT_CONTEXT>
+09:message/developer:
+ <SKILLS_INSTRUCTIONS>
diff --git a/codex-rs/ext/extension-api/src/contributors.rs b/codex-rs/ext/extension-api/src/contributors.rs
index 81711a81de..bb2b162ce0 100644
--- a/codex-rs/ext/extension-api/src/contributors.rs
+++ b/codex-rs/ext/extension-api/src/contributors.rs
@@ -142,6 +142,18 @@ pub trait ContextContributor: Send + Sync {
Vec::new()
})
}
+
+ /// Retains bounded extension metadata when compaction discards rendered context.
+ ///
+ /// Return only this contributor's section IDs, without rendered text or availability
+ /// state. Core persists these partial sections so the next step can rebuild full
+ /// context without losing decisions that are independent of model-visible history.
+ fn retain_world_state_after_compaction(
+ &self,
+ _previous_world_state: &serde_json::Map<String, serde_json::Value>,
+ ) -> serde_json::Map<String, serde_json::Value> {
+ serde_json::Map::new()
+ }
}
/// Contributor for host-owned thread lifecycle gates.
diff --git a/codex-rs/ext/extension-api/src/contributors/world_state.rs b/codex-rs/ext/extension-api/src/contributors/world_state.rs
index c916fac6d0..c2379b8b7f 100644
--- a/codex-rs/ext/extension-api/src/contributors/world_state.rs
+++ b/codex-rs/ext/extension-api/src/contributors/world_state.rs
@@ -26,6 +26,10 @@ pub struct WorldStateContributionInput<'a> {
pub session_store: &'a ExtensionData,
pub thread_store: &'a ExtensionData,
pub turn_store: &'a ExtensionData,
+ /// Persisted comparison state from the last recorded step. Its rendered text may have
+ /// left model history; use a retained-fragment matcher before referring back to it.
+ /// After compaction, sections may contain only retained extension metadata.
+ pub previous_world_state: Option<&'a serde_json::Map<String, Value>>,
}
/// What the harness knows about the previous value of one extension-owned section.
diff --git a/codex-rs/ext/skills/Cargo.toml b/codex-rs/ext/skills/Cargo.toml
index 2b7b1f4032..2891a1a5db 100644
--- a/codex-rs/ext/skills/Cargo.toml
+++ b/codex-rs/ext/skills/Cargo.toml
@@ -13,6 +13,7 @@ doctest = false
workspace = true
[dependencies]
+blake3 = { workspace = true }
codex-analytics = { workspace = true }
codex-config = { workspace = true }
codex-exec-server = { workspace = true }
diff --git a/codex-rs/ext/skills/src/extension.rs b/codex-rs/ext/skills/src/extension.rs
index c49e3d929c..66a881a2b0 100644
--- a/codex-rs/ext/skills/src/extension.rs
+++ b/codex-rs/ext/skills/src/extension.rs
@@ -73,6 +73,7 @@ use crate::tools::SkillAnalytics;
use crate::tools::SkillToolAuthority;
use crate::tools::skill_tools;
use crate::warnings::bounded_warnings;
+use crate::world_state::CLOUD_SKILLS_WORLD_STATE_ID;
use crate::world_state_catalogs::CatalogContext;
use crate::world_state_catalogs::CatalogStatus;
@@ -266,6 +267,25 @@ where
.collect()
})
}
+
+ fn retain_world_state_after_compaction(
+ &self,
+ previous_world_state: &serde_json::Map<String, serde_json::Value>,
+ ) -> serde_json::Map<String, serde_json::Value> {
+ let mut retained = serde_json::Map::new();
+ if let Some(allocation) = previous_world_state
+ .get(CLOUD_SKILLS_WORLD_STATE_ID)
+ .and_then(|section| section.get("allocation"))
+ {
+ // Allocation survives lost history; the catalog fingerprint and budget still
+ // determine whether it can be reused after fresh discovery and policy resolution.
+ retained.insert(
+ CLOUD_SKILLS_WORLD_STATE_ID.to_string(),
+ serde_json::json!({ "allocation": allocation }),
+ );
+ }
+ retained
+ }
}
impl<C> ToolContributor for SkillsExtension<C>
diff --git a/codex-rs/ext/skills/src/render.rs b/codex-rs/ext/skills/src/render.rs
index 9f0bf4c824..ede504ada0 100644
--- a/codex-rs/ext/skills/src/render.rs
+++ b/codex-rs/ext/skills/src/render.rs
@@ -4,6 +4,8 @@ use std::num::NonZeroUsize;
use codex_protocol::protocol::SkillScope;
use codex_utils_string::approx_token_count;
use codex_utils_string::take_bytes_at_char_boundary;
+use serde::Deserialize;
+use serde::Serialize;
use crate::aliases::AliasPlan;
use crate::catalog::SkillCatalog;
@@ -72,7 +74,8 @@ impl SkillCatalogRenderPolicy {
}
}
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
pub(crate) enum SkillMetadataBudget {
Tokens(usize),
Characters(usize),
@@ -157,6 +160,13 @@ fn metadata_line_cost(budget: SkillMetadataBudget, line: &str) -> usize {
}
impl SkillMetadataBudget {
+ pub(crate) fn with_limit(self, limit: usize) -> Self {
+ match self {
+ Self::Tokens(_) => Self::Tokens(limit),
+ Self::Characters(_) => Self::Characters(limit),
+ }
+ }
+
pub(crate) fn limit(self) -> usize {
match self {
Self::Tokens(limit) | Self::Characters(limit) => limit,
@@ -465,6 +475,27 @@ pub(crate) struct RenderedSkillCatalogs {
}
impl AvailableSkillsRender {
+ /// Count the metadata charged by the allocator, including aliases and omission notices.
+ pub(crate) fn metadata_cost(
+ &self,
+ budget: SkillMetadataBudget,
+ include_skills_usage_instructions: bool,
+ ) -> usize {
+ let root_cost = if self.skill_root_lines.is_empty() {
+ 0
+ } else {
+ aliased_metadata_overhead_cost(
+ budget,
+ self.prompt_kind,
+ &self.skill_root_lines,
+ include_skills_usage_instructions,
+ )
+ };
+ self.skill_lines.iter().fold(root_cost, |used, line| {
+ used.saturating_add(metadata_line_cost(budget, line))
+ })
+ }
+
pub(crate) fn into_fragment(
self,
include_skills_usage_instructions: bool,
@@ -862,22 +893,7 @@ fn combined_available_skills_cost(
[&rendered.executor, &rendered.cloud, &rendered.host]
.into_iter()
.fold(0usize, |used, catalog| {
- let root_cost = if !catalog.skill_root_lines.is_empty() {
- aliased_metadata_overhead_cost(
- budget,
- catalog.prompt_kind,
- &catalog.skill_root_lines,
- include_skills_usage_instructions,
- )
- } else {
- Default::default()
- };
- catalog
- .skill_lines
- .iter()
- .fold(used.saturating_add(root_cost), |used, line| {
- used.saturating_add(metadata_line_cost(budget, line))
- })
+ used.saturating_add(catalog.metadata_cost(budget, include_skills_usage_instructions))
})
}
diff --git a/codex-rs/ext/skills/src/world_state.rs b/codex-rs/ext/skills/src/world_state.rs
index a90c020231..31a9bd80bb 100644
--- a/codex-rs/ext/skills/src/world_state.rs
+++ b/codex-rs/ext/skills/src/world_state.rs
@@ -3,9 +3,11 @@ use codex_extension_api::RenderedWorldStateFragment;
use codex_extension_api::WorldStateSectionContribution;
use codex_protocol::protocol::SKILLS_INSTRUCTIONS_CLOSE_TAG;
use codex_protocol::protocol::SKILLS_INSTRUCTIONS_OPEN_TAG;
+use serde::Serialize;
use serde_json::json;
use crate::render::SkillRenderReport;
+use crate::world_state_catalogs::CatalogBudgetAllocation;
pub(crate) const SKILLS_WORLD_STATE_ID: &str = "skills";
pub(crate) const CLOUD_SKILLS_WORLD_STATE_ID: &str = "cloud_skills";
@@ -23,38 +25,111 @@ const OMITTED_HOST_SKILLS_BODY: &str = "\n## Host skills update\nHost skills are
pub(crate) type CatalogRenderCallback = Box<dyn Fn() + Send + Sync>;
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct CatalogSnapshot {
+ body: Option<String>,
+ include_instructions: bool,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ enabled: Option<bool>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ allocation: Option<CatalogBudgetAllocation>,
+}
+
pub(crate) fn executor_skills_world_state_section(
body: Option<String>,
include_instructions: bool,
+ previous_snapshot: Option<&serde_json::Value>,
on_render: CatalogRenderCallback,
) -> WorldStateSectionContribution {
- skills_world_state_section(
+ // Remember display history, not execution authority. Discovery still determines `body`
+ // on every step, including when no selected-environment skills are available.
+ let last_available_fingerprint = previous_snapshot
+ .filter(|_| body.is_none() && include_instructions)
+ .and_then(|previous| {
+ previous
+ .get("body")
+ .and_then(serde_json::Value::as_str)
+ .map(|body| blake3::hash(body.as_bytes()).to_hex().to_string())
+ .or_else(|| {
+ previous
+ .get("lastAvailableFingerprint")
+ .and_then(serde_json::Value::as_str)
+ .map(str::to_string)
+ })
+ });
+ let snapshot = json!({
+ "body": body,
+ "includeInstructions": include_instructions,
+ "lastAvailableFingerprint": last_available_fingerprint,
+ });
+ let retained_body = body.clone();
+ let contribution = WorldStateSectionContribution::new(
SKILLS_WORLD_STATE_ID,
- body,
- include_instructions,
- /*enabled*/ None,
- NO_EXECUTOR_SKILLS_BODY,
- HIDDEN_EXECUTOR_SKILLS_BODY,
- on_render,
+ snapshot,
+ move |previous| {
+ if let PreviousWorldStateSection::Known(previous) = &previous
+ && previous.get("includeInstructions").and_then(serde_json::Value::as_bool)
+ == Some(include_instructions)
+ {
+ if previous.get("body").and_then(serde_json::Value::as_str) == body.as_deref() {
+ return None;
+ }
+ if let Some(body) = body.as_deref()
+ && previous.get("lastAvailableFingerprint").and_then(serde_json::Value::as_str)
+ == Some(blake3::hash(body.as_bytes()).to_hex().as_str())
+ {
+ return Some(RenderedWorldStateFragment::new(
+ "developer",
+ (SKILLS_INSTRUCTIONS_OPEN_TAG, SKILLS_INSTRUCTIONS_CLOSE_TAG),
+ "\n## Skills update\nThe previously listed selected-environment skills are available again.\n",
+ ));
+ }
+ }
+
+ let body = match body.as_deref() {
+ Some(body) => body,
+ None if matches!(previous, PreviousWorldStateSection::Absent) => return None,
+ None if !include_instructions => HIDDEN_EXECUTOR_SKILLS_BODY,
+ None => NO_EXECUTOR_SKILLS_BODY,
+ };
+ on_render();
+ Some(RenderedWorldStateFragment::new(
+ "developer",
+ (SKILLS_INSTRUCTIONS_OPEN_TAG, SKILLS_INSTRUCTIONS_CLOSE_TAG),
+ body,
+ ))
+ },
)
.with_legacy_matcher(|role, text| {
role == "developer"
&& text.trim_start().starts_with(SKILLS_INSTRUCTIONS_OPEN_TAG)
&& text.trim_end().ends_with(SKILLS_INSTRUCTIONS_CLOSE_TAG)
- })
+ });
+ // A short availability update is valid only while the actual catalog remains in history.
+ match retained_body {
+ Some(body) => contribution.with_retained_fragment_matcher(move |role, text| {
+ role == "developer" && text.contains(&body)
+ }),
+ None => contribution,
+ }
}
pub(crate) fn cloud_skills_world_state_section(
body: Option<String>,
include_instructions: bool,
enabled: bool,
+ allocation: CatalogBudgetAllocation,
on_render: CatalogRenderCallback,
) -> WorldStateSectionContribution {
skills_world_state_section(
CLOUD_SKILLS_WORLD_STATE_ID,
- body,
- include_instructions,
- Some(enabled),
+ CatalogSnapshot {
+ body,
+ include_instructions,
+ enabled: Some(enabled),
+ allocation: Some(allocation),
+ },
NO_CLOUD_SKILLS_BODY,
if enabled {
HIDDEN_CLOUD_SKILLS_BODY
@@ -67,20 +142,18 @@ pub(crate) fn cloud_skills_world_state_section(
fn skills_world_state_section(
id: &'static str,
- body: Option<String>,
- include_instructions: bool,
- enabled: Option<bool>,
+ state: CatalogSnapshot,
no_skills_body: &'static str,
hidden_skills_body: &'static str,
on_render: CatalogRenderCallback,
) -> WorldStateSectionContribution {
- let mut snapshot = json!({
- "body": body,
- "includeInstructions": include_instructions,
- });
- if let Some(enabled) = enabled {
- snapshot["enabled"] = json!(enabled);
- }
+ let snapshot = json!(&state);
+ let CatalogSnapshot {
+ body,
+ include_instructions,
+ enabled,
+ ..
+ } = state;
let retained_body = body.clone();
let contribution = WorldStateSectionContribution::new(id, snapshot, move |previous| {
@@ -136,9 +209,12 @@ pub(crate) fn host_skills_world_state_section(
let contribution = skills_world_state_section(
HOST_SKILLS_WORLD_STATE_ID,
- body,
- include_instructions,
- /*enabled*/ None,
+ CatalogSnapshot {
+ body,
+ include_instructions,
+ enabled: None,
+ allocation: None,
+ },
NO_HOST_SKILLS_BODY,
HIDDEN_HOST_SKILLS_BODY,
on_render,
diff --git a/codex-rs/ext/skills/src/world_state_catalogs.rs b/codex-rs/ext/skills/src/world_state_catalogs.rs
index 92303a456d..fc3feccff8 100644
--- a/codex-rs/ext/skills/src/world_state_catalogs.rs
+++ b/codex-rs/ext/skills/src/world_state_catalogs.rs
@@ -6,6 +6,8 @@ use codex_extension_api::ExtensionWarning;
use codex_extension_api::SelectedPluginSnapshot;
use codex_extension_api::WorldStateContributionInput;
use codex_extension_api::WorldStateSectionContribution;
+use serde::Deserialize;
+use serde::Serialize;
use crate::HostSkillsSnapshot;
use crate::SkillsExtensionConfig;
@@ -14,7 +16,9 @@ use crate::provider::SkillListQuery;
use crate::provider::attribute_executor_plugins;
use crate::render::AvailableSkillsRender;
use crate::render::RenderedSkillCatalogs;
+use crate::render::SkillCatalogRenderPolicy;
use crate::render::SkillMetadataBudget;
+use crate::render::render_available_skills;
use crate::render::render_combined_available_skills;
use crate::render::skill_metadata_budget;
use crate::render_observability::CatalogSurface;
@@ -31,6 +35,20 @@ use crate::world_state::cloud_skills_world_state_section;
use crate::world_state::executor_skills_world_state_section;
use crate::world_state::host_skills_world_state_section;
+// Start with one quarter reserved for filesystem skills, before their inventory is known.
+const FILESYSTEM_BUDGET_DIVISOR: usize = 4;
+
+/// A display allocation retained across executor readiness changes and thread resume.
+/// A changed cloud catalog or total budget starts a new allocation. Within that
+/// allocation, filesystem pressure can only shrink the cloud cap.
+#[derive(Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct CatalogBudgetAllocation {
+ total_budget: SkillMetadataBudget,
+ cloud_limit: usize,
+ cloud_catalog_fingerprint: [u8; 32],
+}
+
type CatalogWarningEmitter = Arc<dyn Fn(String) + Send + Sync>;
#[derive(Clone, Copy, Eq, PartialEq)]
@@ -80,6 +98,8 @@ pub(crate) struct CatalogContributions {
pub(crate) struct RenderedCatalogContribution {
kind: CatalogKind,
pub(crate) status: CatalogStatus,
+ budget: SkillMetadataBudget,
+ allocation: CatalogBudgetAllocation,
rendered: Option<AvailableSkillsRender>,
}
@@ -243,17 +263,59 @@ impl<'a> CatalogContext<'a> {
&self,
catalogs: CatalogContributions,
) -> [RenderedCatalogContribution; 3] {
- let rendered = if self.config.include_instructions {
- render_combined_available_skills(
- &catalogs.executor.catalog,
- &catalogs.cloud.catalog,
- &catalogs.host.catalog,
- self.metadata_budget,
- self.include_usage,
- )
- } else {
- RenderedSkillCatalogs::default()
- };
+ let total_limit = self.metadata_budget.limit();
+ let default_cloud_limit = total_limit - total_limit / FILESYSTEM_BUDGET_DIVISOR;
+ // Identify the full visible cloud inventory before budgeting, including entries
+ // a previous cap omitted. Executor readiness and provider warnings are not inputs.
+ let cloud_metadata = catalogs
+ .cloud
+ .catalog
+ .entries
+ .iter()
+ .filter(|entry| entry.is_model_visible())
+ .map(|entry| {
+ (
+ &entry.id.0,
+ entry.authority.kind.to_string(),
+ &entry.name,
+ entry
+ .short_description
+ .as_ref()
+ .unwrap_or(&entry.description),
+ entry.rendered_path(),
+ entry.alias_root(),
+ entry.alias_root_order(),
+ )
+ })
+ .collect::<Vec<_>>();
+ let cloud_catalog_fingerprint =
+ *blake3::hash(serde_json::json!(cloud_metadata).to_string().as_bytes()).as_bytes();
+ let mut allocation = self
+ .input
+ .previous_world_state
+ .and_then(|state| state.get(crate::world_state::CLOUD_SKILLS_WORLD_STATE_ID))
+ .and_then(|snapshot| snapshot.get("allocation"))
+ .and_then(|value| serde_json::from_value::<CatalogBudgetAllocation>(value.clone()).ok())
+ .filter(|previous| {
+ previous.total_budget == self.metadata_budget
+ && previous.cloud_catalog_fingerprint == cloud_catalog_fingerprint
+ })
+ .unwrap_or(CatalogBudgetAllocation {
+ total_budget: self.metadata_budget,
+ cloud_limit: default_cloud_limit,
+ cloud_catalog_fingerprint,
+ });
+ allocation.cloud_limit = allocation.cloud_limit.min(default_cloud_limit);
+ let (mut rendered, mut filesystem_budget) =
+ self.render_with_cloud_limit(&catalogs, allocation.cloud_limit);
+
+ if let Some(cloud_limit) =
+ self.rebalance_to_retain_all_skills(&catalogs, &rendered, allocation.cloud_limit)
+ {
+ allocation.cloud_limit = cloud_limit;
+ (rendered, filesystem_budget) =
+ self.render_with_cloud_limit(&catalogs, allocation.cloud_limit);
+ }
[
(CatalogKind::Executor, catalogs.executor, rendered.executor),
@@ -263,10 +325,91 @@ impl<'a> CatalogContext<'a> {
.map(|(kind, catalog, rendered)| RenderedCatalogContribution {
kind,
status: catalog.status,
+ budget: match kind {
+ CatalogKind::Cloud => self.metadata_budget.with_limit(allocation.cloud_limit),
+ CatalogKind::Executor | CatalogKind::Host => filesystem_budget,
+ },
+ allocation,
rendered,
})
}
+ /// Propose a smaller cloud cap only when omitted filesystem entries can fit without
+ /// losing any cloud entries. Description truncation alone never triggers rebalancing.
+ /// Within one cloud catalog and total budget, the cap can only shrink, so VM
+ /// disappearance does not expand the catalog.
+ fn rebalance_to_retain_all_skills(
+ &self,
+ catalogs: &CatalogContributions,
+ rendered: &RenderedSkillCatalogs,
+ current_cloud_limit: usize,
+ ) -> Option<usize> {
+ if ![&rendered.executor, &rendered.host]
+ .into_iter()
+ .flatten()
+ .any(|catalog| catalog.report.omitted_count > 0)
+ {
+ return None;
+ }
+
+ let shared = render_combined_available_skills(
+ &catalogs.executor.catalog,
+ &catalogs.cloud.catalog,
+ &catalogs.host.catalog,
+ self.metadata_budget,
+ self.include_usage,
+ );
+ if [&shared.executor, &shared.cloud, &shared.host]
+ .into_iter()
+ .flatten()
+ .any(|catalog| catalog.report.omitted_count > 0)
+ {
+ return None;
+ }
+
+ let cloud_limit = shared.cloud.as_ref().map_or(0, |cloud| {
+ cloud.metadata_cost(self.metadata_budget, self.include_usage)
+ });
+ (cloud_limit < current_cloud_limit).then_some(cloud_limit)
+ }
+
+ /// Render the same buckets both before and after adjusting the allocation, so
+ /// the accepted cloud text is reproduced exactly on the next sampling step.
+ fn render_with_cloud_limit(
+ &self,
+ catalogs: &CatalogContributions,
+ cloud_limit: usize,
+ ) -> (RenderedSkillCatalogs, SkillMetadataBudget) {
+ if !self.config.include_instructions {
+ return (RenderedSkillCatalogs::default(), self.metadata_budget);
+ }
+
+ let cloud_budget = self.metadata_budget.with_limit(cloud_limit);
+ let cloud = render_available_skills(
+ &catalogs.cloud.catalog,
+ SkillCatalogRenderPolicy::ExtensionCompatible,
+ cloud_budget,
+ self.include_usage,
+ );
+ // Empty or disabled cloud catalogs leave the full allowance to filesystem skills.
+ let cloud_cost = cloud.as_ref().map_or(0, |rendered| {
+ rendered.metadata_cost(cloud_budget, self.include_usage)
+ });
+ let filesystem_budget = self
+ .metadata_budget
+ .with_limit(self.metadata_budget.limit().saturating_sub(cloud_cost));
+ let mut rendered = render_combined_available_skills(
+ &catalogs.executor.catalog,
+ &SkillCatalog::default(),
+ &catalogs.host.catalog,
+ filesystem_budget,
+ self.include_usage,
+ );
+ rendered.cloud = cloud;
+
+ (rendered, filesystem_budget)
+ }
+
pub(crate) fn build_world_state_section(
&self,
catalog: RenderedCatalogContribution,
@@ -274,6 +417,8 @@ impl<'a> CatalogContext<'a> {
let RenderedCatalogContribution {
kind,
status,
+ budget,
+ allocation,
rendered,
} = catalog;
let report = rendered
@@ -286,7 +431,6 @@ impl<'a> CatalogContext<'a> {
let include_instructions = self.config.include_instructions;
let metrics = self.input.extension_metrics.clone();
let warning_emitter = Arc::clone(&self.warning_emitter);
- let metadata_budget = self.metadata_budget;
let render_report = report.clone();
let on_render: CatalogRenderCallback = Box::new(move || {
if !include_instructions || status != CatalogStatus::Enabled {
@@ -296,7 +440,7 @@ impl<'a> CatalogContext<'a> {
record_catalog_render(
metrics.as_deref(),
kind.metrics_surface(),
- metadata_budget,
+ budget,
&render_report,
);
if let Some(message) = render_report.warning_message() {
@@ -305,13 +449,19 @@ impl<'a> CatalogContext<'a> {
});
match kind {
- CatalogKind::Executor => {
- executor_skills_world_state_section(body, include_instructions, on_render)
- }
+ CatalogKind::Executor => executor_skills_world_state_section(
+ body,
+ include_instructions,
+ self.input
+ .previous_world_state
+ .and_then(|state| state.get(crate::world_state::SKILLS_WORLD_STATE_ID)),
+ on_render,
+ ),
CatalogKind::Cloud => cloud_skills_world_state_section(
body,
include_instructions,
status == CatalogStatus::Enabled,
+ allocation,
on_render,
),
CatalogKind::Host => {
diff --git a/codex-rs/ext/skills/tests/skills_extension.rs b/codex-rs/ext/skills/tests/skills_extension.rs
index 674b28f5a5..f980b7e4a0 100644
--- a/codex-rs/ext/skills/tests/skills_extension.rs
+++ b/codex-rs/ext/skills/tests/skills_extension.rs
@@ -129,6 +129,7 @@ async fn skill_world_state_fragments(
}];
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id,
@@ -313,6 +314,7 @@ async fn host_world_state_records_catalog_metrics_on_publish_and_change() -> Tes
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -340,6 +342,7 @@ async fn host_world_state_records_catalog_metrics_on_publish_and_change() -> Tes
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -377,6 +380,7 @@ async fn host_world_state_records_catalog_metrics_on_publish_and_change() -> Tes
turn_store.insert(HostSkillsSnapshot::new(Arc::new(outcome)));
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -448,6 +452,7 @@ async fn persisted_host_snapshot_deduplicates_warning_after_reinitialization() -
turn_store.insert(host_snapshot.clone());
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &model_info,
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -489,6 +494,7 @@ async fn persisted_host_snapshot_deduplicates_warning_after_reinitialization() -
resumed_turn_store.insert(host_snapshot);
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &model_info,
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-2",
@@ -579,6 +585,7 @@ async fn executor_cloud_and_host_share_catalog_world_state_flow() -> TestResult
let metrics = Arc::new(RecordingMetrics::default());
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -687,6 +694,7 @@ async fn nonempty_executor_empty_host_records_catalog_metrics() -> TestResult {
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -765,6 +773,7 @@ async fn host_world_state_uses_provider_catalog_with_core_compatible_rendering()
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -845,6 +854,7 @@ async fn shadow_selection_uses_host_catalog_when_instructions_are_disabled() ->
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -1103,6 +1113,7 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
};
let available_sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -1156,9 +1167,12 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
)],
read_request_keys(&read_requests)
);
+ let available_world_state =
+ serde_json::Map::from_iter([("skills".to_string(), available_snapshot.clone())]);
let unavailable_turn_store = ExtensionData::new("turn-2");
let unavailable_sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: Some(&available_world_state),
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-2",
@@ -1172,6 +1186,16 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
})
.await;
let unavailable_snapshot = unavailable_sections[0].snapshot().clone();
+ assert_eq!(
+ unavailable_snapshot,
+ serde_json::json!({
+ "body": null,
+ "includeInstructions": true,
+ "lastAvailableFingerprint": blake3::hash(
+ available_snapshot["body"].as_str().ok_or("available catalog")?.as_bytes()
+ ).to_hex().to_string(),
+ }),
+ );
let unavailable_fragment = unavailable_sections[0]
.render_diff(PreviousWorldStateSection::Known(&available_snapshot))
.ok_or("removed skills should render")?;
@@ -1181,9 +1205,12 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
.contains("No selected-environment skills")
);
+ let unavailable_world_state =
+ serde_json::Map::from_iter([("skills".to_string(), unavailable_snapshot.clone())]);
let restored_turn_store = ExtensionData::new("turn-3");
let restored_sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: Some(&unavailable_world_state),
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-3",
@@ -1200,7 +1227,18 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
let restored_fragment = restored_sections[0]
.render_diff(PreviousWorldStateSection::Known(&unavailable_snapshot))
.ok_or("restored skills should render")?;
- assert!(restored_fragment.body().contains("lint-fix"));
+ assert_eq!(
+ restored_fragment.body(),
+ "\n## Skills update\nThe previously listed selected-environment skills are available again.\n",
+ );
+ assert!(restored_sections[0].matches_retained_fragment("developer", available_fragment.body()));
+ assert!(
+ !restored_sections[0].matches_retained_fragment("developer", unavailable_fragment.body())
+ );
+ assert_eq!(
+ restored_sections[0].render_diff(PreviousWorldStateSection::Absent),
+ Some(available_fragment),
+ );
assert_eq!(1, list_calls.load(Ordering::Relaxed));
let failed_discovery = ExecutorCapabilityDiscoverySnapshot::new(
@@ -1228,6 +1266,7 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
] {
registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id,
@@ -1254,6 +1293,7 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
let listing_disabled_turn_store = ExtensionData::new("turn-4");
let listing_disabled_sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-4",
@@ -1292,13 +1332,20 @@ async fn selected_executor_catalog_follows_step_availability_and_reuses_its_cach
#[tokio::test]
async fn default_context_truncates_catalog_descriptions() -> TestResult {
let description = "x".repeat(1_025);
- let mut executor_entry = test_entry(
- SkillSourceKind::Executor,
- "env-1",
- "executor/executor-long-description",
- "skill://executor/executor-long-description/SKILL.md",
- );
- executor_entry.description = description.clone();
+ // A small cloud catalog leaves its unused allowance to filesystem descriptions.
+ let executor_entries = (0..5)
+ .map(|index| {
+ let package_id = format!("executor/executor-long-description-{index}");
+ let mut entry = test_entry(
+ SkillSourceKind::Executor,
+ "env-1",
+ &package_id,
+ &format!("skill://{package_id}/SKILL.md"),
+ );
+ entry.description = description.clone();
+ entry
+ })
+ .collect();
let mut cloud_entry = test_entry(
SkillSourceKind::Cloud,
"codex_apps",
@@ -1309,7 +1356,7 @@ async fn default_context_truncates_catalog_descriptions() -> TestResult {
let providers = SkillProviders::new()
.with_executor_provider(Arc::new(StaticSkillProvider {
catalog: SkillCatalog {
- entries: vec![executor_entry],
+ entries: executor_entries,
warnings: Vec::new(),
},
read_requests: Arc::new(Mutex::new(Vec::new())),
@@ -1348,10 +1395,15 @@ async fn default_context_truncates_catalog_descriptions() -> TestResult {
let (executor, cloud) =
skill_world_state_fragments(&registry, &session_store, &thread_store, "turn-1").await?;
- assert!(executor.body().contains("- executor-long-description:"));
+ let expected_description = "x".repeat(1_021) + "...";
+ for index in 0..5 {
+ assert!(executor.body().contains(&format!(
+ "- executor-long-description-{index}: {expected_description} (executor package:"
+ )));
+ }
assert!(cloud.body().contains("- cloud-long-description:"));
for rendered in [executor.body(), cloud.body()] {
- assert!(rendered.contains(&("x".repeat(1_021) + "...")));
+ assert!(rendered.contains(&expected_description));
assert!(!rendered.contains(&"x".repeat(1_024)));
assert!(!rendered.contains(&description));
}
@@ -1360,115 +1412,252 @@ async fn default_context_truncates_catalog_descriptions() -> TestResult {
}
#[tokio::test]
-async fn moderate_budget_pressure_keeps_every_catalog_entry() -> TestResult {
- let description = "x".repeat(1_025);
- let executor_entries = (0..5)
- .map(|index| {
- let package_id = format!("executor/executor-skill-{index:02}");
- let mut entry = test_entry(
- SkillSourceKind::Executor,
- "env-1",
- &package_id,
- &format!("skill://{package_id}/SKILL.md"),
- );
- entry.description = description.clone();
- entry
- })
- .collect();
- let cloud_entries = (0..5)
- .map(|index| {
- let package_id = format!("cloud/cloud-skill-{index:02}");
- let mut entry = test_entry(
- SkillSourceKind::Cloud,
- "codex_apps",
- &package_id,
- &format!("skill://{package_id}/SKILL.md"),
- );
- entry.description = description.clone();
- entry
- })
- .collect();
- let providers = SkillProviders::new()
- .with_executor_provider(Arc::new(StaticSkillProvider {
- catalog: SkillCatalog {
- entries: executor_entries,
- warnings: Vec::new(),
- },
- read_requests: Arc::new(Mutex::new(Vec::new())),
- list_calls: None,
- fail_first_list: false,
- }))
- .with_cloud_provider(Arc::new(StaticSkillProvider {
- catalog: SkillCatalog {
- entries: cloud_entries,
- warnings: Vec::new(),
- },
- read_requests: Arc::new(Mutex::new(Vec::new())),
- list_calls: None,
- fail_first_list: false,
- }));
- let mut builder = ExtensionRegistryBuilder::new();
- install_with_providers(&mut builder, providers, skills_extension_config);
- let registry = builder.build();
- let session_store = ExtensionData::new("session");
- let thread_store = ExtensionData::new("thread");
- let session_source = SessionSource::Cli;
- let config = default_config();
- registry.thread_lifecycle_contributors()[0]
- .on_thread_start(ThreadStartInput {
- config: &config,
- session_source: &session_source,
- persistent_thread_state_available: true,
- environments: &[],
- mcp_resource_client: None,
- extension_metrics: None,
- session_store: &session_store,
- thread_store: &thread_store,
- })
- .await;
- start_registered_turn(&registry, &session_store, &thread_store, "turn-1").await;
+async fn catalog_rebalances_only_to_avoid_omissions_and_retains_the_allocation() -> TestResult {
+ enum Phase {
+ Initial,
+ FirstReady,
+ Disconnected,
+ Reconnected,
+ Resumed,
+ CloudCatalogGrew,
+ BudgetChanged,
+ }
- let (executor, cloud) =
- skill_world_state_fragments(&registry, &session_store, &thread_store, "turn-1").await?;
- let description_lengths = [("executor", executor.body()), ("cloud", cloud.body())]
- .into_iter()
- .flat_map(|(source, rendered)| (0..5).map(move |index| (source, rendered, index)))
- .map(|(source, rendered, index)| {
- let name = format!("{source}-skill-{index:02}");
- let package_id = format!("{source}/{name}");
- let line_prefix = format!("- {name}: ");
- let line_suffix = if source == "executor" {
- format!(" (executor package: {package_id})")
- } else {
- format!(" (cloud package: {package_id})")
- };
- rendered
- .lines()
- .find_map(|line| {
- line.strip_prefix(&line_prefix)
- .and_then(|line| line.strip_suffix(&line_suffix))
+ // Description-only pressure, filesystem omissions that can be rescued, and
+ // unavoidable omissions. Check both token and fallback character accounting.
+ for (executor_count, cloud_count, rebalance, all_fit) in [
+ (17, 82, false, true),
+ (40, 5, true, true),
+ (40, 160, false, false),
+ ] {
+ for context_window in [None, Some(100_000)] {
+ let description = "x".repeat(1_025);
+ let executor_entries: Vec<_> = (0..executor_count)
+ .map(|index| {
+ let package_id = format!("executor/executor-skill-{index:02}");
+ let mut entry = test_entry(
+ SkillSourceKind::Executor,
+ "env-1",
+ &package_id,
+ &format!("skill://{package_id}/SKILL.md"),
+ );
+ entry.description = description.clone();
+ entry
})
- .unwrap_or_else(|| panic!("rendered catalog should include {name}"))
- .chars()
- .count()
- })
- .collect::<Vec<_>>();
- let shortest_description = *description_lengths
- .iter()
- .min()
- .expect("catalog should include descriptions");
- let longest_description = *description_lengths
- .iter()
- .max()
- .expect("catalog should include descriptions");
- assert!(shortest_description > 0);
- assert!(longest_description < 1_024);
- assert!(longest_description.abs_diff(shortest_description) <= 1);
- for rendered in [executor.body(), cloud.body()] {
- assert!(!rendered.contains("additional skills omitted from this bounded skills list"));
- assert!(!rendered.contains(&"x".repeat(1_021)));
- }
+ .collect();
+ let registry_for_cloud_count = |cloud_count| {
+ let cloud_entries = (0..cloud_count)
+ .map(|index| {
+ let package_id = format!("cloud/cloud-skill-{index:02}");
+ let mut entry = test_entry(
+ SkillSourceKind::Cloud,
+ "codex_apps",
+ &package_id,
+ &format!("skill://{package_id}/SKILL.md"),
+ );
+ entry.description = description.clone();
+ entry
+ })
+ .collect();
+ let providers = SkillProviders::new()
+ .with_executor_provider(Arc::new(StaticSkillProvider {
+ catalog: SkillCatalog {
+ entries: executor_entries.clone(),
+ warnings: Vec::new(),
+ },
+ read_requests: Arc::new(Mutex::new(Vec::new())),
+ list_calls: None,
+ fail_first_list: false,
+ }))
+ .with_cloud_provider(Arc::new(StaticSkillProvider {
+ catalog: SkillCatalog {
+ entries: cloud_entries,
+ warnings: Vec::new(),
+ },
+ read_requests: Arc::new(Mutex::new(Vec::new())),
+ list_calls: None,
+ fail_first_list: false,
+ }));
+ let mut builder = ExtensionRegistryBuilder::new();
+ install_with_providers(&mut builder, providers, skills_extension_config);
+ builder.build()
+ };
+ let mut registry = registry_for_cloud_count(cloud_count);
+ let selected_roots = [SelectedCapabilityRoot {
+ id: "skills".to_string(),
+ location: CapabilityRootLocation::Environment {
+ environment_id: "env-1".to_string(),
+ path: PathUri::parse("file:///skills")?,
+ },
+ }];
+ let mut model = ModelInfo {
+ context_window,
+ ..catalog_model_info()
+ };
+ let session_store = ExtensionData::new("session");
+ let mut thread_store = ExtensionData::new("thread");
+ let mut previous = serde_json::Map::new();
+ let mut initial_cloud = None;
+ let mut accepted_cloud = None;
+ let mut phases = vec![
+ Phase::Initial,
+ Phase::FirstReady,
+ Phase::Disconnected,
+ Phase::Reconnected,
+ Phase::Disconnected,
+ Phase::Reconnected,
+ Phase::Resumed,
+ ];
+ if rebalance {
+ phases.extend([
+ Phase::CloudCatalogGrew,
+ Phase::Disconnected,
+ Phase::Reconnected,
+ Phase::Resumed,
+ ]);
+ }
+ phases.push(Phase::BudgetChanged);
+ for (step, phase) in phases.into_iter().enumerate() {
+ if matches!(phase, Phase::CloudCatalogGrew) {
+ // Refresh the cloud inventory on resume while retaining the saved allocation.
+ registry = registry_for_cloud_count(/*cloud_count*/ 15);
+ }
+ if matches!(
+ phase,
+ Phase::Initial | Phase::Resumed | Phase::CloudCatalogGrew
+ ) {
+ thread_store = ExtensionData::new("thread");
+ registry.thread_lifecycle_contributors()[0]
+ .on_thread_start(ThreadStartInput {
+ config: &default_config(),
+ session_source: &SessionSource::Cli,
+ persistent_thread_state_available: true,
+ environments: &[],
+ mcp_resource_client: None,
+ extension_metrics: None,
+ session_store: &session_store,
+ thread_store: &thread_store,
+ })
+ .await;
+ }
+ if matches!(phase, Phase::BudgetChanged) {
+ model.context_window = Some(200_000);
+ }
+ let ready = matches!(
+ phase,
+ Phase::FirstReady
+ | Phase::Reconnected
+ | Phase::Resumed
+ | Phase::CloudCatalogGrew
+ );
+ let turn_id = format!("turn-{step}");
+ let turn_store = ExtensionData::new(&turn_id);
+ start_registered_turn(&registry, &session_store, &thread_store, &turn_id).await;
+ let sections = registry.context_contributors()[0]
+ .contribute_world_state(WorldStateContributionInput {
+ previous_world_state: Some(&previous),
+ model_info: &model,
+ thread_id: codex_protocol::ThreadId::new(),
+ turn_id: &turn_id,
+ environments: &[],
+ ready_selected_capability_roots: if ready { &selected_roots } else { &[] },
+ executor_capability_discovery: None,
+ extension_metrics: None,
+ session_store: &session_store,
+ thread_store: &thread_store,
+ turn_store: &turn_store,
+ })
+ .await;
+ let cloud = world_state_section(&sections, "cloud_skills");
+ let cloud_body = cloud.snapshot()["body"].as_str().ok_or("cloud catalog")?;
+ match phase {
+ Phase::Initial => initial_cloud = Some(cloud_body.to_string()),
+ Phase::FirstReady => {
+ assert_eq!(initial_cloud.as_deref() != Some(cloud_body), rebalance);
+ accepted_cloud = Some(cloud.snapshot().clone());
+ let executor = world_state_section(&sections, "skills");
+ let executor_body = executor.snapshot()["body"]
+ .as_str()
+ .ok_or("executor catalog")?;
+ assert_eq!(
+ executor_body
+ .lines()
+ .filter(|line| line.starts_with("- executor-skill-"))
+ .count()
+ == executor_count,
+ all_fit
+ );
+ if all_fit {
+ assert_eq!(
+ cloud_body
+ .lines()
+ .filter(|line| line.starts_with("- cloud-skill-"))
+ .count(),
+ cloud_count
+ );
+ }
+ }
+ Phase::CloudCatalogGrew => {
+ let allocation = &cloud.snapshot()["allocation"];
+ let previous_limit = previous["cloud_skills"]["allocation"]["cloudLimit"]
+ .as_u64()
+ .ok_or("previous cloud limit")?;
+ assert!(
+ allocation["cloudLimit"].as_u64().ok_or("cloud limit")?
+ > previous_limit
+ );
+ assert_ne!(
+ allocation["cloudCatalogFingerprint"],
+ previous["cloud_skills"]["allocation"]["cloudCatalogFingerprint"]
+ );
+ assert_eq!(
+ cloud_body
+ .lines()
+ .filter(|line| line.starts_with("- cloud-skill-"))
+ .count(),
+ 15
+ );
+ let executor = world_state_section(&sections, "skills");
+ assert_eq!(
+ executor.snapshot()["body"]
+ .as_str()
+ .ok_or("executor catalog")?
+ .lines()
+ .filter(|line| line.starts_with("- executor-skill-"))
+ .count(),
+ executor_count
+ );
+ accepted_cloud = Some(cloud.snapshot().clone());
+ }
+ Phase::Disconnected | Phase::Reconnected | Phase::Resumed => {
+ assert_eq!(Some(cloud.snapshot()), accepted_cloud.as_ref());
+ assert!(
+ cloud
+ .render_diff(PreviousWorldStateSection::Known(
+ &previous["cloud_skills"]
+ ))
+ .is_none()
+ );
+ }
+ Phase::BudgetChanged => {
+ // A genuinely different total budget starts a new allocation.
+ assert_eq!(
+ cloud.snapshot()["allocation"],
+ serde_json::json!({
+ "totalBudget": {"tokens": 4_000}, "cloudLimit": 3_000,
+ "cloudCatalogFingerprint": previous["cloud_skills"]["allocation"]["cloudCatalogFingerprint"],
+ })
+ );
+ }
+ }
+ previous = sections
+ .iter()
+ .map(|section| (section.id().to_string(), section.snapshot().clone()))
+ .collect();
+ }
+ }
+ }
Ok(())
}
@@ -1554,34 +1743,34 @@ async fn extreme_budget_pressure_removes_descriptions_before_omitting_entries()
.lines()
.filter(|line| line.starts_with("- cloud-skill-"))
.count();
- assert_eq!(40, included_executor_count);
+ assert!(included_executor_count > 0);
+ assert!(included_executor_count < 40);
assert!(included_cloud_count > 0);
assert!(included_cloud_count < 160);
assert!(
executor
.body()
- .contains("- executor-skill-039: (executor package:")
+ .contains("- executor-skill-000: (executor package:")
);
assert!(cloud.body().contains("- cloud-skill-000: (cloud package:"));
assert!(!cloud.body().contains("- cloud-skill-159:"));
- for rendered in [executor.body(), cloud.body()] {
+ for (total, included, rendered) in [
+ (40, included_executor_count, executor.body()),
+ (160, included_cloud_count, cloud.body()),
+ ] {
assert!(!rendered.contains("description-"));
+ assert!(rendered.contains("additional skills omitted from this bounded skills list"));
+ let omitted_count = total - included;
+ let warning = event_rx.try_recv()?.into_warning();
+ assert_eq!(warning.thread_id, "thread");
+ assert_eq!(warning.turn_id.as_deref(), Some("turn-1"));
+ assert_eq!(
+ warning.message,
+ format!(
+ "Exceeded skills context budget. All skill descriptions were removed and {omitted_count} additional skills were not included in the model-visible skills list."
+ )
+ );
}
- assert!(
- cloud
- .body()
- .contains("additional skills omitted from this bounded skills list")
- );
- let omitted_count = 200 - included_executor_count - included_cloud_count;
- let warning = event_rx.try_recv()?.into_warning();
- assert_eq!(warning.thread_id, "thread");
- assert_eq!(warning.turn_id.as_deref(), Some("turn-1"));
- assert_eq!(
- warning.message,
- format!(
- "Exceeded skills context budget. All skill descriptions were removed and {omitted_count} additional skills were not included in the model-visible skills list."
- )
- );
assert!(event_rx.try_recv().is_err());
Ok(())
@@ -1988,6 +2177,7 @@ async fn root_qualified_locator_selects_only_the_matching_executor_skill() -> Te
let turn_store = ExtensionData::new("turn-1");
registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -2117,6 +2307,7 @@ async fn model_context_window_scales_executor_and_cloud_catalogs() -> TestResult
let turn_store = ExtensionData::new("turn-1");
let sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &model_info,
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -2132,6 +2323,7 @@ async fn model_context_window_scales_executor_and_cloud_catalogs() -> TestResult
// Core rebuilds world state before each sampling step.
let _repeated_sections = registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &model_info,
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",
@@ -2228,6 +2420,7 @@ async fn executor_catalog_emits_at_most_four_warnings() -> TestResult {
registry.context_contributors()[0]
.contribute_world_state(WorldStateContributionInput {
+ previous_world_state: None,
model_info: &catalog_model_info(),
thread_id: codex_protocol::ThreadId::new(),
turn_id: "turn-1",