Plugin and connector ecosystem management

fn is_openai_curated_marketplace_name(marketplace_name: &str) -> bool

Purpose: This function checks whether a given marketplace name is one of the OpenAI-curated marketplace names known to this crate. It gives the rest of the system one shared place to make that decision, instead of scattering string comparisons throughout the code.

Data flow: It takes a marketplace name as text. It compares that text against the two constants that count as OpenAI-curated marketplace names. It returns true if the input matches either one, and false otherwise; it does not change any stored data.

Call relations: Other plugin or marketplace code can call this when it needs to branch based on whether a marketplace is OpenAI-curated. The function does its check directly using the constants in this file and does not hand work off to other functions.

fn plugin(&self) -> &ResolvedPlugin

Purpose: This returns the resolved plugin description without exposing where it came from. Code uses it when it only needs to know what the plugin is, not how to read more files from it.

Data flow: It receives a ResolvedExecutorPlugin object → looks inside it at the stored ResolvedPlugin → returns a borrowed view of that plugin description. It does not change anything.

Call relations: After a plugin has been resolved and bound to an executor filesystem, the loading flow calls this to get the plugin descriptor. It is the read-only doorway from the bound wrapper back to the ordinary plugin information.

Call graph: called by 1 (load).

fn file_system(&self) -> &dyn ExecutorFileSystem

Purpose: This returns the exact environment filesystem that was used to resolve the plugin. Code uses it so any later file reads happen in the same environment, not accidentally on the host machine or another filesystem.

Data flow: It receives a ResolvedExecutorPlugin object → looks inside it at the stored shared filesystem reference → returns it as an ExecutorFileSystem interface. It does not create, copy, or modify the filesystem.

Call relations: The loading flow calls this alongside ResolvedExecutorPlugin::plugin. Together they give the loader both halves it needs: the plugin description and the filesystem that should be trusted for reading the plugin package.

Call graph: called by 1 (load).

fn new(environment_manager: Arc<EnvironmentManager>) -> Self

Purpose: This creates a plugin provider backed by the current set of execution environments. It is used during setup so later plugin resolution can ask the right environment for files.

Data flow: It receives a shared EnvironmentManager → stores it inside a new ExecutorPluginProvider → returns that provider. Nothing is inspected yet; this only wires the provider to the environment registry.

Call relations: Tests and setup code call this before resolving plugins. Later, ExecutorPluginProvider::resolve_bound and ExecutorPluginProvider::resolve use the stored EnvironmentManager to find the environment named by a selected capability root.

Call graph: called by 6 (host_and_executor_sources_parse_the_same_manifest, executor_root_must_be_an_explicit_absolute_path, malformed_preferred_manifest_does_not_fall_through_to_alternate, standalone_capability_root_is_not_a_plugin, unavailable_environment_does_not_fall_back_to_host_filesystem, new).

async fn resolve_bound(
        &self,
        selected_root: &SelectedCapabilityRoot,
    ) -> Result<Option<ResolvedExecutorPlugin>, ExecutorPluginProviderError>

Purpose: This is the full resolver for environment-owned plugins. It returns not only the plugin description, but also the exact filesystem that was used to find it, so later loading stays tied to the same environment.

Data flow: It receives a selected capability root → checks and converts its path with selected_plugin_root → reads the environment id from the root → asks the EnvironmentManager for that environment → gets the environment filesystem → passes the root and filesystem to resolve_plugin_root → returns either no plugin, a ResolvedExecutorPlugin containing the descriptor and filesystem, or a clear error.

Call relations: This is the central path used when caller code needs a plugin plus its filesystem. ExecutorPluginProvider::resolve calls it and then discards the filesystem, while resolve_snapshot uses it when it needs the bound filesystem for later package access.

Call graph: calls 2 internal fn (resolve_plugin_root, selected_plugin_root); called by 2 (resolve, resolve_snapshot).

async fn resolve(
        &self,
        selected_root: &SelectedCapabilityRoot,
    ) -> Result<Option<ResolvedPlugin>, Self::Error>

Purpose: This implements the general PluginProvider interface, which asks only for a plugin description. It adapts the richer environment-specific resolver into the simpler plugin-provider shape.

Data flow: It receives a selected capability root → calls ExecutorPluginProvider::resolve_bound → if a bound plugin is found, it takes out just the ResolvedPlugin → returns that plugin, no plugin, or the same error from the deeper resolver.

Call relations: This is the standard entry point for code that treats all plugin providers the same way. It delegates the real work to resolve_bound, because this provider still needs the environment-aware checks and filesystem lookup even when the caller only wants the final descriptor.

Call graph: calls 1 internal fn (resolve_bound).

fn selected_plugin_root(
    selected_root: &SelectedCapabilityRoot,
) -> Result<AbsolutePathBuf, ExecutorPluginProviderError>

Purpose: This validates the selected root path and turns it into the project’s safe absolute-path type. It prevents relative or malformed paths from being treated as plugin roots.

Data flow: It receives a SelectedCapabilityRoot → reads its id and environment path → converts the path text into a PathBuf → rejects it if it is not absolute → asks AbsolutePathBuf::from_absolute_path_checked to confirm it is a valid absolute path → returns the checked path or an InvalidRootPath error with the root id and reason.

Call relations: ExecutorPluginProvider::resolve_bound calls this before touching any environment filesystem. This keeps the rest of the resolver working with a trusted absolute path instead of raw user-provided path text.

Call graph: calls 1 internal fn (from_absolute_path_checked); called by 1 (resolve_bound); 1 external calls (from).

async fn resolve_plugin_root(
    selected_root: &SelectedCapabilityRoot,
    plugin_root: AbsolutePathBuf,
    file_system: &dyn ExecutorFileSystem,
) -> Result<Option<ResolvedPlugin>, ExecutorPlugin

Purpose: This inspects one candidate plugin directory inside an environment and, if it contains a valid manifest, turns it into a ResolvedPlugin. It is where the actual discovery and manifest reading happens.

Data flow: It receives the selected root, a checked absolute plugin root path, and an environment filesystem → converts paths to path URIs, which are filesystem-friendly path identifiers → checks that the root exists and is a directory → tries each known manifest location → ignores missing manifest candidates → reads the first manifest file it finds → parses the manifest text → builds a ResolvedPlugin tied to the environment id and root id → returns that plugin, no plugin if no manifest exists, or a detailed error if inspection, reading, parsing, or descriptor construction fails.

Call relations: ExecutorPluginProvider::resolve_bound calls this after it has already found the right environment and filesystem. This function hands off manifest parsing to parse_plugin_manifest and descriptor creation to ResolvedPlugin::from_environment, while all file inspection and file reading go through the provided ExecutorFileSystem.

Call graph: calls 5 internal fn (parse_plugin_manifest, read_file_text, from_environment, join, from_abs_path); called by 1 (resolve_bound); 1 external calls (get_metadata).

fn load_plugin_manifest(plugin_root: &Path) -> Option<PluginManifest>

Purpose: Finds and loads a plugin manifest from the local filesystem. It is the public entry point for callers that have a plugin folder and want the parsed plugin description, or None if it cannot be found or safely read.

Data flow: It receives a plugin root folder path. It asks the plugin utility code to find the manifest file, reads that file as text, and passes the text to parse_plugin_manifest. If parsing succeeds, it returns the cleaned manifest; if finding, reading, or parsing fails, it returns nothing and logs a warning for parse errors.

Call relations: Many plugin-loading paths call this when they need information about a plugin, including loading MCP servers, apps, telemetry metadata, marketplace details, and tests. It delegates the real interpretation work to parse_plugin_manifest after it has found and read the file.

Call graph: calls 1 internal fn (parse_plugin_manifest); called by 12 (load_declared_plugin_mcp_servers, load_plugin, load_plugin_apps, plugin_telemetry_metadata_from_root, load_sources, read_plugin_detail_for_marketplace_plugin, host_and_executor_sources_parse_the_same_manifest, load_manifest, resolve_marketplace_plugin_entry, extract_remote_plugin_bundle_to_path (+2 more)); 3 external calls (find_plugin_manifest_path, read_to_string, warn!).

fn parse_plugin_manifest(
    plugin_root: &Path,
    manifest_path: &Path,
    contents: &str,
) -> Result<PluginManifest, serde_json::Error>

Purpose: Turns the raw JSON contents of a manifest into the official PluginManifest used by the rest of the system. It fills in small conveniences, cleans optional text, and resolves plugin-relative paths into safe absolute paths.

Data flow: It receives the plugin root, the manifest file path, and the manifest text. It deserializes the JSON, chooses a name, trims the version, builds the optional interface section, validates default prompts, resolves asset and feature paths, and returns a structured manifest or a JSON parsing error.

Call relations: It is called by load_plugin_manifest after file reading, and by plugin-root resolution code that already has manifest contents. It calls the path and hook helper functions so every path-like field is checked in the same way before being handed to other plugin subsystems.

Call graph: calls 3 internal fn (resolve_manifest_hooks, resolve_manifest_path, resolve_manifest_path_value); called by 3 (load_plugin_manifest, resolve_plugin_root, plugin_root_resolution_uses_supplied_executor_file_system); 1 external calls (file_name).

fn resolve_manifest_hooks(
    plugin_root: &Path,
    hooks: Option<RawPluginManifestHooks>,
) -> Option<PluginManifestHooks>

Purpose: Interprets the manifest's hooks field, which can be written in several supported forms. Hooks are plugin-provided actions or rules, and this function accepts either paths to hook files or inline hook definitions.

Data flow: It receives the plugin root and the raw hooks value. If the value is a string or list of strings, it validates each path and returns hook paths. If it is an object or list of objects, it returns inline hook definitions. If the value has the wrong shape or all paths are invalid, it logs a warning or returns nothing.

Call relations: It is used only by parse_plugin_manifest while building the manifest's paths section. For path-based hooks it hands each path to resolve_manifest_path, so hooks follow the same “stay inside the plugin folder” rule as other manifest paths.

Call graph: calls 1 internal fn (resolve_manifest_path); called by 1 (parse_plugin_manifest); 4 external calls (Inline, Paths, warn!, vec!).

fn resolve_interface_asset_path(
    plugin_root: &Path,
    field: &'static str,
    path: Option<&str>,
) -> Option<AbsolutePathBuf>

Purpose: Resolves a user-interface asset path, such as an icon, logo, or screenshot, into a safe absolute path. It exists as a small named wrapper so interface asset fields are treated consistently.

Data flow: It receives the plugin root, the name of the manifest field being checked, and an optional path string. It passes those directly to resolve_manifest_path and returns the validated absolute path, or nothing if the input is absent or invalid.

Call relations: It is used while parse_plugin_manifest builds the optional interface section. It relies on resolve_manifest_path for the actual validation and conversion.

Call graph: calls 1 internal fn (resolve_manifest_path).

fn resolve_default_prompts(
    manifest_path: &Path,
    value: Option<&RawPluginManifestDefaultPrompt>,
) -> Option<Vec<String>>

Purpose: Cleans and validates the plugin's suggested starter prompts shown to users. It supports both the old single-string format and the newer list format.

Data flow: It receives the manifest file path and the raw default prompt value. A single string becomes a one-item list after cleanup. A list is checked item by item, with invalid entries skipped, and no more than three prompts accepted. If the whole value has the wrong shape or no valid prompts remain, it returns nothing.

Call relations: It is called from parse_plugin_manifest while building the interface data. It calls resolve_default_prompt_str for each candidate prompt and uses warn_invalid_default_prompt whenever a prompt is missing, too long, empty, or the wrong type.

Call graph: calls 2 internal fn (resolve_default_prompt_str, warn_invalid_default_prompt); 2 external calls (new, format!).

fn resolve_default_prompt_str(manifest_path: &Path, field: &str, prompt: &str) -> Option<String>

Purpose: Normalizes one default prompt and checks that it is usable. This keeps suggested prompts short and clean before they appear in the interface.

Data flow: It receives the manifest path, the field name for error messages, and the prompt text. It collapses repeated whitespace into single spaces, rejects an empty result, rejects text longer than the allowed limit, and returns the cleaned prompt if valid.

Call relations: It is called by resolve_default_prompts for both single prompts and list entries. When a prompt is invalid, it calls warn_invalid_default_prompt so the problem is visible without stopping the whole manifest from loading.

Call graph: calls 1 internal fn (warn_invalid_default_prompt); called by 1 (resolve_default_prompts); 1 external calls (format!).

fn warn_invalid_default_prompt(manifest_path: &Path, field: &str, message: &str)

Purpose: Writes a warning explaining why a default prompt was ignored. This gives plugin authors a useful clue without making the entire plugin fail to load.

Data flow: It receives the manifest path, the field name, and a short reason. It sends a warning to the tracing log and does not return any data.

Call relations: It is used by resolve_default_prompts and resolve_default_prompt_str whenever default prompt data is malformed, empty, too long, or beyond the supported count.

Call graph: called by 2 (resolve_default_prompt_str, resolve_default_prompts); 1 external calls (warn!).

fn json_value_type(value: &JsonValue) -> &'static str

Purpose: Describes a JSON value's broad type in plain words, such as string, array, or object. It is used to make warning messages clearer.

Data flow: It receives a JSON value. It checks which JSON category the value belongs to and returns a static text label for that category.

Call relations: It supports the warning paths in manifest parsing, especially when fields such as hooks, paths, or default prompts have the wrong kind of JSON value.

fn resolve_manifest_path_value(
    plugin_root: &Path,
    field: &'static str,
    path: Option<&RawPluginManifestPath>,
) -> Option<AbsolutePathBuf>

Purpose: Validates a manifest field that should be a single path string, while gracefully ignoring values of the wrong JSON type. This is used for fields like skills that have a stricter expected shape.

Data flow: It receives the plugin root, the manifest field name, and the raw path value. If the value is a string, it passes it to resolve_manifest_path. If the value is not a string, it logs what type was found and returns nothing.

Call relations: It is called by parse_plugin_manifest for path fields represented by the raw path enum. It depends on resolve_manifest_path for the actual safety checks.

Call graph: calls 1 internal fn (resolve_manifest_path); called by 1 (parse_plugin_manifest); 1 external calls (warn!).

fn resolve_manifest_path(
    plugin_root: &Path,
    field: &'static str,
    path: Option<&str>,
) -> Option<AbsolutePathBuf>

Purpose: Converts a plugin-relative manifest path into a safe absolute path inside the plugin folder. This is the main guardrail that prevents manifest paths from escaping the plugin root.

Data flow: It receives the plugin root, a field name for warnings, and an optional path string. Empty paths are ignored. Valid paths must start with ./, must name something after that prefix, and must not contain .. or special components that leave the plugin folder. A valid relative path is joined to the plugin root and returned as an absolute path.

Call relations: It is the shared path checker used by parse_plugin_manifest, resolve_interface_asset_path, resolve_manifest_hooks, and resolve_manifest_path_value. Because all these callers go through the same helper, skills, MCP server files, app files, hooks, icons, logos, and screenshots all follow the same safety rule.

Call graph: calls 1 internal fn (try_from); called by 4 (parse_plugin_manifest, resolve_interface_asset_path, resolve_manifest_hooks, resolve_manifest_path_value); 4 external calls (join, new, new, warn!).

fn write_manifest(plugin_root: &Path, version: Option<&str>, interface: &str)

Purpose: Creates a test plugin manifest at the normal .codex-plugin/plugin.json location. It lets tests quickly set up different manifest contents without repeating file-writing code.

Data flow: It receives a plugin root, an optional version string, and an interface JSON snippet. It creates the manifest directory, builds a JSON file containing a fixed plugin name plus the requested fields, and writes it to disk.

Call relations: The manifest parsing tests call this before loading a plugin. It feeds controlled input into tests::load_manifest or load_plugin_manifest so each test can check one behavior.

Call graph: 4 external calls (join, format!, create_dir_all, write).

fn write_alternate_plugin_manifest(plugin_root: &Path, contents: &str)

Purpose: Creates a test manifest at an alternate discoverable path. This verifies that plugin discovery can find more than the primary .codex-plugin/plugin.json location.

Data flow: It receives a plugin root and raw manifest text. It creates the parent directory for the alternate manifest path and writes the provided contents there.

Call relations: It is used by the alternate-path test, which then calls tests::load_manifest to prove that load_plugin_manifest can discover and parse that location.

Call graph: 3 external calls (join, create_dir_all, write).

fn load_manifest(plugin_root: &Path) -> PluginManifest

Purpose: Loads a manifest during tests and fails the test if loading returns nothing. It keeps test code short when a manifest is expected to be valid.

Data flow: It receives a plugin root path. It calls load_plugin_manifest, unwraps the successful result, and returns the parsed manifest to the test.

Call relations: Most tests in this module use it after writing a temporary manifest. It is a thin testing wrapper around the real public loading function.

Call graph: calls 1 internal fn (load_plugin_manifest).

fn plugin_interface_accepts_legacy_default_prompt_string()

Purpose: Checks that a plugin can still use the older single-string defaultPrompt format. This protects backward compatibility for existing plugin manifests.

Data flow: The test creates a temporary plugin with a default prompt containing extra spaces. It loads the manifest and checks that the interface contains one cleaned prompt with the extra spacing removed.

Call relations: It uses tests::write_manifest to create input and tests::load_manifest to run the real loader. It indirectly exercises resolve_default_prompts and resolve_default_prompt_str.

Call graph: 4 external calls (assert_eq!, load_manifest, write_manifest, tempdir).

fn plugin_interface_normalizes_default_prompt_array()

Purpose: Checks that a list of default prompts is cleaned, filtered, and capped correctly. This proves that bad entries do not poison the whole list.

Data flow: The test writes a manifest with a prompt array containing valid strings, a number, an overlong string, an empty string, and more entries than allowed. It loads the manifest and checks that only the first three valid cleaned prompts remain.

Call relations: It uses the test manifest writer and loader, then verifies the behavior implemented by resolve_default_prompts, including item validation and the maximum prompt count.

Call graph: 5 external calls (assert_eq!, load_manifest, write_manifest, format!, tempdir).

fn plugin_interface_ignores_invalid_default_prompt_shape()

Purpose: Checks that an object-shaped defaultPrompt is ignored because only a string or an array of strings is supported. This keeps malformed manifest data from becoming confusing user-facing text.

Data flow: The test writes a manifest where defaultPrompt is an object. After loading, it checks that the interface has no default prompts.

Call relations: It sets up input with tests::write_manifest and loads through tests::load_manifest. It specifically exercises the invalid-value branch of resolve_default_prompts.

Call graph: 4 external calls (assert_eq!, load_manifest, write_manifest, tempdir).

fn plugin_manifest_reads_trimmed_version()

Purpose: Checks that version strings are trimmed before being stored. This prevents accidental spaces in JSON from becoming part of the plugin version.

Data flow: The test writes a manifest with a version surrounded by spaces. It loads the manifest and checks that the stored version contains only the meaningful version text.

Call relations: It uses the normal test manifest setup and loading helper. It verifies the version cleanup done inside parse_plugin_manifest.

Call graph: 4 external calls (assert_eq!, load_manifest, write_manifest, tempdir).

fn plugin_manifest_reads_keywords()

Purpose: Checks that the manifest's keyword list is preserved. Keywords help describe or categorize plugins, so this test ensures they survive parsing.

Data flow: The test writes a manifest containing two keywords. It loads the manifest and compares the parsed keyword list to the expected strings.

Call relations: It writes the file directly rather than using the shared helper because the test focuses on keywords instead of the interface section. It still uses tests::load_manifest, which exercises the real loader.

Call graph: 5 external calls (assert_eq!, load_manifest, create_dir_all, write, tempdir).

fn plugin_manifest_uses_alternate_discoverable_path()

Purpose: Checks that a manifest can be loaded from an alternate supported location. This matters for compatibility with plugin layouts that do not use the main Codex manifest folder.

Data flow: The test creates a temporary plugin with a manifest at the alternate path, including a spaced version and display name. It loads the manifest and checks that the version is trimmed and the interface display name is read.

Call relations: It uses tests::write_alternate_plugin_manifest to create the alternate file and tests::load_manifest to run normal discovery through load_plugin_manifest.

Call graph: 4 external calls (assert_eq!, load_manifest, write_alternate_plugin_manifest, tempdir).

async fn host_and_executor_sources_parse_the_same_manifest()

Purpose: Checks that the host-side loader and executor-side plugin provider agree on the same plugin manifest. This prevents two parts of the system from interpreting the same plugin differently.

Data flow: The test writes a plugin manifest, loads it directly through load_plugin_manifest, then asks an executor plugin provider to resolve the same plugin root. It builds the expected resolved plugin descriptor and checks that the executor result matches it.

Call relations: It calls the real loader and also goes through ExecutorPluginProvider. This ties the manifest parser to the wider plugin-resolution flow and guards against host/executor drift.

Call graph: calls 5 internal fn (load_plugin_manifest, new, default_for_tests, from_environment, from_absolute_path_checked); 4 external calls (new, assert_eq!, write_manifest, tempdir).

fn apps_route_available(auth_mode: Option<AuthMode>) -> bool

Purpose: This function answers a simple yes-or-no question: can app-based routing be used with the current authentication mode? It returns true only when there is an authentication mode and that mode uses the Codex backend.

Data flow: It receives an optional authentication mode. If there is no mode, the answer is false. If there is a mode, it asks that mode whether it uses the Codex backend, and returns that answer.

Call relations: This is the small gatekeeper used by the broader routing policy in apply_app_mcp_routing_policy. It is also called during plugin MCP server loading so other setup code can make the same decision consistently.

Call graph: called by 2 (apply_app_mcp_routing_policy, load_plugin_mcp_servers).

fn apply_app_mcp_routing_policy(
    apps: &mut Vec<AppDeclaration>,
    mcp_servers: &mut HashMap<String, M>,
    auth_mode: Option<AuthMode>,
    plugin_active: bool,
)

Purpose: This function applies the project’s rules for when plugin apps and MCP server entries should be kept or removed. It protects users from unusable app entries and avoids duplicate routes for the same plugin.

Data flow: It receives a mutable list of app declarations, a mutable map of MCP servers keyed by name, the current authentication mode, and a flag saying whether the plugin feature is active. First it checks whether app routing is available. If not, it clears the app list. If app routing is available, the plugin feature is active, and there are app declarations, it collects the app names and removes any MCP server with a matching name. The result is that the two collections are changed in place to match the routing policy.

Call relations: Several plugin-loading paths call this function after they have gathered app declarations and MCP server entries. It first delegates the basic availability check to apps_route_available, then edits the app and server lists so later code sees only the routes that should actually be exposed.

Call graph: calls 1 internal fn (apps_route_available); called by 4 (load_plugin_mcp_servers, read_plugin_detail_for_marketplace_plugin, resolve_loaded_plugins_for_auth, build_remote_plugin_detail).

fn from(value: MarketplacePluginInstallPolicy) -> Self

Purpose: Converts this file’s marketplace install policy into the install policy type used by the app-server protocol. This lets the marketplace layer speak cleanly to the API layer without exposing its own internal enum everywhere.

Data flow: It receives one marketplace install policy value, matches it to the equivalent protocol value, and returns that new value. Nothing else is changed.

Call relations: This is a small adapter used when marketplace information needs to be sent through the app-server protocol. It sits at the boundary between internal marketplace data and externally shared protocol data.

fn from(value: MarketplacePluginAuthPolicy) -> Self

Purpose: Converts this file’s marketplace authentication policy into the authentication policy type used by the app-server protocol. It keeps the internal marketplace model separate from the wire-facing API model.

Data flow: It receives one marketplace authentication policy value, chooses the matching protocol value, and returns it. It has no side effects.

Call relations: This function is used as a boundary translator when plugin marketplace policy is exposed through the app-server protocol.

fn io(context: &'static str, source: io::Error) -> Self

Purpose: Builds a marketplace error from a lower-level input/output error, such as a failed file read. It adds a short human context string so the final error message explains what Codex was trying to do.

Data flow: It takes a fixed context message and an operating-system file error, wraps them into a MarketplaceError::Io, and returns that error value.

Call relations: Other functions use this helper when disk operations fail and they want marketplace-specific error messages instead of raw file-system errors.

fn find_marketplace_plugin(
    marketplace_path: &AbsolutePathBuf,
    plugin_name: &str,
) -> Result<ResolvedMarketplacePlugin, MarketplaceError>

Purpose: Looks inside one marketplace file for a plugin with a specific name and returns a fully interpreted plugin record. It is used when another part of Codex knows the marketplace and plugin name and needs the real source, policy, and metadata.

Data flow: It receives a marketplace file path and a plugin name. It reads the raw marketplace JSON, scans the plugin list, resolves the matching entry into a safer internal form, and returns that resolved plugin. If no matching usable entry is found, it returns a clear PluginNotFound error.

Call relations: This function starts by calling load_raw_marketplace_manifest to read the catalog, then hands a candidate entry to resolve_marketplace_plugin_entry to interpret it. It is called by configuration-reading code and by find_installable_marketplace_plugin, which adds install eligibility checks afterward.

Call graph: calls 2 internal fn (load_raw_marketplace_manifest, resolve_marketplace_plugin_entry); called by 2 (read_plugin_for_config, find_installable_marketplace_plugin).

fn find_installable_marketplace_plugin(
    marketplace_path: &AbsolutePathBuf,
    plugin_name: &str,
    restriction_product: Option<Product>,
) -> Result<ResolvedMarketplacePlugin, MarketplaceError

Purpose: Finds a plugin in a marketplace and checks whether it is allowed to be installed. This protects installation flows from installing plugins that the marketplace marks as unavailable or not allowed for the current product.

Data flow: It receives a marketplace path, a plugin name, and an optional product restriction. It first gets the resolved plugin, then checks the plugin’s install policy and product allow-list. It returns the plugin if installation is allowed, or a PluginNotAvailable error if not.

Call relations: This builds directly on find_marketplace_plugin. Plugin installation paths call it before installing, so policy checks happen before any install work begins.

Call graph: calls 1 internal fn (find_marketplace_plugin); called by 2 (install_plugin, install_plugin_with_remote_sync).

fn list_marketplaces(
    additional_roots: &[AbsolutePathBuf],
) -> Result<MarketplaceListOutcome, MarketplaceError>

Purpose: Finds and loads all marketplaces Codex should know about, using the normal home directory lookup. This is the public, convenient entry point for marketplace discovery.

Data flow: It receives extra root folders to search. It finds the user’s home directory with home_dir, then passes both the extra roots and home directory into list_marketplaces_with_home. It returns a list outcome containing loaded marketplaces and recoverable load errors.

Call relations: Higher-level cache refresh and configuration discovery code calls this when it needs the current marketplace list. It delegates the real work to list_marketplaces_with_home so tests and special cases can supply a chosen home directory.

Call graph: calls 2 internal fn (home_dir, list_marketplaces_with_home); called by 3 (refresh_non_curated_plugin_cache_with_mode, discover_marketplaces_for_config, list_marketplaces_for_config).

fn home_dir() -> Option<PathBuf>

Purpose: Finds the user’s home folder in a careful, cross-platform way. Marketplace discovery uses this because a default marketplace may live under the user’s home directory.

Data flow: It checks common environment variables such as HOME and USERPROFILE, ignores empty or relative values, and falls back to the system home-directory helper. It returns an absolute path if one can be found, otherwise nothing.

Call relations: It is called by list_marketplaces during marketplace discovery and by remote plugin checkout code that also needs a home folder.

Call graph: called by 2 (list_marketplaces, checkout_remote_plugin_share).

fn validate_marketplace_root(root: &Path) -> Result<String, MarketplaceError>

Purpose: Checks whether a folder is a valid marketplace root and returns the marketplace name if it is. This is useful when users or configuration point Codex at a marketplace folder and Codex needs to verify it before trusting it.

Data flow: It receives a root path, searches inside it for a supported marketplace manifest, then loads that marketplace. If the layout or file is invalid, it returns a marketplace error; otherwise it returns the marketplace’s name.

Call relations: This function first calls find_marketplace_manifest_path to locate the catalog and then load_marketplace to prove it can be read. It is used by marketplace configuration, installation, and upgrade flows before accepting a marketplace source.

Call graph: calls 2 internal fn (find_marketplace_manifest_path, load_marketplace); called by 4 (find_marketplace_root_by_name, installed_marketplace_root_for_source, validate_marketplace_source_root, upgrade_configured_git_marketplace); 1 external calls (to_path_buf).

fn find_marketplace_manifest_path(root: &Path) -> Option<AbsolutePathBuf>

Purpose: Looks under a root folder for a marketplace JSON file in one of the supported locations. It answers the simple question: “Does this folder contain a marketplace catalog Codex understands?”

Data flow: It receives a root path and tries each supported relative manifest path beneath it. The first existing file is converted to an absolute path and returned. If none exist or the path cannot be made absolute, it returns nothing.

Call relations: Marketplace import, configuration checks, discovery, validation, and upgrade code call this whenever they need to locate the actual manifest file inside a candidate root.

Call graph: called by 5 (import_plugins, configured_marketplace_snapshot_issues, discover_marketplace_paths_from_roots, validate_marketplace_root, upgrade_configured_git_marketplace).

fn supported_marketplace_manifest_path(path: &Path) -> Option<AbsolutePathBuf>

Purpose: Checks whether a given path is itself a marketplace manifest in a supported layout. This is for cases where Codex is handed the file path directly rather than the marketplace root folder.

Data flow: It receives a path, confirms it is a file, checks whether its surrounding folders match one of the accepted layouts, and returns an absolute path if so. Otherwise it returns nothing.

Call relations: Marketplace discovery uses this before trying broader root-folder searches. It lets discover_marketplace_paths_from_roots accept both direct manifest paths and root folders.

Call graph: calls 1 internal fn (try_from); called by 1 (discover_marketplace_paths_from_roots); 2 external calls (is_file, to_path_buf).

fn invalid_marketplace_layout_error(path: &AbsolutePathBuf) -> MarketplaceError

Purpose: Creates a consistent error for marketplace files that are not located in one of the supported folder layouts. This keeps layout-related failures easy to recognize and explain.

Data flow: It receives the marketplace path and builds an InvalidMarketplaceFile error with a fixed message saying the file is not in a supported location.

Call relations: It is used by marketplace_root_dir when that function cannot work out the marketplace root from the manifest path.

Call graph: calls 1 internal fn (to_path_buf); called by 1 (marketplace_root_dir).

fn marketplace_root_from_layout(marketplace_path: &Path, relative_path: &str) -> Option<PathBuf>

Purpose: Works backward from a marketplace manifest path to find the marketplace root, but only if the path matches one supported layout. For example, it can turn <root>/.agents/plugins/marketplace.json back into <root>.

Data flow: It receives the manifest path and one supported relative layout. It compares the manifest path’s trailing folder and file names against that layout from the end backward. If every piece matches, it returns the root path; otherwise it returns nothing.

Call relations: This is a layout-recognition helper used when marketplace_root_dir needs to recover the root folder for path resolution.

Call graph: called by 1 (marketplace_root_dir); 1 external calls (new).

fn load_marketplace(path: &AbsolutePathBuf) -> Result<Marketplace, MarketplaceError>

Purpose: Reads a marketplace file and turns it into the clean public Marketplace structure used by the rest of Codex. It filters out unsupported or invalid plugin entries where possible instead of failing the whole marketplace for every bad plugin.

Data flow: It receives an absolute manifest path, reads the raw JSON, then resolves each plugin entry. Valid entries become MarketplacePlugin records with source, policy, optional local version, optional interface, and keywords. Invalid plugin IDs are logged and skipped; serious marketplace-level errors are returned.

Call relations: It calls load_raw_marketplace_manifest to read JSON, resolve_marketplace_plugin_entry to interpret each plugin, and resolve_marketplace_interface for display metadata. It is used by marketplace cache refresh, marketplace listing, and root validation.

Call graph: calls 3 internal fn (load_raw_marketplace_manifest, resolve_marketplace_interface, resolve_marketplace_plugin_entry); called by 3 (refresh_curated_plugin_cache, list_marketplaces_with_home, validate_marketplace_root); 3 external calls (new, clone, warn!).

fn list_marketplaces_with_home(
    additional_roots: &[AbsolutePathBuf],
    home_dir: Option<&Path>,
) -> Result<MarketplaceListOutcome, MarketplaceError>

Purpose: Discovers marketplace files and loads each one, while collecting errors for marketplaces that fail. This lets Codex show or use the marketplaces that worked instead of giving up because one file was bad.

Data flow: It receives extra roots plus an optional home directory. It discovers marketplace manifest paths, tries to load each one, appends successful marketplaces to the result, and records failed paths with error messages. It returns one outcome containing both successes and failures.

Call relations: The public list_marketplaces function calls this after choosing the home directory. It relies on discover_marketplace_paths_from_roots for the search and load_marketplace for reading each catalog.

Call graph: calls 2 internal fn (discover_marketplace_paths_from_roots, load_marketplace); called by 1 (list_marketplaces); 2 external calls (default, warn!).

fn discover_marketplace_paths_from_roots(
    additional_roots: &[AbsolutePathBuf],
    home_dir: Option<&Path>,
) -> Vec<AbsolutePathBuf>

Purpose: Builds the ordered list of marketplace manifest files Codex should try to load. It avoids duplicates and supports several ways a marketplace may be provided.

Data flow: It receives extra roots and an optional home directory. It first checks the home directory, then for each extra root it tries a direct manifest path, a marketplace root layout, and finally the root of the surrounding Git repository. It returns a de-duplicated list of manifest paths.

Call relations: This is the search engine underneath list_marketplaces_with_home. It calls find_marketplace_manifest_path and supported_marketplace_manifest_path, and it can ask Git utilities for the repository root when a supplied path is inside a checkout.

Call graph: calls 3 internal fn (find_marketplace_manifest_path, supported_marketplace_manifest_path, try_from); called by 1 (list_marketplaces_with_home); 2 external calls (new, get_git_repo_root).

fn load_raw_marketplace_manifest(
    path: &AbsolutePathBuf,
) -> Result<RawMarketplaceManifest, MarketplaceError>

Purpose: Reads the marketplace JSON file from disk and parses it into the raw manifest shape that mirrors the file format. It is the point where text on disk becomes structured data.

Data flow: It receives an absolute file path, reads the file as a string, and parses it as JSON. A missing file becomes MarketplaceNotFound; other read problems become input/output errors; invalid JSON becomes InvalidMarketplaceFile with the parser’s message.

Call relations: Both find_marketplace_plugin and load_marketplace call this before resolving plugin entries into the safer public marketplace model.

Call graph: calls 1 internal fn (as_path); called by 2 (find_marketplace_plugin, load_marketplace); 2 external calls (read_to_string, from_str).

fn resolve_marketplace_plugin_entry(
    marketplace_path: &AbsolutePathBuf,
    marketplace_name: &str,
    plugin: RawMarketplaceManifestPlugin,
) -> Result<Option<ResolvedMarketplacePlugin>, Market

Purpose: Turns one raw plugin entry from the marketplace JSON into a usable, validated plugin record. This is where names, sources, policies, local manifests, and categories are brought together.

Data flow: It receives the marketplace path, the marketplace name, and one raw plugin entry. It resolves the plugin source, optionally reads the local plugin manifest, merges marketplace category information into the interface, builds a checked plugin ID, and returns a resolved plugin. Unsupported sources are skipped by returning nothing; invalid plugin names become errors.

Call relations: find_marketplace_plugin uses this when looking for one plugin, and load_marketplace uses it for every entry in a catalog. It calls resolve_supported_plugin_source, load_plugin_manifest, plugin_interface_with_marketplace_category, and the plugin ID constructor.

Call graph: calls 4 internal fn (load_plugin_manifest, plugin_interface_with_marketplace_category, resolve_supported_plugin_source, new); called by 2 (find_marketplace_plugin, load_marketplace).

fn resolve_supported_plugin_source(
    marketplace_path: &AbsolutePathBuf,
    plugin_name: &str,
    source: RawMarketplaceManifestPluginSource,
) -> Option<MarketplacePluginSource>

Purpose: Filters and resolves a plugin source while treating unsupported or bad source descriptions as skippable plugin entries. This keeps one unfamiliar source format from breaking the whole marketplace.

Data flow: It receives the marketplace path, plugin name, and raw source. If the source is unsupported, it logs a warning and returns nothing. Otherwise it asks resolve_plugin_source to normalize it; success returns a source, while failure is logged and skipped.

Call relations: resolve_marketplace_plugin_entry calls this before doing any other plugin resolution work. It acts as a safe wrapper around resolve_plugin_source.

Call graph: calls 1 internal fn (resolve_plugin_source); called by 1 (resolve_marketplace_plugin_entry); 1 external calls (warn!).

fn resolve_plugin_source(
    marketplace_path: &AbsolutePathBuf,
    source: RawMarketplaceManifestPluginSource,
) -> Result<MarketplacePluginSource, MarketplaceError>

Purpose: Converts the marketplace JSON’s source field into a clear internal source: either a local folder or a Git repository. It understands several accepted JSON shapes for backward compatibility and convenience.

Data flow: It receives the marketplace path and a raw source value. Local sources are converted into safe absolute local paths. Git sources have their URL, optional subdirectory, optional branch or tag, and optional commit hash cleaned up. It returns the normalized source or an error if the source is invalid.

Call relations: resolve_supported_plugin_source calls this after filtering out unsupported source formats. It delegates detailed cleanup to resolve_local_plugin_source_path, normalize_git_plugin_source_url, normalize_remote_plugin_subdir, and normalize_optional_git_selector.

Call graph: calls 4 internal fn (normalize_git_plugin_source_url, normalize_optional_git_selector, normalize_remote_plugin_subdir, resolve_local_plugin_source_path); called by 1 (resolve_supported_plugin_source); 1 external calls (unreachable!).

fn resolve_local_plugin_source_path(
    marketplace_path: &AbsolutePathBuf,
    path: &str,
) -> Result<AbsolutePathBuf, MarketplaceError>

Purpose: Validates and resolves a local plugin path from the marketplace file. It makes sure local plugin paths stay inside the marketplace root instead of pointing somewhere unexpected.

Data flow: It receives the marketplace manifest path and a source string. The string must start with ./, must not be empty, and must contain only normal path pieces, not parent-directory jumps like ... It then joins the safe relative path to the marketplace root and returns an absolute path.

Call relations: resolve_plugin_source calls this for local plugin sources. It uses marketplace_root_dir to find the trusted root folder before building the final path.

Call graph: calls 2 internal fn (marketplace_root_dir, to_path_buf); called by 1 (resolve_plugin_source); 1 external calls (new).

fn normalize_remote_plugin_subdir(
    marketplace_path: &AbsolutePathBuf,
    path: &str,
) -> Result<String, MarketplaceError>

Purpose: Cleans and checks a subfolder path inside a remote Git repository. It prevents marketplace entries from naming an empty path or escaping upward out of the repository.

Data flow: It receives the marketplace path and a subdirectory string. It trims whitespace, removes an optional leading ./, rejects empty paths, and rejects path components such as ... It returns the safe subdirectory string.

Call relations: resolve_plugin_source calls this when a Git source points to a plugin inside a repository subfolder.

Call graph: calls 1 internal fn (to_path_buf); called by 1 (resolve_plugin_source); 1 external calls (new).

fn normalize_git_plugin_source_url(
    marketplace_path: &AbsolutePathBuf,
    url: &str,
) -> Result<String, MarketplaceError>

Purpose: Accepts the different Git URL styles marketplace authors may write and turns them into a form Codex can use. It also rejects empty or unrecognized Git source URLs.

Data flow: It receives the marketplace path and a URL string. It trims whitespace, accepts HTTP, HTTPS, file, absolute local, SSH, and GitHub shorthand forms, and normalizes supported forms where needed. Relative URLs are resolved under the marketplace root. If nothing matches, it returns an invalid-file error.

Call relations: resolve_plugin_source calls this for every Git-based plugin source. It may hand work to normalize_github_git_url, normalize_relative_git_plugin_source_url, or normalize_github_shorthand_url depending on the input style.

Call graph: calls 4 internal fn (normalize_github_git_url, normalize_github_shorthand_url, normalize_relative_git_plugin_source_url, to_path_buf); called by 1 (resolve_plugin_source); 1 external calls (format!).

fn normalize_relative_git_plugin_source_url(
    marketplace_path: &AbsolutePathBuf,
    url: &str,
) -> Result<String, MarketplaceError>

Purpose: Resolves a relative Git source path against the marketplace root while refusing to leave that root. This lets a marketplace point at a sibling local repository safely.

Data flow: It receives the marketplace path and a relative URL string. It starts from the marketplace root, walks each slash- or backslash-separated segment, ignores . and empty pieces, rejects .., and returns the resulting local path as a string.

Call relations: normalize_git_plugin_source_url calls this only for relative Git source URLs such as ./repo. It uses marketplace_root_dir to know the safe base folder.

Call graph: calls 2 internal fn (marketplace_root_dir, to_path_buf); called by 1 (normalize_git_plugin_source_url).

fn normalize_optional_git_selector(value: &Option<String>) -> Option<String>

Purpose: Cleans optional Git selectors, such as a branch name, tag, or commit hash. Empty strings are treated the same as not providing a selector.

Data flow: It receives an optional string. If present, it trims whitespace and keeps it only if something remains. It returns either the cleaned string or nothing.

Call relations: resolve_plugin_source uses this for optional Git ref and sha fields while building a normalized Git plugin source.

Call graph: called by 1 (resolve_plugin_source).

fn normalize_github_git_url(url: &str) -> String

Purpose: Adds the conventional .git suffix to plain GitHub HTTPS repository URLs when it is missing. This makes GitHub URLs more consistent for later Git operations.

Data flow: It receives a URL string. If it starts with https://github.com/ and does not already end in .git, it returns the same URL with .git appended. Otherwise it returns the original URL unchanged.

Call relations: normalize_git_plugin_source_url calls this after recognizing an HTTP or HTTPS URL.

Call graph: called by 1 (normalize_git_plugin_source_url); 1 external calls (format!).

fn normalize_github_shorthand_url(source: &str) -> Option<String>

Purpose: Turns a short GitHub reference like owner/repo into a full GitHub Git URL. This lets marketplace files stay concise while Codex still gets a complete URL.

Data flow: It receives a source string, first checks whether it looks like valid two-part GitHub shorthand, then extracts the owner and repository names. It removes any .git suffix from the repository part and returns https://github.com/owner/repo.git; invalid shorthand returns nothing.

Call relations: normalize_git_plugin_source_url calls this after other URL styles do not match. It uses looks_like_github_shorthand to decide whether the input is eligible.

Call graph: calls 1 internal fn (looks_like_github_shorthand); called by 1 (normalize_git_plugin_source_url); 1 external calls (format!).

fn looks_like_github_shorthand(source: &str) -> bool

Purpose: Checks whether a string has exactly the simple owner/repo shape accepted as GitHub shorthand. It keeps the shorthand rule narrow so random strings are not mistaken for repositories.

Data flow: It receives a string, splits it on /, and requires exactly two valid segments with no extra part. It returns true only when both pieces pass the allowed-character check.

Call relations: normalize_github_shorthand_url uses this as its gatekeeper before constructing a full GitHub URL.

Call graph: called by 1 (normalize_github_shorthand_url).

fn is_github_shorthand_segment(segment: &str) -> bool

Purpose: Checks whether one part of a GitHub shorthand reference is non-empty and uses only allowed characters. It is the small character-level rule behind the shorthand parser.

Data flow: It receives one segment string and returns true if it is not empty and every character is a letter, digit, dash, underscore, or dot. Otherwise it returns false.

Call relations: looks_like_github_shorthand relies on this for both the owner and repository parts of a shorthand source.

fn plugin_interface_with_marketplace_category(
    mut interface: Option<PluginManifestInterface>,
    category: Option<String>,
) -> Option<PluginManifestInterface>

Purpose: Combines plugin interface metadata with a category supplied by the marketplace. If both the plugin manifest and marketplace name a category, the marketplace category wins.

Data flow: It receives optional interface metadata and an optional category string. If a category is present, it creates default interface metadata if needed and sets that category. It returns the updated interface, or the original empty value if there is still no metadata.

Call relations: resolve_marketplace_plugin_entry calls this when combining marketplace and manifest information. Plugin detail reading code also uses it so category behavior stays consistent.

Call graph: called by 2 (read_plugin_detail_for_marketplace_plugin, resolve_marketplace_plugin_entry).

fn marketplace_root_dir(
    marketplace_path: &AbsolutePathBuf,
) -> Result<AbsolutePathBuf, MarketplaceError>

Purpose: Finds the root folder that owns a marketplace manifest path. Many path checks depend on this root so local plugin paths and relative Git paths can be resolved safely.

Data flow: It receives an absolute marketplace manifest path and tries each supported marketplace layout. If one layout matches, it converts the recovered root into an absolute path and returns it. If none match, it returns a consistent invalid-layout error.

Call relations: Path-resolution code such as resolve_local_plugin_source_path and normalize_relative_git_plugin_source_url calls this before joining relative paths. Other listing code also uses it when it needs to reason from manifest file back to root folder.

Call graph: calls 4 internal fn (invalid_marketplace_layout_error, marketplace_root_from_layout, as_path, try_from); called by 3 (run_list, normalize_relative_git_plugin_source_url, resolve_local_plugin_source_path).

fn resolve_marketplace_interface(
    interface: Option<RawMarketplaceManifestInterface>,
) -> Option<MarketplaceInterface>

Purpose: Turns raw marketplace interface metadata from JSON into the public marketplace interface structure, but only when there is meaningful display information. This avoids carrying around empty metadata objects.

Data flow: It receives optional raw interface data. If there is no interface, or if it has no display name, it returns nothing. If a display name exists, it returns a MarketplaceInterface containing it.

Call relations: load_marketplace calls this after reading the raw marketplace manifest so the returned Marketplace has clean, useful display metadata.

Call graph: called by 1 (load_marketplace).

fn log_plugin_load_errors(plugins: &[LoadedPlugin<McpServerConfig>])

Purpose: Writes a warning for every loaded plugin that carries an error. This gives operators a visible clue that a plugin failed without stopping all plugins from loading.

Data flow: It receives a list of loaded plugin records. It looks for records with an error message, then writes a warning containing the plugin name, root path, and error. It returns nothing and only changes the log output.

Call relations: After plugin loading is forced or refreshed, plugins_for_config_with_force_reload calls this to surface any failures found during the earlier loading work.

Call graph: called by 1 (plugins_for_config_with_force_reload); 2 external calls (iter, warn!).

async fn load_plugins_from_layer_stack(
    config_layer_stack: &ConfigLayerStack,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    restriction_product: Option<Product>,

Purpose: Loads all configured plugins with their full capabilities, using the combined configuration stack. It is the normal high-level entry for turning config into usable plugin records.

Data flow: It receives layered configuration, extra plugin settings, the plugin store, an optional product restriction, and a conflict preference. It derives skill enable/disable rules from the configuration, then asks the scoped loader to load every capability. It returns a list of loaded plugin records.

Call relations: Higher-level plugin entry points call this when they need complete plugin information. It prepares skill rules, then delegates the actual merge-and-load loop to load_plugins_from_layer_stack_with_scope.

Call graph: calls 2 internal fn (load_plugins_from_layer_stack_with_scope, skill_config_rules_from_stack); called by 3 (plugins_for_config_with_force_reload, plugins_for_layer_stack, load_plugins_ignores_project_config_files).

async fn load_plugins_from_layer_stack_with_scope(
    config_layer_stack: &ConfigLayerStack,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    prefer_remote_curated_confl

Purpose: Loads configured plugins either fully or in a hooks-only mode. This shared path prevents the hooks-only loader and the full loader from disagreeing about which plugins are enabled.

Data flow: It reads configured plugins from the config stack, merges in extra or remote-installed plugins, sorts them for stable order, then loads each one. As it goes, it watches for duplicate MCP server names and logs a warning when two plugins declare the same name. It returns all loaded plugin records.

Call relations: Both load_plugins_from_layer_stack and load_plugin_hooks_from_layer_stack rely on this. For each plugin it calls load_plugin, and it supplies the scope that tells load_plugin how much work to do.

Call graph: calls 3 internal fn (configured_plugins_from_stack, load_plugin, merge_configured_plugins_with_remote_installed); called by 2 (load_plugin_hooks_from_layer_stack, load_plugins_from_layer_stack); 3 external calls (new, with_capacity, warn!).

async fn load_plugin_hooks_from_layer_stack(
    config_layer_stack: &ConfigLayerStack,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    prefer_remote_curated_conflicts:

Purpose: Loads only hook declarations from enabled plugins. This is useful when the system needs hook rules but does not need skills, apps, or MCP servers yet.

Data flow: It receives the same plugin configuration inputs as full loading. It asks the shared loader to run in hooks-only mode, filters to active plugins, collects their hook sources and hook warnings, and returns those two lists in a small outcome object.

Call relations: plugin_hooks_for_layer_stack calls this when it needs startup hook configuration. Internally it reuses load_plugins_from_layer_stack_with_scope so hook loading follows the same plugin selection rules as full loading.

Call graph: calls 1 internal fn (load_plugins_from_layer_stack_with_scope); called by 1 (plugin_hooks_for_layer_stack).

fn merge_configured_plugins_with_remote_installed(
    mut configured_plugins: HashMap<String, PluginConfig>,
    extra_plugins: HashMap<String, PluginConfig>,
    store: &PluginStore,
    prefer_remo

Purpose: Combines plugins from user configuration with plugins reported as remotely installed. It also resolves a special conflict where a local curated plugin and a remote curated plugin refer to the same plugin name.

Data flow: It starts with configured plugins, extra plugin configs, the plugin store, and a conflict preference. It identifies installed local curated plugins, checks whether incoming remote curated plugins overlap, then either keeps the local one or replaces it depending on the preference. It returns the final plugin config map.

Call relations: The shared loader calls this before loading any plugin. It uses installed_plugin_name_for_marketplace to recognize remote curated plugins that are actually installed locally.

Call graph: calls 3 internal fn (installed_plugin_name_for_marketplace, active_plugin_version, parse); called by 1 (load_plugins_from_layer_stack_with_scope); 2 external calls (new, is_openai_curated_marketplace_name).

fn installed_plugin_name_for_marketplace(
    plugin_key: &str,
    marketplace_name: &str,
    store: &PluginStore,
) -> Option<String>

Purpose: Checks whether a plugin key names an installed plugin from a specific marketplace. If so, it returns that plugin’s simple name.

Data flow: It receives a plugin key, a marketplace name, and the plugin store. It parses the key, verifies the marketplace matches, and confirms the store has an active root for that plugin. It returns the plugin name, or nothing if any check fails.

Call relations: merge_configured_plugins_with_remote_installed uses this as a small helper while deciding whether remote-installed plugin config conflicts with locally configured curated plugins.

Call graph: calls 2 internal fn (active_plugin_root, parse); called by 1 (merge_configured_plugins_with_remote_installed).

fn remote_installed_plugins_to_config(
    plugins: &[RemoteInstalledPlugin],
    store: &PluginStore,
) -> HashMap<String, PluginConfig>

Purpose: Turns the server’s list of remotely installed plugins into local plugin configuration entries. It ignores invalid names and plugins whose bundle is not already present in the local cache.

Data flow: It receives remote plugin records and the plugin store. For each record it builds a plugin id, checks that the local cache has an active plugin root, and creates a PluginConfig with the remote enabled flag. It returns a map keyed by plugin id string.

Call relations: remote_installed_plugin_configs calls this while reconciling remote install state with local loading. The result can later be merged into the normal configured plugin list.

Call graph: called by 1 (remote_installed_plugin_configs); 1 external calls (iter).

fn refresh_curated_plugin_cache(
    codex_home: &Path,
    plugin_version: &str,
    configured_curated_plugin_ids: &[PluginId],
) -> Result<bool, String>

Purpose: Refreshes cached copies of curated plugins that are configured by the user. Curated plugins are the officially bundled marketplace plugins shipped through known marketplace files.

Data flow: It receives the Codex home directory, the current plugin version, and configured curated plugin ids. It loads curated marketplace files, maps plugin ids to local source folders, removes stale cached plugins that vanished from a loaded marketplace, and installs updated copies when the cache version differs. It returns whether anything changed, or an error string.

Call relations: This is called by cache-refresh or install flows. It uses curated_marketplace_paths_for_cache_refresh to find marketplace files and curated_plugin_cache_version to normalize the cache version name.

Call graph: calls 5 internal fn (curated_marketplace_paths_for_cache_refresh, curated_plugin_cache_version, load_marketplace, try_new, new); 4 external calls (new, new, to_path_buf, warn!).

fn curated_marketplace_paths_for_cache_refresh(
    codex_home: &Path,
) -> Result<Vec<AbsolutePathBuf>, String>

Purpose: Finds the local marketplace JSON files used to refresh curated plugin cache entries. It knows the expected temporary paths where bundled curated marketplace data is placed.

Data flow: It receives the Codex home directory. It builds the required curated marketplace path and optionally adds the API curated marketplace path if that file exists. It returns absolute paths or an error if a path cannot be made absolute.

Call relations: refresh_curated_plugin_cache calls this before reading marketplace contents, so cache refresh works from the same known marketplace locations every time.

Call graph: calls 1 internal fn (try_from); called by 1 (refresh_curated_plugin_cache); 2 external calls (join, vec!).

fn curated_plugin_cache_version(plugin_version: &str) -> String

Purpose: Chooses the version string used for cached curated plugin copies. Full git commit hashes are shortened so cache folder versions stay compact.

Data flow: It receives a plugin version string. If the string looks like a full 40-character git SHA, it returns the first eight characters; otherwise it returns the original string. It does not touch disk.

Call relations: refresh_curated_plugin_cache uses this when deciding whether a cached curated plugin is current. install_resolved_plugin also uses it when installing a curated plugin.

Call graph: calls 1 internal fn (is_full_git_sha); called by 2 (refresh_curated_plugin_cache, install_resolved_plugin).

fn refresh_non_curated_plugin_cache(
    codex_home: &Path,
    additional_roots: &[AbsolutePathBuf],
) -> Result<bool, String>

Purpose: Refreshes cached copies of configured non-curated plugins, but only when their source version changed. Non-curated means plugins from discovered marketplaces other than the official curated ones.

Data flow: It receives Codex home and extra marketplace roots. It calls the shared non-curated refresh helper in normal mode, which compares source versions before reinstalling. It returns whether the cache changed or an error.

Call relations: run_non_curated_plugin_cache_refresh_loop calls this for routine background refreshes. The real work is done by refresh_non_curated_plugin_cache_with_mode.

Call graph: calls 1 internal fn (refresh_non_curated_plugin_cache_with_mode); called by 1 (run_non_curated_plugin_cache_refresh_loop).

fn refresh_non_curated_plugin_cache_force_reinstall(
    codex_home: &Path,
    additional_roots: &[AbsolutePathBuf],
) -> Result<bool, String>

Purpose: Refreshes configured non-curated plugins by reinstalling them even if their version appears unchanged. This is useful after marketplace upgrades or when the cache may be stale for reasons beyond the version string.

Data flow: It receives Codex home and extra marketplace roots. It calls the shared refresh helper in force-reinstall mode. It returns whether anything was reinstalled or an error.

Call relations: The background refresh loop and marketplace upgrade flow call this when they want a stronger refresh than the normal version check.

Call graph: calls 1 internal fn (refresh_non_curated_plugin_cache_with_mode); called by 2 (run_non_curated_plugin_cache_refresh_loop, upgrade_configured_marketplaces_for_config).

fn refresh_non_curated_plugin_cache_with_mode(
    codex_home: &Path,
    additional_roots: &[AbsolutePathBuf],
    mode: NonCuratedCacheRefreshMode,
) -> Result<bool, String>

Purpose: Performs the actual cache refresh for configured non-curated marketplace plugins. It discovers sources, materializes them, reads versions, and installs updated bundles into the plugin store.

Data flow: It reads plugin config from config.toml, keeps only non-curated plugin ids, lists available marketplaces, and matches configured plugins to marketplace entries. For each match it turns the source into a local path, reads the plugin version, and installs it unless normal mode says the same version is already active. It returns whether any cache entry changed.

Call relations: Both public non-curated refresh functions call this with different modes. It uses materialize_marketplace_plugin_source when a marketplace source must be made available as a local directory.

Call graph: calls 7 internal fn (configured_plugins_from_codex_home, materialize_marketplace_plugin_source, non_curated_plugin_ids_from_config_keys, list_marketplaces, try_new, plugin_version_for_source, new); called by 2 (refresh_non_curated_plugin_cache, refresh_non_curated_plugin_cache_force_reinstall); 4 external calls (new, to_path_buf, is_openai_curated_marketplace_name, warn!).

fn configured_plugins_from_stack(
    config_layer_stack: &ConfigLayerStack,
) -> HashMap<String, PluginConfig>

Purpose: Extracts plugin configuration from the effective user configuration in a layered config stack. If there is no user config, it reports no configured plugins.

Data flow: It receives a ConfigLayerStack. It asks for the effective user config, then passes that TOML value to configured_plugins_from_user_config_value. It returns a map of plugin keys to plugin settings.

Call relations: load_plugins_from_layer_stack_with_scope calls this before merging local config with remote-installed plugins.

Call graph: calls 2 internal fn (effective_user_config, configured_plugins_from_user_config_value); called by 1 (load_plugins_from_layer_stack_with_scope); 1 external calls (new).

fn is_full_git_sha(value: &str) -> bool

Purpose: Checks whether a string looks like a full git commit SHA. A SHA is a hexadecimal identifier used by git to name an exact commit.

Data flow: It receives a string. It checks that it is exactly 40 characters long and that every character is hexadecimal. It returns true or false.

Call relations: curated_plugin_cache_version calls this to decide whether to shorten a version string.

Call graph: called by 1 (curated_plugin_cache_version).

fn configured_plugins_from_user_config_value(
    user_config: &toml::Value,
) -> HashMap<String, PluginConfig>

Purpose: Reads the plugins section from an already-parsed user config value. Bad plugin config is ignored with a warning instead of breaking startup.

Data flow: It receives a TOML value. It looks for the top-level plugins table and tries to convert it into plugin configuration records. It returns that map, or an empty map if the section is missing or invalid.

Call relations: configured_plugins_from_stack uses this for in-memory layered config, and configured_plugins_from_codex_home uses it after reading config.toml from disk.

Call graph: called by 2 (configured_plugins_from_codex_home, configured_plugins_from_stack); 3 external calls (new, get, warn!).

fn configured_plugins_from_codex_home(
    codex_home: &Path,
    read_error_message: &str,
    parse_error_message: &str,
) -> HashMap<String, PluginConfig>

Purpose: Reads plugin configuration directly from the user’s config.toml file under Codex home. This is used by cache refresh paths that do not already have a full config stack.

Data flow: It receives Codex home plus warning messages to use for read and parse failures. It reads config.toml if present, parses it as TOML, extracts the plugins section, and returns plugin settings. Missing files or invalid content produce warnings and an empty map.

Call relations: configured_curated_plugin_ids_from_codex_home and the non-curated cache refresh helper call this before deciding which plugin ids need cache work.

Call graph: calls 1 internal fn (configured_plugins_from_user_config_value); called by 2 (configured_curated_plugin_ids_from_codex_home, refresh_non_curated_plugin_cache_with_mode); 4 external calls (new, join, read_to_string, warn!).

fn configured_plugin_ids(
    configured_plugins: HashMap<String, PluginConfig>,
    invalid_plugin_key_message: &str,
) -> Vec<PluginId>

Purpose: Converts plugin config keys into structured plugin ids and drops invalid keys. This turns raw strings from config into safer values with separate marketplace and plugin names.

Data flow: It receives a plugin config map and a warning message. It parses each key, keeps successful ids, and logs the supplied warning for invalid keys. It returns the list of valid plugin ids.

Call relations: The curated and non-curated id filters both call this first, then apply their own marketplace selection rules.

Call graph: called by 2 (curated_plugin_ids_from_config_keys, non_curated_plugin_ids_from_config_keys).

fn curated_plugin_ids_from_config_keys(
    configured_plugins: HashMap<String, PluginConfig>,
) -> Vec<PluginId>

Purpose: Finds the configured plugin ids that belong to OpenAI curated marketplaces. It returns them in a stable order.

Data flow: It receives plugin configuration. It parses keys into plugin ids, keeps only curated marketplace ids, sorts them by key, and returns the list.

Call relations: configured_curated_plugin_ids_from_codex_home calls this after reading config.toml so curated cache refresh knows exactly which curated plugins matter.

Call graph: calls 1 internal fn (configured_plugin_ids); called by 1 (configured_curated_plugin_ids_from_codex_home).

fn non_curated_plugin_ids_from_config_keys(
    configured_plugins: HashMap<String, PluginConfig>,
) -> Vec<PluginId>

Purpose: Finds configured plugin ids that do not belong to OpenAI curated marketplaces. These are the plugins refreshed from discovered external marketplaces.

Data flow: It receives plugin configuration. It parses keys into plugin ids, filters out curated marketplaces, sorts the remaining ids, and returns them.

Call relations: refresh_non_curated_plugin_cache_with_mode calls this before scanning marketplace entries, so it only looks for plugins the user actually configured.

Call graph: calls 1 internal fn (configured_plugin_ids); called by 1 (refresh_non_curated_plugin_cache_with_mode).

fn configured_curated_plugin_ids_from_codex_home(codex_home: &Path) -> Vec<PluginId>

Purpose: Reads config.toml and returns the curated plugin ids configured by the user. It is a convenience wrapper for curated cache setup.

Data flow: It receives Codex home. It reads configured plugins from config.toml, filters them to curated plugin ids, and returns the sorted list.

Call relations: Cache-refresh setup code uses this to know which curated plugins should be present in the local plugin cache.

Call graph: calls 2 internal fn (configured_plugins_from_codex_home, curated_plugin_ids_from_config_keys).

async fn load_plugin(
    config_name: String,
    plugin: &PluginConfig,
    store: &PluginStore,
    scope: &PluginLoadScope<'_>,
) -> LoadedPlugin<McpServerConfig>

Purpose: Loads one plugin record from its config and installed folder. It validates the plugin, reads its manifest, and fills in the capabilities requested by the current load scope.

Data flow: It receives the config name, plugin settings, plugin store, and a scope. It creates a loaded-plugin shell, returns early for disabled or invalid plugins, finds the active installed root, reads plugin.json, and then loads skills, MCP servers, apps, and hooks as appropriate. It returns a LoadedPlugin containing data or an error message.

Call relations: load_plugins_from_layer_stack_with_scope calls this once per configured plugin. Inside, it delegates specialized work to helpers such as load_plugin_skills, load_mcp_servers_from_file, load_plugin_apps, and load_plugin_hooks.

Call graph: calls 10 internal fn (apply_plugin_mcp_server_policy, load_mcp_servers_from_file, load_plugin_apps, load_plugin_hooks, load_plugin_skills, plugin_mcp_config_paths, plugin_skill_roots, load_plugin_manifest, plugin_data_root, parse); called by 1 (load_plugins_from_layer_stack_with_scope); 4 external calls (new, new, new, warn!).

fn apply_plugin_mcp_server_policy(config: &mut McpServerConfig, policy: &PluginMcpServerConfig)

Purpose: Applies the user’s per-plugin MCP server policy to a server declared by the plugin. This lets user config disable a server or restrict its tools.

Data flow: It receives a mutable MCP server config and a policy from plugin settings. It updates enabled status, default approval mode, enabled or disabled tool lists, and per-tool approval rules. It returns nothing because it changes the config in place.

Call relations: load_plugin calls this while loading MCP servers, after reading a plugin’s declared server config and before storing it in the loaded plugin record.

Call graph: called by 1 (load_plugin).

fn has_enabled_skills(&self) -> bool

Purpose: Answers whether a plugin should be considered to have enabled skills. It treats load errors as important, because errors may mean skills were expected but could not be read.

Data flow: It reads the resolved skills, the disabled skill path set, and the error flag inside the ResolvedPluginSkills value. It returns true if there were load errors or if at least one skill is not disabled; otherwise false.

Call relations: load_plugin uses this after load_plugin_skills to set the plugin’s has_enabled_skills flag.

async fn load_plugin_skills(
    plugin_root: &AbsolutePathBuf,
    plugin_id: &PluginId,
    manifest_paths: &PluginManifestPaths,
    restriction_product: Option<Product>,
    skill_config_rules: &S

Purpose: Loads skill metadata from a plugin’s skill folders and applies product and user disable rules. A skill is a reusable instruction or capability bundle available to the assistant.

Data flow: It receives the plugin root, plugin id, manifest paths, an optional product restriction, and skill config rules. It builds skill roots, loads skills from those folders, filters out skills not meant for the current product, resolves which skill paths are disabled, and returns the resolved skills plus error status.

Call relations: load_plugin calls this during full plugin loading. Plugin detail readers can also call it when showing information about a marketplace plugin.

Call graph: calls 3 internal fn (plugin_skill_roots, resolve_disabled_skill_paths, load_skills_from_roots); called by 2 (load_plugin, read_plugin_detail_for_marketplace_plugin).

fn plugin_skill_roots(
    plugin_root: &AbsolutePathBuf,
    manifest_paths: &PluginManifestPaths,
) -> Vec<AbsolutePathBuf>

Purpose: Builds the list of folders where a plugin’s skills may live. It combines the default skills folder with any manifest-specified skills path.

Data flow: It receives a plugin root and manifest path settings. It starts with the default skills directory if it exists, adds the manifest skills path if present, sorts and removes duplicates, and returns the folder list.

Call relations: load_plugin, load_plugin_skills, and plugin_telemetry_metadata_from_root use this so they all agree on where plugin skills are located.

Call graph: calls 1 internal fn (default_skill_roots); called by 3 (load_plugin, load_plugin_skills, plugin_telemetry_metadata_from_root).

fn default_skill_roots(plugin_root: &AbsolutePathBuf) -> Vec<AbsolutePathBuf>

Purpose: Finds the conventional skills directory inside a plugin. By default, plugins can place skills in a folder named skills.

Data flow: It receives the plugin root, appends the default skills folder name, and checks whether that directory exists. It returns a one-item list if it exists, otherwise an empty list.

Call relations: plugin_skill_roots calls this before adding any manifest-defined skills path.

Call graph: calls 1 internal fn (join); called by 1 (plugin_skill_roots); 2 external calls (new, vec!).

fn plugin_mcp_config_paths(
    plugin_root: &Path,
    manifest_paths: &PluginManifestPaths,
) -> Vec<AbsolutePathBuf>

Purpose: Determines which MCP configuration files to read for a plugin. A manifest path takes priority over the default file location.

Data flow: It receives the plugin root and manifest path settings. If the manifest names an MCP config file, it returns that one path; otherwise it searches for the default .mcp.json file. It returns a list of absolute paths.

Call relations: load_plugin, load_declared_plugin_mcp_servers, and plugin_telemetry_metadata_from_root use this before parsing MCP server definitions.

Call graph: calls 1 internal fn (default_mcp_config_paths); called by 3 (load_declared_plugin_mcp_servers, load_plugin, plugin_telemetry_metadata_from_root); 1 external calls (vec!).

fn default_mcp_config_paths(plugin_root: &Path) -> Vec<AbsolutePathBuf>

Purpose: Looks for the default MCP config file inside a plugin folder. The default file name is .mcp.json.

Data flow: It receives the plugin root path, checks whether .mcp.json exists and can be made absolute, sorts and deduplicates the result, and returns zero or one paths.

Call relations: plugin_mcp_config_paths calls this when the manifest does not specify a custom MCP config path.

Call graph: calls 1 internal fn (try_from); called by 1 (plugin_mcp_config_paths); 2 external calls (join, new).

async fn load_plugin_apps(plugin_root: &Path) -> Vec<AppDeclaration>

Purpose: Loads app connector declarations from a plugin. App declarations describe external app connectors that the plugin provides or relates to.

Data flow: It receives a plugin root. It reads the manifest if available, chooses manifest app paths or the default .app.json file, reads those files, and returns app declarations. If the manifest is missing, it still tries the default app config path.

Call relations: load_plugin uses this during full loading, load_plugin_mcp_servers uses it before applying app routing policy, and plugin detail readers use it when showing plugin capabilities.

Call graph: calls 4 internal fn (default_app_config_paths, load_apps_from_paths, plugin_app_config_paths, load_plugin_manifest); called by 3 (load_plugin, load_plugin_mcp_servers, read_plugin_detail_for_marketplace_plugin).

fn plugin_app_declarations_from_value(value: &JsonValue) -> Vec<AppDeclaration>

Purpose: Parses app declarations from an already-loaded JSON value. This is useful when app config content is available in memory rather than as a file.

Data flow: It receives a JSON value, tries to interpret it as a plugin app file, converts entries into app declarations, removes duplicate connector ids, and returns the remaining declarations. Invalid JSON shape produces an empty list.

Call relations: plugin_app_category_by_id_from_value calls this when it needs app declarations from raw JSON data.

Call graph: calls 1 internal fn (app_declarations_from_file); called by 1 (plugin_app_category_by_id_from_value); 3 external calls (new, clone, new).

fn plugin_app_config_paths(
    plugin_root: &Path,
    manifest_paths: &PluginManifestPaths,
) -> Vec<AbsolutePathBuf>

Purpose: Chooses which app configuration files to read for a plugin. Manifest-provided paths override the default file location.

Data flow: It receives the plugin root and manifest path settings. If the manifest names an apps config path, it returns that; otherwise it checks for the default .app.json file. It returns absolute paths.

Call relations: load_plugin_apps and plugin_telemetry_metadata_from_root call this before reading app declarations.

Call graph: calls 1 internal fn (default_app_config_paths); called by 2 (load_plugin_apps, plugin_telemetry_metadata_from_root); 1 external calls (vec!).

fn default_app_config_paths(plugin_root: &Path) -> Vec<AbsolutePathBuf>

Purpose: Looks for the default app config file in a plugin folder. The default file name is .app.json.

Data flow: It receives the plugin root path, checks for .app.json, converts it to an absolute path if possible, sorts and deduplicates the result, and returns zero or one paths.

Call relations: plugin_app_config_paths and load_plugin_apps use this when no manifest app path is given.

Call graph: calls 1 internal fn (try_from); called by 2 (load_plugin_apps, plugin_app_config_paths); 2 external calls (join, new).

fn load_plugin_hooks(
    plugin_root: &AbsolutePathBuf,
    plugin_id: &PluginId,
    plugin_data_root: &AbsolutePathBuf,
    manifest_paths: &PluginManifestPaths,
) -> (Vec<PluginHookSource>, Vec<St

Purpose: Discovers hook rules bundled with a plugin. Hooks are rules that let plugins run actions at certain system events.

Data flow: It receives the plugin root, plugin id, plugin data root, and manifest paths. It reads hooks from manifest-listed files, inline manifest hook objects, or the default hooks/hooks.json file. It returns hook source records and warning messages for files that could not be read or parsed.

Call relations: load_plugin calls this for every enabled plugin, even in hooks-only mode. Plugin detail readers also use it to inspect plugin hook capability.

Call graph: calls 3 internal fn (append_plugin_hook_file, as_path, join); called by 2 (load_plugin, read_plugin_detail_for_marketplace_plugin); 5 external calls (new, find_plugin_manifest_path, format!, clone, clone).

fn append_plugin_hook_file(
    plugin_root: &AbsolutePathBuf,
    plugin_id: &PluginId,
    plugin_data_root: &AbsolutePathBuf,
    path: &AbsolutePathBuf,
    sources: &mut Vec<PluginHookSource>,

Purpose: Reads one hook config file and appends it to the collected hook sources. It preserves file location details so later runtime messages can say where the hooks came from.

Data flow: It receives plugin identity, the hook file path, and mutable source and warning lists. It reads the file, parses it as a hooks JSON file, ignores empty hook lists, and pushes a PluginHookSource on success. Read or parse failures are added to warnings.

Call relations: load_plugin_hooks calls this for each manifest hook file and for the default hook file when present.

Call graph: calls 1 internal fn (as_path); called by 1 (load_plugin_hooks); 4 external calls (format!, read_to_string, clone, clone).

async fn load_apps_from_paths(
    plugin_root: &Path,
    app_config_paths: Vec<AbsolutePathBuf>,
) -> Vec<AppDeclaration>

Purpose: Reads app declarations from one or more app config files. Bad or unreadable files are skipped so one broken app file does not stop plugin loading.

Data flow: It receives a plugin root and a list of app config paths. For each file it reads JSON, parses it as a plugin app file, converts it into declarations, and appends those to the result. It returns all declarations that could be loaded.

Call relations: load_plugin_apps and plugin_telemetry_metadata_from_root call this after deciding which app config paths apply.

Call graph: calls 1 internal fn (app_declarations_from_file); called by 2 (load_plugin_apps, plugin_telemetry_metadata_from_root); 3 external calls (new, read_to_string, warn!).

fn app_declarations_from_file(
    parsed: PluginAppFile,
    plugin_root: Option<&Path>,
) -> Vec<AppDeclaration>

Purpose: Converts a parsed app config file into app declaration records. It drops entries that do not include a usable app id.

Data flow: It receives the parsed app file and optionally the plugin root for warning messages. It walks the app entries, trims and validates ids and categories, creates AppDeclaration records for valid entries, and returns the list.

Call relations: load_apps_from_paths uses this after reading files from disk. plugin_app_declarations_from_value uses it for JSON values already in memory.

Call graph: called by 2 (load_apps_from_paths, plugin_app_declarations_from_value).

fn cleaned_app_category(category: Option<String>) -> Option<String>

Purpose: Normalizes an optional app category by trimming whitespace and treating an empty string as missing.

Data flow: It receives an optional string. If present, it trims surrounding whitespace and returns it only if something remains. Otherwise it returns nothing.

Call relations: app_declarations_from_file calls this while building each AppDeclaration.

async fn plugin_telemetry_metadata_from_root(
    plugin_id: &PluginId,
    plugin_root: &AbsolutePathBuf,
) -> PluginTelemetryMetadata

Purpose: Builds lightweight telemetry information for a plugin folder. Telemetry here means summary data about capabilities, not the full loaded plugin.

Data flow: It receives a plugin id and plugin root. It reads the manifest, checks whether skills exist, gathers MCP server names, gathers app connector ids, and returns a PluginTelemetryMetadata summary. If the manifest is missing, it falls back to metadata made only from the plugin id.

Call relations: installed_plugin_telemetry_metadata calls this for installed plugins, and install_resolved_plugin uses it after installing a plugin.

Call graph: calls 9 internal fn (load_apps_from_paths, load_mcp_servers_from_file, plugin_app_config_paths, plugin_mcp_config_paths, plugin_skill_roots, load_plugin_manifest, from_plugin_id, as_key, as_path); called by 2 (installed_plugin_telemetry_metadata, install_resolved_plugin); 3 external calls (new, app_connector_ids_from_declarations, clone).

async fn load_plugin_mcp_servers(
    plugin_root: &Path,
    auth_mode: Option<AuthMode>,
) -> HashMap<String, McpServerConfig>

Purpose: Loads declared MCP servers for a plugin and applies app-based routing rules when those rules are available. Routing rules can adjust which app connector paths are active for the current authentication mode.

Data flow: It receives a plugin root and optional authentication mode. It loads declared MCP server configs, then, if app routing is available and servers exist, loads app declarations and applies the routing policy. It returns the final server map.

Call relations: Plugin detail readers call this when they need MCP server information with runtime app routing policy applied. It delegates basic server parsing to load_declared_plugin_mcp_servers.

Call graph: calls 4 internal fn (apply_app_mcp_routing_policy, apps_route_available, load_declared_plugin_mcp_servers, load_plugin_apps); called by 1 (read_plugin_detail_for_marketplace_plugin).

async fn load_declared_plugin_mcp_servers(plugin_root: &Path) -> HashMap<String, McpServerConfig>

Purpose: Loads MCP server definitions exactly as declared by a plugin, without auth-dependent app routing. It reads the manifest first so it knows which config paths to use.

Data flow: It receives a plugin root. If the manifest is missing, it returns an empty map. Otherwise it reads each MCP config file and inserts the first definition for each server name into the result map.

Call relations: load_plugin_mcp_servers calls this before applying app routing policy.

Call graph: calls 3 internal fn (load_mcp_servers_from_file, plugin_mcp_config_paths, load_plugin_manifest); called by 1 (load_plugin_mcp_servers); 1 external calls (new).

async fn installed_plugin_telemetry_metadata(
    codex_home: &Path,
    plugin_id: &PluginId,
) -> PluginTelemetryMetadata

Purpose: Builds telemetry metadata for an already installed plugin. It gracefully falls back to plugin-id-only metadata if the store cannot be opened or the plugin is not installed.

Data flow: It receives Codex home and a plugin id. It opens the plugin store, finds the active plugin root, then asks plugin_telemetry_metadata_from_root to inspect that folder. It returns the metadata summary.

Call relations: emit_plugin_toggle_events and uninstall_plugin_id call this when they need capability summary data for plugin lifecycle events.

Call graph: calls 3 internal fn (plugin_telemetry_metadata_from_root, try_new, from_plugin_id); called by 2 (emit_plugin_toggle_events, uninstall_plugin_id); 2 external calls (to_path_buf, warn!).

async fn load_mcp_servers_from_file(
    plugin_root: &Path,
    mcp_config_path: &AbsolutePathBuf,
) -> PluginMcpDiscovery

Purpose: Reads and parses one plugin MCP config file. It turns the file’s server definitions into runtime server config objects and logs parse problems.

Data flow: It receives the plugin root and MCP config path. It reads the file asynchronously, parses it with the plugin MCP parser, logs any file-level or server-level parse errors, and returns a discovery object containing the valid servers. If reading or parsing fails, it returns an empty discovery.

Call relations: load_plugin, load_declared_plugin_mcp_servers, and plugin_telemetry_metadata_from_root call this whenever they need MCP server definitions from a plugin file.

Call graph: calls 1 internal fn (as_path); called by 3 (load_declared_plugin_mcp_servers, load_plugin, plugin_telemetry_metadata_from_root); 4 external calls (parse_plugin_mcp_config, default, read_to_string, warn!).

fn materialize_marketplace_plugin_source(
    codex_home: &Path,
    source: &MarketplacePluginSource,
) -> Result<MaterializedMarketplacePluginSource, String>

Purpose: Turns a marketplace plugin source into a local directory path that can be installed. Local sources are used directly; git sources are cloned into a temporary staging folder.

Data flow: It receives Codex home and a marketplace source. For a local source, it returns that path. For a git source, it creates a staging temp directory, clones the repository, optionally checks out a ref or SHA and subpath, and returns the resulting path while keeping the temp directory alive.

Call relations: refresh_non_curated_plugin_cache_with_mode calls this before reading a plugin version and installing a marketplace plugin into the cache.

Call graph: calls 2 internal fn (clone_git_plugin_source, try_from); called by 1 (refresh_non_curated_plugin_cache_with_mode); 3 external calls (join, create_dir_all, new).

fn clone_git_plugin_source(
    url: &str,
    ref_name: Option<&str>,
    sha: Option<&str>,
    sparse_checkout_path: Option<&str>,
    destination: &Path,
) -> Result<(), String>

Purpose: Clones a git-based plugin source into a destination folder. It supports sparse checkout, which means downloading only a selected subfolder when the plugin lives inside a larger repository.

Data flow: It receives a git URL, optional ref name, optional SHA, optional sparse path, and destination. It runs the needed git commands to clone, configure sparse checkout if requested, and check out the target commit or branch. It returns success or an error string.

Call relations: materialize_marketplace_plugin_source calls this when a marketplace plugin source is a git repository. It uses run_git for each actual git command.

Call graph: calls 1 internal fn (run_git); called by 1 (materialize_marketplace_plugin_source); 1 external calls (to_string_lossy).

fn run_git(args: &[&str], cwd: Option<&Path>) -> Result<(), String>

Purpose: Runs one git command and converts failure output into a readable error message. It also disables interactive terminal prompts so background operations do not hang waiting for user input.

Data flow: It receives git arguments and an optional working directory. It starts the git process with those arguments, captures stdout and stderr, and returns success only if git exits successfully. On failure it returns a message containing the command, status, stdout, and stderr.

Call relations: clone_git_plugin_source uses this for clone, sparse-checkout, and checkout commands.

Call graph: called by 1 (clone_git_plugin_source); 2 external calls (new, format!).

fn new(
        config_layer_stack: ConfigLayerStack,
        plugins_enabled: bool,
        remote_plugin_enabled: bool,
        chatgpt_base_url: String,
    ) -> Self

Purpose: Builds the small bundle of settings the plugin manager needs for one run or request. It keeps the configuration layers, feature switches, and ChatGPT service address together.

Data flow: It receives a config layer stack, two booleans saying whether plugins and remote plugins are enabled, and a base URL. It stores those values unchanged in a PluginsConfigInput object and returns it.

Call relations: Configuration-loading helpers call this when they need to pass plugin settings into the manager as one clear package.

Call graph: called by 2 (load_plugins_config, plugins_config_input).

fn remote_plugin_service_config(config: &PluginsConfigInput) -> RemotePluginServiceConfig

Purpose: Turns the broader plugin configuration into the smaller remote-service configuration used for network calls. This avoids repeating how the ChatGPT base URL is picked.

Data flow: It reads the ChatGPT base URL from PluginsConfigInput, copies it into a RemotePluginServiceConfig, and returns that lightweight object.

Call relations: Remote-facing manager methods call this just before they fetch catalogs, sync installed plugins, or send install/uninstall mutations to the backend.

Call graph: called by 9 (build_and_cache_remote_installed_plugin_marketplaces, cached_global_remote_discoverable_plugins_for_config, featured_plugin_ids_for_config, install_plugin_with_remote_sync, maybe_start_global_remote_catalog_cache_refresh, maybe_start_plugin_startup_tasks_for_config, maybe_start_remote_installed_plugin_bundle_sync, maybe_start_remote_installed_plugins_cache_refresh_with_notify, uninstall_plugin_with_remote_sync).

fn featured_plugin_ids_cache_key(
    config: &PluginsConfigInput,
    auth: Option<&CodexAuth>,
) -> FeaturedPluginIdsCacheKey

Purpose: Creates the identity for cached featured-plugin results. Featured plugins can differ by server, account, user, and workspace status, so the cache key includes all of those.

Data flow: It takes the current plugin config and optional authentication. It copies the base URL and, when available, extracts account ID, ChatGPT user ID, and workspace-account status, then returns a key object.

Call relations: featured_plugin_ids_for_config uses this before checking or writing the featured-plugin cache so one user’s featured list is not reused for the wrong context.

Call graph: called by 1 (featured_plugin_ids_for_config).

fn recommended_plugins_cache_key(config: &PluginsConfigInput) -> RecommendedPluginsCacheKey

Purpose: Creates the identity for cached recommended-plugin mode results. In this file, that cache is separated by ChatGPT base URL.

Data flow: It reads the base URL from PluginsConfigInput, places it in a cache-key object, and returns it.

Call relations: recommended_plugins_mode_for_config uses this key to share one in-flight or completed remote lookup for the same service endpoint.

Call graph: called by 1 (recommended_plugins_mode_for_config).

fn from(value: PluginDetail) -> Self

Purpose: Converts detailed marketplace information into a short capability summary safe to show to the model or prompt-building code. It keeps only the plugin name, safe description, and exposed capability names.

Data flow: It receives a full PluginDetail, checks whether it has any non-disabled skills, sanitizes the description for prompt use, and returns a PluginCapabilitySummary with skill, MCP server, and app connector information.

Call relations: This conversion is used when a detailed plugin record needs to become a compact capability record. It delegates description cleanup to prompt_safe_plugin_description.

Call graph: 1 external calls (prompt_safe_plugin_description).

fn new(codex_home: PathBuf) -> Self

Purpose: Creates a normal plugin manager for a Codex home directory. This is the simple constructor most callers use.

Data flow: It receives the path to CODEX_HOME, then calls the more flexible constructor with Codex product restrictions and no initial authentication mode. The result is a ready-to-use manager.

Call relations: Command handlers, login/logout flows, migration checks, and plugin commands call this when they need access to plugin operations without special test options.

Call graph: called by 84 (detect_migrations, import_plugins, run_list, run_upgrade, run_get, run_list, run_login, run_logout, load_plugin_command_context, deduplicates_configured_marketplace_plugin (+15 more)); 1 external calls (new_with_options).

fn new_with_options(
        codex_home: PathBuf,
        restriction_product: Option<Product>,
        auth_mode: Option<AuthMode>,
    ) -> Self

Purpose: Creates a plugin manager with explicit product and authentication settings. This is useful for tests and for callers that need product-specific plugin restrictions.

Data flow: It receives a home directory, an optional product restriction, and an optional authentication mode. It creates the plugin store, initializes locks, caches, background-task state, and semaphores, then returns the manager.

Call relations: PluginsManager::new calls this for the common case, while tests and specialized loading paths call it directly to control product or auth behavior.

Call graph: calls 1 internal fn (new); called by 14 (featured_plugin_ids_for_config_defaults_query_param_to_codex, featured_plugin_ids_for_config_uses_restriction_product_query_param, load_plugins_from_config, plugin_auth_projection_hides_apps_without_chatgpt_auth, plugin_auth_projection_hides_dual_surface_mcp_with_agent_identity_apps_route, plugin_auth_projection_hides_matching_mcp_with_chatgpt_apps_route, plugin_auth_projection_keeps_non_conflicting_mcp_with_chatgpt_apps_route, plugin_auth_projection_preserves_duplicate_connector_declaration_names, plugin_auth_projection_reprojects_cached_plugins_when_auth_changes, plugins_manager_tracks_auth_mode (+4 more)); 9 external calls (new, clone, new, new, default, default, default, default, default).

fn set_auth_mode(&self, auth_mode: Option<AuthMode>) -> bool

Purpose: Updates the authentication mode remembered by the plugin manager. This matters because some app and MCP capabilities are only shown for certain login modes.

Data flow: It receives a new optional authentication mode, compares it with the stored one, and writes it only if it changed. It returns true when a change happened and false otherwise.

Call relations: Other parts of the app can call this after login state changes. Later plugin reads and loads use auth_mode to project the right capabilities.

fn auth_mode(&self) -> Option<AuthMode>

Purpose: Reads the manager’s current authentication mode. Callers use it to decide which plugin app or MCP capabilities should be visible.

Data flow: It reads the protected stored value, recovers gracefully if the lock was poisoned, and returns the optional authentication mode.

Call relations: resolve_loaded_plugins_for_auth and read_plugin_detail_for_marketplace_plugin call this before applying app/MCP routing rules.

Call graph: called by 2 (read_plugin_detail_for_marketplace_plugin, resolve_loaded_plugins_for_auth).

fn set_analytics_events_client(&self, analytics_events_client: AnalyticsEventsClient)

Purpose: Stores the analytics client used to record plugin install and uninstall events. If this is not set, those user actions still work but are not tracked here.

Data flow: It receives an analytics client and saves it inside the manager behind a lock. It does not return a value.

Call relations: Install and uninstall internals later read this stored client and send telemetry when one is available.

fn restriction_product_matches(&self, products: Option<&[Product]>) -> bool

Purpose: Checks whether a plugin or marketplace entry is allowed for the current product. This prevents plugins intended for another product from being listed, read, or installed through this manager.

Data flow: It receives an optional list of allowed products. If there is no restriction list, it returns true; if the list is empty, false; otherwise it compares the manager’s product against the allowed list.

Call relations: Marketplace listing and plugin detail reading use this check before exposing a plugin to the caller.

Call graph: called by 2 (read_plugin_detail_for_marketplace_plugin, read_plugin_for_config).

async fn plugins_for_config(&self, config: &PluginsConfigInput) -> PluginLoadOutcome

Purpose: Loads the effective plugins for a given configuration using the normal cache. This is the main path for callers that need currently active plugin capabilities.

Data flow: It receives PluginsConfigInput and forwards it to the force-reload variant with force reload turned off. It returns a PluginLoadOutcome.

Call relations: MCP configuration building and hook building call this when they need the active plugin set.

Call graph: calls 1 internal fn (plugins_for_config_with_force_reload); called by 2 (to_mcp_config_with_plugin_registrations, build_hooks_for_config).

async fn plugins_for_config_with_force_reload(
        &self,
        config: &PluginsConfigInput,
        force_reload: bool,
    ) -> PluginLoadOutcome

Purpose: Loads active plugins, optionally bypassing the cache. It avoids expensive reloads when the relevant configuration has not changed.

Data flow: It first returns an empty outcome if plugins are disabled. Otherwise it builds a cache key from configured plugins, skill rules, and remote-plugin status; tries the cache; serializes real loading with a semaphore; loads from the config layer stack and remote-installed cache; logs load errors; writes the cache if still current; and returns capabilities adjusted for auth.

Call relations: plugins_for_config uses this as the main implementation. It hands actual filesystem/config loading to loader functions and hands final auth filtering to resolve_loaded_plugins_for_auth.

Call graph: calls 10 internal fn (load_plugins_from_layer_stack, log_plugin_load_errors, cache_loaded_plugins_if_current, cached_loaded_plugins, loaded_plugins_cache_generation, remote_installed_plugin_configs, resolve_loaded_plugins_for_auth, configured_plugins_from_stack, skill_config_rules_from_stack, default); called by 1 (plugins_for_config); 2 external calls (acquire, warn!).

fn resolve_loaded_plugins_for_auth(&self, mut plugins: Vec<LoadedPlugin>) -> PluginLoadOutcome

Purpose: Applies the current login-mode rules to already loaded plugins. This makes sure app connectors and MCP servers line up with whether the user is authenticated in the needed way.

Data flow: It receives loaded plugins, reads the current auth mode, applies routing policy to each plugin’s apps and MCP servers, and converts the adjusted list into a PluginLoadOutcome.

Call relations: Both cached and freshly loaded plugin paths call this just before returning plugin capabilities to the rest of the system.

Call graph: calls 3 internal fn (apply_app_mcp_routing_policy, auth_mode, from_plugins); called by 2 (plugins_for_config_with_force_reload, plugins_for_layer_stack).

fn clear_cache(&self)

Purpose: Clears the manager’s main plugin-related caches. This is used when plugin files, marketplaces, or curated data may have changed.

Data flow: It invalidates the loaded-plugin cache and removes the cached featured-plugin IDs. It does not return a value.

Call relations: Cache refresh and marketplace-upgrade flows call this after changes so later plugin loads see fresh data.

Call graph: calls 1 internal fn (clear_loaded_plugins_cache); called by 2 (run_non_curated_plugin_cache_refresh_loop, upgrade_configured_marketplaces_for_config).

fn clear_recommended_plugins_cache(&self)

Purpose: Clears cached recommended-plugin mode information and any remembered in-flight refresh markers. This forces the next request to ask again.

Data flow: It locks and empties the map of in-flight recommendation lookups, then locks and empties the completed recommendation cache. Nothing is returned.

Call relations: This is a maintenance hook for callers that know recommendation state should be recomputed.

fn clear_loaded_plugins_cache(&self)

Purpose: Invalidates the cached active plugin list. It also bumps a generation number so an older load cannot overwrite a newer invalidation.

Data flow: It takes the cache write lock, increments the generation counter with wrapping arithmetic, and removes the cached entry.

Call relations: Higher-level cache clearing and remote-installed cache updates call this when effective plugins may have changed.

Call graph: called by 3 (clear_cache, clear_remote_installed_plugins_cache, write_remote_installed_plugins_cache).

async fn plugins_for_layer_stack(
        &self,
        config_layer_stack: &ConfigLayerStack,
        config: &PluginsConfigInput,
    ) -> PluginLoadOutcome

Purpose: Loads plugins for a supplied configuration layer stack without using or changing the manager’s loaded-plugin cache. This is useful for temporary or alternate config views.

Data flow: It returns an empty outcome if plugins are disabled. Otherwise it loads plugins from the provided layer stack plus remote-installed config, then applies auth-based capability filtering and returns the outcome.

Call relations: effective_skill_roots_for_layer_stack calls this when it only needs skill roots, and callers can use it when cache isolation matters.

Call graph: calls 4 internal fn (load_plugins_from_layer_stack, remote_installed_plugin_configs, resolve_loaded_plugins_for_auth, default); called by 1 (effective_skill_roots_for_layer_stack).

async fn plugin_hooks_for_layer_stack(
        &self,
        config_layer_stack: &ConfigLayerStack,
        config: &PluginsConfigInput,
    ) -> PluginHookLoadOutcome

Purpose: Loads only plugin hooks for a supplied configuration layer stack. Hooks are plugin-declared actions triggered by named events.

Data flow: It returns an empty hook outcome if plugins are disabled. Otherwise it asks the loader for hooks using the supplied layer stack, remote-installed configs, the store, and the remote-plugin feature flag.

Call relations: This is a lighter-weight path than full plugin loading when the caller only needs hook declarations.

Call graph: calls 2 internal fn (load_plugin_hooks_from_layer_stack, remote_installed_plugin_configs); 1 external calls (default).

async fn effective_skill_roots_for_layer_stack(
        &self,
        config_layer_stack: &ConfigLayerStack,
        config: &PluginsConfigInput,
    ) -> Vec<PluginSkillRoot>

Purpose: Returns the skill root directories that are active for a supplied configuration layer stack. Skills are plugin-provided instruction or capability files.

Data flow: It loads plugins through plugins_for_layer_stack, then extracts the effective skill roots from the resulting load outcome.

Call relations: It builds directly on the uncached layer-stack loading path so callers get skill roots for exactly the stack they supplied.

Call graph: calls 1 internal fn (plugins_for_layer_stack).

fn cached_loaded_plugins(&self, key: &PluginLoadCacheKey) -> Option<Vec<LoadedPlugin>>

Purpose: Looks for a cached active-plugin list that matches the requested loading conditions. It prevents repeated disk and config work.

Data flow: It reads the loaded-plugin cache, compares the stored key with the requested key, and returns a cloned plugin list only when they match.

Call relations: plugins_for_config_with_force_reload checks this before and after waiting for the load semaphore.

Call graph: called by 1 (plugins_for_config_with_force_reload).

fn loaded_plugins_cache_generation(&self) -> u64

Purpose: Reads the current loaded-plugin cache generation. The generation is a simple version stamp used to avoid writing stale load results.

Data flow: It reads the cache state and returns its generation number.

Call relations: plugins_for_config_with_force_reload records this before doing a real load, then cache_loaded_plugins_if_current checks it afterward.

Call graph: called by 1 (plugins_for_config_with_force_reload).

fn cache_loaded_plugins_if_current(
        &self,
        generation: u64,
        key: PluginLoadCacheKey,
        plugins: Vec<LoadedPlugin>,
    )

Purpose: Writes freshly loaded plugins into the cache only if no invalidation happened while loading. This avoids reintroducing old data after a cache clear.

Data flow: It receives the generation seen before loading, a cache key, and the loaded plugin list. If the current generation is unchanged, it stores the key and plugins; otherwise it discards them.

Call relations: plugins_for_config_with_force_reload calls this after loading from the layer stack.

Call graph: called by 1 (plugins_for_config_with_force_reload).

fn remote_installed_plugin_configs(&self) -> HashMap<String, PluginConfig>

Purpose: Converts the cached remote-installed plugin list into local plugin configuration entries. This lets remote-installed plugins participate in the same loading path as locally configured plugins.

Data flow: It reads the remote-installed cache. If it is empty, it returns an empty map; otherwise it asks the remote helper to translate those plugins into PluginConfig values using the local store.

Call relations: Plugin and hook loading paths call this before invoking the loader so remote-installed plugins can be included when enabled.

Call graph: calls 1 internal fn (remote_installed_plugins_to_config); called by 3 (plugin_hooks_for_layer_stack, plugins_for_config_with_force_reload, plugins_for_layer_stack); 1 external calls (new).

fn build_remote_installed_plugin_marketplaces_from_cache(
        &self,
        visible_marketplaces: &[&str],
    ) -> Option<Vec<crate::remote::RemoteMarketplace>>

Purpose: Builds marketplace-shaped data from the cached remote-installed plugins. This is a quick read path that avoids a network request.

Data flow: It reads the remote-installed cache. If no cache exists, it returns None; otherwise it groups the cached plugins by visible marketplaces and returns that list.

Call relations: Callers that already trust the local remote-installed cache can use this instead of fetching fresh remote state.

Call graph: calls 1 internal fn (group_remote_installed_plugins_by_marketplaces).

fn cached_global_remote_discoverable_plugins_for_config(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
    ) -> Vec<crate::remote::RemoteDiscoverablePlugin>

Purpose: Reads discoverable remote plugins from the global on-disk cache when the current config and auth allow it. Discoverable plugins are remote plugins the user may be able to browse or add.

Data flow: It first checks that plugins and remote plugins are enabled, that the auth uses the Codex backend, and that an account ID exists. If any check fails it returns an empty list; otherwise it reads cached remote discoverable plugins for the service config.

Call relations: This is a cache-only companion to background catalog refresh tasks, letting UI or listing code show what is already warmed.

Call graph: calls 2 internal fn (remote_plugin_service_config, cached_global_remote_discoverable_plugins); 2 external calls (as_path, new).

async fn build_and_cache_remote_installed_plugin_marketplaces(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
        visible_marketplaces: &[&str],
        on_e

Purpose: Fetches the user’s remote-installed plugins, saves them locally, and returns them grouped as marketplaces. It also notifies the app when the effective plugin set changed.

Data flow: It receives config, auth, visible marketplace names, and an optional callback. It fetches remote installed plugins, groups them by marketplace, writes the cache, calls the callback if the cache changed, and returns the grouped marketplaces or an error.

Call relations: This is the direct refresh-and-return path for callers that need fresh remote installed marketplace data immediately.

Call graph: calls 4 internal fn (write_remote_installed_plugins_cache, remote_plugin_service_config, fetch_remote_installed_plugins, group_remote_installed_plugins_by_marketplaces).

fn write_remote_installed_plugins_cache(&self, plugins: Vec<RemoteInstalledPlugin>) -> bool

Purpose: Stores a newly fetched remote-installed plugin list if it differs from the current cache. Changing this cache can change which plugins load locally.

Data flow: It compares the incoming plugin list with the cached one. If identical, it returns false; if different, it replaces the cache, clears the loaded-plugin cache, and returns true.

Call relations: Immediate remote fetches and the background remote-installed refresh loop call this after successful remote reads.

Call graph: calls 1 internal fn (clear_loaded_plugins_cache); called by 2 (build_and_cache_remote_installed_plugin_marketplaces, run_remote_installed_plugins_cache_refresh_loop).

fn clear_remote_installed_plugins_cache(&self) -> bool

Purpose: Removes cached remote-installed plugin state. This is needed when authentication no longer allows reading remote plugins.

Data flow: It checks whether the cache exists. If not, it returns false; otherwise it clears the cache, invalidates loaded plugins, and returns true.

Call relations: The remote-installed refresh loop calls this when the backend says auth is required or unsupported.

Call graph: calls 1 internal fn (clear_loaded_plugins_cache); called by 1 (run_remote_installed_plugins_cache_refresh_loop).

fn maybe_start_remote_plugin_caches_refresh(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        on_effective_plugins_changed: Option<Arc<dyn Fn() +

Purpose: Starts background refreshes for remote plugin state when plugins are enabled. It refreshes installed plugins and also warms the recommended-plugin mode.

Data flow: It schedules a remote-installed cache refresh, then spawns an asynchronous task that asks for recommended-plugin mode. It returns immediately.

Call relations: maybe_start_plugin_list_background_tasks_for_config and startup flows use this so remote state updates happen behind the scenes.

Call graph: calls 1 internal fn (maybe_start_remote_installed_plugins_cache_refresh_with_notify); called by 1 (maybe_start_plugin_list_background_tasks_for_config); 3 external calls (clone, clone, spawn).

fn maybe_start_remote_installed_plugins_cache_refresh_after_mutation(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        on_effective_plugins_chang

Purpose: Schedules a remote-installed cache refresh after a remote install or uninstall mutation. It asks the refresh path to notify after any successful refresh, even if the installed list looks unchanged.

Data flow: It wraps the config, auth, notification mode, and optional callback and forwards them to the shared scheduling helper.

Call relations: Bundle-sync callbacks use this after local or remote mutation work so MCP refreshes happen after the installed cache is updated.

Call graph: calls 1 internal fn (maybe_start_remote_installed_plugins_cache_refresh_with_notify).

fn maybe_start_remote_installed_plugins_cache_refresh_with_notify(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        notify: RemoteInstalledPlugin

Purpose: Shared helper for scheduling remote-installed plugin cache refreshes with a chosen notification rule. It skips all work if plugins are disabled.

Data flow: It checks the plugin feature flag, builds a remote service config, packages auth and callback information into a refresh request, and hands it to the scheduler.

Call relations: Both normal remote cache warming and after-mutation refreshes pass through this method.

Call graph: calls 2 internal fn (schedule_remote_installed_plugins_cache_refresh, remote_plugin_service_config); called by 2 (maybe_start_remote_installed_plugins_cache_refresh_after_mutation, maybe_start_remote_plugin_caches_refresh).

fn maybe_start_remote_installed_plugin_bundle_sync(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        on_effective_plugins_changed: Option<Arc<dyn

Purpose: Starts background synchronization of local bundles for plugins installed remotely. A bundle is the local copy needed to run a remote-installed plugin.

Data flow: If plugins are disabled, it returns. Otherwise it builds a callback that will refresh the remote-installed cache after local bundle changes, then asks the remote module to start bundle sync.

Call relations: Plugin-list background tasks and startup tasks call this so remote-installed plugins have usable local files.

Call graph: calls 1 internal fn (remote_plugin_service_config); called by 1 (maybe_start_plugin_list_background_tasks_for_config); 5 external calls (clone, new, clone, clone, maybe_start_remote_installed_plugin_bundle_sync).

fn maybe_start_global_remote_catalog_cache_refresh(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
    )

Purpose: Schedules a background refresh of the global remote plugin catalog. It only runs when both plugins and remote plugins are enabled.

Data flow: It checks feature flags, builds a service config with auth, and submits a global catalog refresh request to the scheduler.

Call relations: Plugin-list background tasks call this when their options request a global remote catalog refresh.

Call graph: calls 2 internal fn (schedule_global_remote_catalog_cache_refresh, remote_plugin_service_config); called by 1 (maybe_start_plugin_list_background_tasks_for_config).

fn maybe_start_plugin_list_background_tasks_for_config(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth: Option<CodexAuth>,
        roots: &[AbsolutePathBuf],
        optio

Purpose: Kicks off the background jobs that make plugin listing fresher over time. It does not wait for those jobs to finish.

Data flow: It receives config, auth, marketplace roots, options, and a callback. It schedules non-curated cache refresh, maybe global remote catalog refresh, remote plugin cache refresh, and remote bundle sync.

Call relations: Listing code can call this after returning or while preparing plugin lists so caches are warmed for later requests.

Call graph: calls 4 internal fn (maybe_start_global_remote_catalog_cache_refresh, maybe_start_non_curated_plugin_cache_refresh, maybe_start_remote_installed_plugin_bundle_sync, maybe_start_remote_plugin_caches_refresh).

fn cached_featured_plugin_ids(
        &self,
        cache_key: &FeaturedPluginIdsCacheKey,
    ) -> Option<Vec<String>>

Purpose: Reads featured-plugin IDs from the short-lived in-memory cache. It also clears expired or wrong-context entries.

Data flow: It checks the cached entry against the supplied key and expiration time. If valid, it returns a cloned list; otherwise it removes stale data and returns None.

Call relations: featured_plugin_ids_for_config calls this before making a remote featured-plugin request.

Call graph: called by 1 (featured_plugin_ids_for_config); 1 external calls (now).

fn write_featured_plugin_ids_cache(
        &self,
        cache_key: FeaturedPluginIdsCacheKey,
        featured_plugin_ids: &[String],
    )

Purpose: Stores featured-plugin IDs in memory with an expiration time. This reduces repeated network calls for the same user and server.

Data flow: It receives a cache key and list of IDs, copies the IDs, sets an expiry three hours in the future, and writes the cache entry.

Call relations: featured_plugin_ids_for_config calls this after successfully fetching featured IDs from the remote legacy service.

Call graph: called by 1 (featured_plugin_ids_for_config); 1 external calls (now).

async fn featured_plugin_ids_for_config(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
    ) -> Result<Vec<String>, RemotePluginFetchError>

Purpose: Returns the plugin IDs that should be featured for the current config and auth. It uses a cache first and falls back to a remote request.

Data flow: If plugins are disabled it returns an empty list. Otherwise it builds a cache key, returns cached IDs when available, fetches remote featured IDs when not, writes them to cache, and returns them.

Call relations: Startup warming and callers that need featured plugin ordering use this path.

Call graph: calls 5 internal fn (cached_featured_plugin_ids, write_featured_plugin_ids_cache, featured_plugin_ids_cache_key, remote_plugin_service_config, fetch_remote_featured_plugin_ids); 1 external calls (new).

async fn recommended_plugins_mode_for_config(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
    ) -> RecommendedPluginsMode

Purpose: Determines whether the app should use the newer remote recommended-plugin behavior or the legacy behavior. It coalesces simultaneous requests so only one remote fetch happens per key.

Data flow: It returns legacy mode if plugins, remote plugins, or suitable auth are missing. Otherwise it checks the cache, joins or creates an in-flight OnceCell refresh, fetches the mode from the remote service, stores successful results, falls back to legacy on error, removes the in-flight marker, and returns the mode.

Call relations: Remote cache warming calls this in the background, while UI or plugin listing code can call it directly when deciding how recommendations should work.

Call graph: calls 2 internal fn (cached_recommended_plugins_mode, recommended_plugins_cache_key).

fn cached_recommended_plugins_mode(
        &self,
        cache_key: &RecommendedPluginsCacheKey,
    ) -> Option<RecommendedPluginsMode>

Purpose: Reads a cached recommended-plugin mode for a service endpoint. It is the simple lookup used by the fuller refresh method.

Data flow: It locks the recommendation cache, looks up the supplied key, clones the stored mode if present, and returns it.

Call relations: recommended_plugins_mode_for_config calls this before and during refresh setup to avoid unnecessary remote work.

Call graph: called by 1 (recommended_plugins_mode_for_config).

async fn install_plugin(
        &self,
        request: PluginInstallRequest,
    ) -> Result<PluginInstallOutcome, PluginInstallError>

Purpose: Installs a plugin from a marketplace without doing a remote backend mutation first. This is the local install path.

Data flow: It receives a marketplace path and plugin name, resolves that marketplace entry as installable under the product restriction, then passes the resolved plugin to the shared install routine.

Call relations: Command and UI install flows use this when local marketplace installation is enough.

Call graph: calls 2 internal fn (install_resolved_plugin, find_installable_marketplace_plugin).

async fn install_plugin_with_remote_sync(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
        request: PluginInstallRequest,
    ) -> Result<PluginInstallOutc

Purpose: Installs a plugin while first telling the legacy remote service to enable it. This keeps older remote plugin state in sync with local installation.

Data flow: It resolves the plugin from the marketplace, sends an enable mutation to the remote legacy service using config and auth, then installs the resolved plugin locally through the shared install routine.

Call relations: Remote-aware install flows use this when the backend must be updated before local files and config are changed.

Call graph: calls 4 internal fn (install_resolved_plugin, remote_plugin_service_config, find_installable_marketplace_plugin, enable_remote_plugin).

async fn install_resolved_plugin(
        &self,
        resolved: ResolvedMarketplacePlugin,
    ) -> Result<PluginInstallOutcome, PluginInstallError>

Purpose: Performs the actual local install once a marketplace plugin has already been resolved. It copies or materializes plugin source, records version information, enables the plugin, and sends analytics.

Data flow: It receives a resolved marketplace plugin. For curated OpenAI plugins it reads the curated repository version; then it runs blocking store installation off the async runtime, enables the plugin in user config, optionally tracks telemetry, and returns the installed plugin ID, version, path, and auth policy.

Call relations: Both public install methods delegate here after marketplace resolution and any optional remote mutation.

Call graph: calls 3 internal fn (curated_plugin_cache_version, plugin_telemetry_metadata_from_root, read_curated_plugins_sha); called by 2 (install_plugin, install_plugin_with_remote_sync); 6 external calls (as_path, clone, set_user_plugin_enabled, clone, is_openai_curated_marketplace_name, spawn_blocking).

async fn uninstall_plugin(&self, plugin_id: String) -> Result<(), PluginUninstallError>

Purpose: Uninstalls a plugin by its string ID using only local state. It parses the ID before doing the shared uninstall work.

Data flow: It receives a plugin ID string, parses it into a structured PluginId, then calls uninstall_plugin_id. It returns success or an uninstall error.

Call relations: Local uninstall flows call this when no remote backend mutation is needed.

Call graph: calls 2 internal fn (uninstall_plugin_id, parse).

async fn uninstall_plugin_with_remote_sync(
        &self,
        config: &PluginsConfigInput,
        auth: Option<&CodexAuth>,
        plugin_id: String,
    ) -> Result<(), PluginUninstallError>

Purpose: Uninstalls a plugin while first telling the legacy remote service to remove it. This keeps backend state aligned with local removal.

Data flow: It parses the plugin ID string, sends an uninstall mutation to the remote legacy service using config and auth, then calls the shared local uninstall routine.

Call relations: Remote-aware uninstall flows use this path until remote plugins have a separate installed-state manager.

Call graph: calls 4 internal fn (uninstall_plugin_id, remote_plugin_service_config, uninstall_remote_plugin, parse).

async fn uninstall_plugin_id(&self, plugin_id: PluginId) -> Result<(), PluginUninstallError>

Purpose: Performs the actual local uninstall for a parsed plugin ID. It removes plugin files, clears user config, and optionally records analytics.

Data flow: It checks whether an active plugin root exists and gathers telemetry if so. It runs the blocking store uninstall on a blocking task, clears the plugin from user config, sends uninstall analytics when possible, and returns success.

Call relations: Both public uninstall methods call this after parsing and any optional remote mutation.

Call graph: calls 3 internal fn (installed_plugin_telemetry_metadata, active_plugin_root, as_key); called by 2 (uninstall_plugin, uninstall_plugin_with_remote_sync); 5 external calls (as_path, clear_user_plugin, clone, clone, spawn_blocking).

fn list_marketplaces_for_config(
        &self,
        config: &PluginsConfigInput,
        additional_roots: &[AbsolutePathBuf],
        include_openai_curated: bool,
    ) -> Result<ConfiguredMarke

Purpose: Lists configured marketplaces and their plugins with installed and enabled state added. It is the main marketplace listing view for local and curated sources.

Data flow: If plugins are disabled it returns an empty outcome. Otherwise it gathers configured plugin states, computes marketplace roots, reads marketplaces, removes duplicate plugin keys, filters by product restriction, fills in installed version and manifest details when available, and returns marketplaces plus any listing errors.

Call relations: Higher-level marketplace lookup and verification helpers call this when they need a complete configured marketplace view.

Call graph: calls 3 internal fn (configured_plugin_states, marketplace_roots, list_marketplaces); called by 3 (configured_marketplace_plugins, find_marketplace_for_plugin, verified_plugin_install_completed); 2 external calls (new, default).

fn discover_marketplaces_for_config(
        &self,
        config: &PluginsConfigInput,
        additional_roots: &[AbsolutePathBuf],
    ) -> Result<MarketplaceListOutcome, MarketplaceError>

Purpose: Discovers marketplace files or roots available for the current configuration. Unlike the richer list method, it returns the raw marketplace listing outcome.

Data flow: It returns an empty listing if plugins are disabled. Otherwise it computes marketplace roots including the curated marketplace and asks the marketplace module to list them.

Call relations: Callers use this when they need marketplace discovery rather than per-plugin installed/enabled decoration.

Call graph: calls 2 internal fn (marketplace_roots, list_marketplaces); 1 external calls (default).

async fn read_plugin_for_config(
        &self,
        config: &PluginsConfigInput,
        request: &PluginReadRequest,
    ) -> Result<PluginReadOutcome, MarketplaceError>

Purpose: Reads detailed information for one plugin from a specific marketplace. It adds local installed/enabled state before loading deeper details.

Data flow: It rejects the request if plugins are disabled. It finds the marketplace plugin, checks product restrictions, computes whether it is installed and enabled, builds a configured plugin record, then calls read_plugin_detail_for_marketplace_plugin and wraps the result with marketplace information.

Call relations: Plugin detail endpoints or commands call this when the user selects a specific marketplace plugin.

Call graph: calls 5 internal fn (configured_plugin_states, read_plugin_detail_for_marketplace_plugin, restriction_product_matches, find_marketplace_plugin, active_plugin_version).

async fn read_plugin_detail_for_marketplace_plugin(
        &self,
        config: &PluginsConfigInput,
        marketplace_name: &str,
        plugin: ConfiguredMarketplacePlugin,
    ) -> Result<Plu

Purpose: Builds a full detail record for one marketplace plugin. It reads the manifest, skills, hooks, app connectors, MCP servers, and availability information when possible.

Data flow: It checks product restrictions and validates the plugin ID. For uninstalled Git plugins it returns a limited record explaining that installation is needed. Otherwise it finds or materializes the source directory, loads the manifest, combines marketplace category information, loads skills with config rules, loads hooks, apps, and MCP servers, applies auth routing, deduplicates and sorts capability names, and returns a PluginDetail.

Call relations: read_plugin_for_config calls this after locating a marketplace entry. It delegates source, manifest, skill, hook, app, and MCP reading to specialized loader functions.

Call graph: calls 14 internal fn (apply_app_mcp_routing_policy, load_plugin_apps, load_plugin_hooks, load_plugin_mcp_servers, load_plugin_skills, auth_mode, restriction_product_matches, remote_plugin_install_required_description, load_plugin_manifest, plugin_interface_with_marketplace_category (+4 more)); called by 1 (read_plugin_for_config); 9 external calls (new, new, clone, new, plugin_hook_declarations, app_connector_ids_from_declarations, InvalidPlugin, matches!, spawn_blocking).

fn maybe_start_plugin_startup_tasks_for_config(
        self: &Arc<Self>,
        config: &PluginsConfigInput,
        auth_manager: Arc<AuthManager>,
        on_effective_plugins_changed: Option<Arc<

Purpose: Starts plugin-related background work at application startup. It warms caches and upgrades marketplace data without blocking startup.

Data flow: If plugins are enabled, it starts curated repo sync, maybe starts a single marketplace auto-upgrade thread, spawns async work to refresh remote installed state and global remote catalog, and spawns another task to warm featured-plugin IDs.

Call relations: Startup code calls this once the manager and authentication manager exist. It fans out to curated sync, marketplace upgrade, remote cache refresh, bundle sync, and featured-cache warming.

Call graph: calls 3 internal fn (start_curated_repo_sync, remote_plugin_service_config, fetch_and_cache_global_remote_plugin_catalog); 5 external calls (clone, clone, new, spawn, warn!).

fn upgrade_configured_marketplaces_for_config(
        &self,
        config: &PluginsConfigInput,
        marketplace_name: Option<&str>,
    ) -> Result<ConfiguredMarketplaceUpgradeOutcome, String>

Purpose: Upgrades configured Git marketplaces, optionally limited to one marketplace name. After an upgrade, it refreshes installed plugin caches so local plugin bundles match the new marketplace contents.

Data flow: It validates the requested marketplace name if one was provided, runs the Git marketplace upgrade helper, and if roots were upgraded, force-refreshes the non-curated plugin cache. It clears caches on refresh changes or errors and returns the upgrade outcome.

Call relations: Startup auto-upgrade and explicit upgrade commands use this to keep configured Git marketplace checkouts current.

Call graph: calls 4 internal fn (refresh_non_curated_plugin_cache_force_reinstall, clear_cache, configured_git_marketplace_names, upgrade_configured_git_marketplaces); 2 external calls (as_path, format!).

fn maybe_start_non_curated_plugin_cache_refresh(
        self: &Arc<Self>,
        roots: &[AbsolutePathBuf],
    )

Purpose: Schedules a background refresh for non-curated marketplace plugin caches. Non-curated means not the built-in OpenAI-curated catalog.

Data flow: It receives marketplace roots and forwards them to the scheduler with the normal “only if version changed” mode.

Call relations: Plugin-list background task setup calls this before listing-related remote refreshes.

Call graph: calls 1 internal fn (schedule_non_curated_plugin_cache_refresh); called by 1 (maybe_start_plugin_list_background_tasks_for_config).

fn schedule_remote_installed_plugins_cache_refresh(
        self: &Arc<Self>,
        mut request: RemoteInstalledPluginsCacheRefreshRequest,
    )

Purpose: Queues and, if needed, starts the worker that refreshes remote-installed plugin state. It collapses repeated requests so only one worker loop is active.

Data flow: It merges the new request with any pending request, preserving stronger notification needs and callbacks, stores it, and starts an async worker if none is running.

Call relations: The remote-installed refresh helper calls this after checking feature flags and building the request.

Call graph: called by 1 (maybe_start_remote_installed_plugins_cache_refresh_with_notify); 3 external calls (clone, matches!, spawn).

fn schedule_global_remote_catalog_cache_refresh(
        self: &Arc<Self>,
        request: GlobalRemoteCatalogCacheRefreshRequest,
    )

Purpose: Queues and starts the worker that refreshes the global remote plugin catalog cache. It keeps at most one worker active at a time.

Data flow: It stores the latest catalog refresh request, checks whether a worker is already in flight, and spawns the async refresh loop only when needed.

Call relations: maybe_start_global_remote_catalog_cache_refresh calls this when list or startup work wants the global catalog warmed.

Call graph: called by 1 (maybe_start_global_remote_catalog_cache_refresh); 2 external calls (clone, spawn).

fn schedule_non_curated_plugin_cache_refresh(
        self: &Arc<Self>,
        roots: &[AbsolutePathBuf],
        mode: NonCuratedCacheRefreshMode,
    )

Purpose: Queues and starts a background thread to refresh non-curated plugin caches. It deduplicates repeated requests so listing does not start endless identical refreshes.

Data flow: It sorts and deduplicates roots, ignores empty input, builds a request, skips it if an equivalent refresh is already pending or just completed, stores it, and starts a named thread to run the refresh loop.

Call relations: maybe_start_non_curated_plugin_cache_refresh calls this for normal refreshes, while cache upgrade code can request forced reinstall mode.

Call graph: called by 1 (maybe_start_non_curated_plugin_cache_refresh); 7 external calls (clone, new, dedup, is_empty, sort_unstable, to_vec, warn!).

fn start_curated_repo_sync(self: &Arc<Self>)

Purpose: Starts a one-at-a-time background sync of the OpenAI-curated plugin repository. This keeps the built-in curated catalog fresh.

Data flow: It uses a global atomic flag to avoid duplicate syncs. The thread syncs the curated repo, finds configured curated plugin IDs, refreshes their cache, clears manager caches if needed, and resets the flag on failures.

Call relations: Startup tasks call this when plugins are enabled.

Call graph: called by 1 (maybe_start_plugin_startup_tasks_for_config); 4 external calls (clone, clone, new, warn!).

async fn run_remote_installed_plugins_cache_refresh_loop(self: Arc<Self>)

Purpose: Worker loop that performs queued remote-installed plugin cache refreshes. It processes the latest queued request until no request remains.

Data flow: Each pass takes one queued request, fetches remote installed plugins, writes or clears the cache depending on success or auth errors, calls the effective-plugin callback when needed, logs other errors, and then loops for another queued request.

Call relations: schedule_remote_installed_plugins_cache_refresh spawns this loop in the background.

Call graph: calls 3 internal fn (clear_remote_installed_plugins_cache, write_remote_installed_plugins_cache, fetch_remote_installed_plugins); 2 external calls (matches!, warn!).

async fn run_global_remote_catalog_cache_refresh_loop(self: Arc<Self>)

Purpose: Worker loop that refreshes the global remote plugin catalog cache. It drains queued catalog refresh requests one by one.

Data flow: Each pass takes a queued request, calls the remote catalog fetch-and-cache helper, ignores expected auth-mode errors, logs unexpected errors, and exits when no request remains.

Call relations: schedule_global_remote_catalog_cache_refresh spawns this loop in the background.

Call graph: calls 1 internal fn (fetch_and_cache_global_remote_plugin_catalog); 2 external calls (as_path, warn!).

fn run_non_curated_plugin_cache_refresh_loop(self: Arc<Self>)

Purpose: Thread worker that refreshes non-curated plugin caches. It keeps running while newer refresh requests are queued.

Data flow: It reads the current request, refreshes either only changed versions or force-reinstalls depending on mode, clears manager caches when cache content changes or an error occurs, records successful refreshes, and exits when the processed request is still the latest request.

Call relations: schedule_non_curated_plugin_cache_refresh starts this thread for marketplace cache maintenance.

Call graph: calls 3 internal fn (refresh_non_curated_plugin_cache, refresh_non_curated_plugin_cache_force_reinstall, clear_cache); 2 external calls (as_path, warn!).

fn configured_plugin_states(
        &self,
        config: &PluginsConfigInput,
    ) -> (HashSet<String>, HashSet<String>)

Purpose: Separates configured plugins into installed and enabled sets. This gives listing and detail code quick answers about local state.

Data flow: It reads configured plugins from the config stack. For each plugin key, it parses the ID and asks the store whether it is installed; it also collects keys whose config says enabled. It returns both sets.

Call relations: Marketplace listing and single-plugin reading call this before adding state to marketplace entries.

Call graph: calls 1 internal fn (configured_plugins_from_stack); called by 2 (list_marketplaces_for_config, read_plugin_for_config).

fn marketplace_roots(
        &self,
        config: &PluginsConfigInput,
        additional_roots: &[AbsolutePathBuf],
        include_openai_curated: bool,
    ) -> Vec<AbsolutePathBuf>

Purpose: Builds the complete list of marketplace roots to search. It combines caller-provided roots, configured marketplace roots, and optionally the built-in curated marketplace.

Data flow: It starts with additional roots, adds roots from the config layer stack, chooses the curated marketplace path based on auth mode and whether curated sources should be included, converts it to an absolute path when present, then sorts and deduplicates the result.

Call relations: Marketplace listing and discovery call this before asking the marketplace module to read marketplace contents.

Call graph: calls 4 internal fn (installed_marketplace_roots_from_layer_stack, curated_plugins_api_marketplace_path, curated_plugins_repo_path, try_from); called by 2 (discover_marketplaces_for_config, list_marketplaces_for_config); 3 external calls (as_path, matches!, to_vec).

fn remote_plugin_install_required_description(source: &MarketplacePluginSource) -> String

Purpose: Creates a user-facing explanation for why an uninstalled cross-repository plugin has limited details. It includes enough source information to identify where the plugin would come from.

Data flow: It receives a marketplace plugin source. For Git sources it formats the URL plus optional path, ref, and SHA; for local sources it formats the path. It returns a sentence saying installation is required for more detail.

Call relations: read_plugin_detail_for_marketplace_plugin uses this when a Git plugin is listed but not installed locally.

Call graph: called by 1 (read_plugin_detail_for_marketplace_plugin); 2 external calls (format!, vec!).

fn join(source: tokio::task::JoinError) -> Self

Purpose: Wraps an async task join failure as a plugin install error. A join failure means the spawned install task itself failed to complete normally.

Data flow: It receives a JoinError from Tokio and returns the PluginInstallError::Join variant containing that error.

Call relations: The shared install routine uses this when waiting for blocking installation work to finish.

Call graph: 1 external calls (Join).

fn is_invalid_request(&self) -> bool

Purpose: Tells callers whether an install error was caused by a bad user request rather than an internal or service failure. This helps choose the right response status or message.

Data flow: It inspects the error variant and returns true for marketplace not found, plugin not found, unavailable plugin, invalid plugin, and invalid store input cases; otherwise it returns false.

Call relations: Install command or API layers can call this after install_plugin or install_plugin_with_remote_sync fails.

Call graph: 1 external calls (matches!).

fn join(source: tokio::task::JoinError) -> Self

Purpose: Wraps an async task join failure as a plugin uninstall error. This keeps task failures in the same error type as other uninstall problems.

Data flow: It receives a Tokio JoinError and returns the PluginUninstallError::Join variant.

Call relations: The shared uninstall routine uses this when waiting for blocking store removal work.

Call graph: 1 external calls (Join).

fn is_invalid_request(&self) -> bool

Purpose: Tells callers whether an uninstall error came from an invalid plugin ID supplied by the user.

Data flow: It checks the error variant and returns true only for invalid plugin ID errors.

Call relations: Uninstall command or API layers can call this after uninstall fails to decide whether to report a bad request.

Call graph: 1 external calls (matches!).

fn configured_plugins_from_stack(
    config_layer_stack: &ConfigLayerStack,
) -> HashMap<String, PluginConfig>

Purpose: Reads plugin configuration from the effective user config. Plugin entries are intentionally taken from user configuration only.

Data flow: It asks the config layer stack for the effective user config. If none exists, it returns an empty map; otherwise it parses the plugin entries from that TOML value.

Call relations: Plugin loading and configured-state calculation call this to know which plugins the user has configured.

Call graph: calls 2 internal fn (effective_user_config, configured_plugins_from_user_config_value); called by 2 (configured_plugin_states, plugins_for_config_with_force_reload); 1 external calls (new).

fn configured_plugins_from_user_config_value(
    user_config: &toml::Value,
) -> HashMap<String, PluginConfig>

Purpose: Parses the plugins section from a user config value. If the section is missing or invalid, it safely returns no configured plugins.

Data flow: It looks for a plugins key in the TOML value. If present, it tries to convert it into a map of plugin configs; on parse failure it logs a warning and returns an empty map.

Call relations: configured_plugins_from_stack calls this after it has found the effective user config value.

Call graph: called by 1 (configured_plugins_from_stack); 3 external calls (new, get, warn!).

fn record_added_marketplace_entry(
    codex_home: &Path,
    marketplace_name: &str,
    install_metadata: &MarketplaceInstallMetadata,
) -> Result<(), MarketplaceAddError>

Purpose: This function writes a newly added marketplace into the user's config.toml. It records where the marketplace came from, when it was added or updated, and any Git-specific details needed to find the same source again.

Data flow: It receives the Codex home folder, the marketplace name, and the install metadata. It turns the metadata into config fields, asks for the current UTC timestamp, builds a MarketplaceConfigUpdate, and passes that to the config-writing helper. If the write succeeds, nothing is returned except success; if it fails, the error is wrapped in a marketplace-add error with a useful message.

Call relations: During the add flow, add_marketplace_sync_with_cloner calls this after it has enough source information to record the marketplace. The function relies on the metadata helper methods for source, type, ref, and sparse paths, calls utc_timestamp_now for the timestamp, then hands the final update to record_user_marketplace. A test also calls it to set up a local marketplace entry before checking that the lookup path works.

Call graph: calls 5 internal fn (config_source, config_source_type, ref_name, sparse_paths, utc_timestamp_now); called by 2 (add_marketplace_sync_with_cloner, installed_marketplace_root_for_source_uses_local_source_root); 1 external calls (record_user_marketplace).

fn installed_marketplace_root_for_source(
    codex_home: &Path,
    install_root: &Path,
    install_metadata: &MarketplaceInstallMetadata,
) -> Result<Option<PathBuf>, MarketplaceAddError>

Purpose: This function checks whether a marketplace from the same source is already recorded in the user's config, and if so returns its real root folder. It helps the add command reuse or recognize an existing installation instead of blindly adding another copy.

Data flow: It receives the Codex home folder, the marketplace install root, and the source metadata to match. It reads config.toml, treats a missing file as "no match," parses the TOML text, and looks through the marketplaces table. For each saved marketplace, it compares the saved source fields against the requested source, resolves the saved entry to a folder path, validates that the folder is a real marketplace, and returns the first valid match. If nothing matches, it returns None; unreadable or unparseable config becomes an error.

Call relations: add_marketplace_sync_with_cloner calls this while deciding whether the requested marketplace source is already installed. Inside, the function asks MarketplaceInstallMetadata::matches_config to compare config entries, then passes likely matches to resolve_configured_marketplace_root and validate_marketplace_root. The tests call it both to confirm read errors are reported and to confirm a recorded local marketplace can be found.

Call graph: calls 3 internal fn (resolve_configured_marketplace_root, validate_marketplace_root, matches_config); called by 3 (add_marketplace_sync_with_cloner, installed_marketplace_root_for_source_propagates_config_read_errors, installed_marketplace_root_for_source_uses_local_source_root); 5 external calls (join, Internal, format!, read_to_string, from_str).

fn find_marketplace_root_by_name(
    codex_home: &Path,
    install_root: &Path,
    marketplace_name: &str,
) -> Result<Option<PathBuf>, MarketplaceAddError>

Purpose: This function looks up a marketplace by its configured name and returns the folder where it lives, but only if that folder still looks valid. It is useful when the add flow knows the name and wants to locate an existing entry directly.

Data flow: It receives the Codex home folder, the marketplace install root, and the marketplace name. It reads and parses config.toml, finds the named entry under the marketplaces table, resolves that entry into a path, and validates the path. It returns Some(path) for a valid marketplace, None if the config or entry is missing or the resolved folder is invalid, and an error if the config cannot be read or parsed.

Call relations: add_marketplace_sync_with_cloner calls this as part of the marketplace add decision-making path. This function does not compare full source metadata; instead it goes straight to the named config entry, then uses resolve_configured_marketplace_root and validate_marketplace_root to turn that entry into a trustworthy folder path.

Call graph: calls 2 internal fn (resolve_configured_marketplace_root, validate_marketplace_root); called by 1 (add_marketplace_sync_with_cloner); 5 external calls (join, Internal, format!, read_to_string, from_str).

fn from_source(source: &MarketplaceSource, sparse_paths: &[String]) -> Self

Purpose: This constructor turns the user's requested marketplace source into the internal receipt format used by this file. It preserves the details that matter later: Git URL, optional Git ref, sparse paths, or a local folder path.

Data flow: It receives a MarketplaceSource and a list of sparse paths. If the source is Git, it copies the URL, optional ref name, and sparse paths into the metadata. If the source is local, it converts the local path into a string. It returns a MarketplaceInstallMetadata value ready to be recorded or compared.

Call relations: add_marketplace_sync_with_cloner calls this near the start of metadata work, so later functions can use one common shape for both Git and local sources. The tests also call it to build metadata for their lookup scenarios.

Call graph: called by 3 (add_marketplace_sync_with_cloner, installed_marketplace_root_for_source_propagates_config_read_errors, installed_marketplace_root_for_source_uses_local_source_root).

fn config_source_type(&self) -> &'static str

Purpose: This helper says which kind of source the metadata represents: git or local. That short label is exactly what gets written into and compared against config.toml.

Data flow: It reads the metadata's stored source variant. For a Git source it returns the string git; for a local folder it returns local. It does not change anything.

Call relations: record_added_marketplace_entry uses this when writing a config update. MarketplaceInstallMetadata::matches_config uses it later to check whether a saved config entry has the same source kind.

Call graph: called by 2 (matches_config, record_added_marketplace_entry).

fn config_source(&self) -> String

Purpose: This helper returns the main source value that should appear in config.toml. For Git this is the repository URL; for a local marketplace this is the folder path string.

Data flow: It reads the metadata's stored source. It clones and returns the Git URL or local path as a String. The metadata itself is left unchanged.

Call relations: record_added_marketplace_entry uses this when building the config update. MarketplaceInstallMetadata::matches_config uses it to compare the requested source with the source saved in config.toml.

Call graph: called by 2 (matches_config, record_added_marketplace_entry).

fn ref_name(&self) -> Option<&str>

Purpose: This helper returns the Git ref, such as a branch, tag, or commit name, when the marketplace came from Git. Local marketplaces do not have a Git ref, so they return no value.

Data flow: It reads the metadata. For Git metadata, it returns the optional ref name as a borrowed string if one was supplied. For local metadata, it returns None. Nothing is modified.

Call relations: record_added_marketplace_entry uses this to write the optional ref field. MarketplaceInstallMetadata::matches_config uses it to make sure a saved Git marketplace matches the same ref, not just the same repository URL.

Call graph: called by 2 (matches_config, record_added_marketplace_entry).

fn sparse_paths(&self) -> &[String]

Purpose: This helper returns the sparse paths for a Git marketplace. Sparse paths are a list of subfolders to use from a larger repository; local marketplaces do not use them.

Data flow: It reads the metadata. For Git metadata, it returns the stored list of sparse path strings. For local metadata, it returns an empty list. It does not copy or change the stored data.

Call relations: record_added_marketplace_entry uses this when saving the marketplace config. MarketplaceInstallMetadata::matches_config uses it to confirm that a saved Git entry used the same sparse checkout choices.

Call graph: called by 2 (matches_config, record_added_marketplace_entry).

fn matches_config(&self, marketplace: &toml::Value) -> bool

Purpose: This function decides whether one marketplace entry from config.toml describes the same source as this metadata. It is the equality check that lets the add flow recognize an already-recorded marketplace.

Data flow: It receives a TOML value for one marketplace entry. It reads source_type, source, ref, and sparse_paths from that entry, reads the same values from the metadata, and compares them all. It returns true only when every relevant field matches; otherwise it returns false.

Call relations: installed_marketplace_root_for_source calls this while scanning all configured marketplaces. This function gathers expected values through config_source_type, config_source, ref_name, and sparse_paths, and it delegates sparse path extraction from TOML to config_sparse_paths.

Call graph: calls 5 internal fn (config_source, config_source_type, ref_name, sparse_paths, config_sparse_paths); called by 1 (installed_marketplace_root_for_source); 1 external calls (get).

fn config_sparse_paths(marketplace: &toml::Value) -> Vec<String>

Purpose: This helper pulls the sparse_paths list out of a marketplace's TOML config entry. It gives the comparison code a simple list of strings to work with.

Data flow: It receives a TOML marketplace value. It looks for a sparse_paths array, keeps only array items that are strings, converts them into owned String values, and returns the list. If the field is missing or not an array, it returns an empty list.

Call relations: MarketplaceInstallMetadata::matches_config calls this when comparing a saved config entry with the requested install metadata. Its small job keeps the TOML parsing detail out of the higher-level match logic.

Call graph: called by 1 (matches_config); 1 external calls (get).

fn utc_timestamp_now() -> Result<String, MarketplaceAddError>

Purpose: This function creates the current UTC timestamp string used in the marketplace config entry. It makes sure recorded marketplace updates have a consistent time format.

Data flow: It asks the operating system for the current time, measures how many seconds have passed since the Unix epoch, which is midnight UTC on 1970-01-01, and formats that count as a UTC date-time string. If the system clock is somehow before the Unix epoch, it returns an internal error.

Call relations: record_added_marketplace_entry calls this just before writing the config update. utc_timestamp_now hands the numeric seconds to format_utc_timestamp, which does the calendar formatting.

Call graph: calls 1 internal fn (format_utc_timestamp); called by 1 (record_added_marketplace_entry); 1 external calls (now).

fn format_utc_timestamp(seconds_since_epoch: i64) -> String

Purpose: This function turns a number of seconds since the Unix epoch into a readable UTC timestamp. It exists so config entries can use a standard date-time string instead of a raw number.

Data flow: It receives a signed count of seconds since 1970-01-01T00:00:00Z. It splits that into whole days and seconds within the day, converts the day count into year, month, and day, calculates hour, minute, and second, and returns a string like 2026-04-10T00:00:00Z.

Call relations: utc_timestamp_now calls this after getting the current time from the system. The timestamp formatting test also relies on it directly to check known dates. It delegates the calendar date calculation to civil_from_days.

Call graph: calls 1 internal fn (civil_from_days); called by 1 (utc_timestamp_now); 1 external calls (format!).

fn civil_from_days(days_since_epoch: i64) -> (i64, i64, i64)

Purpose: This function converts a day count into a calendar date: year, month, and day. It is the calendar math behind the timestamp formatter.

Data flow: It receives the number of days since the Unix epoch. It applies a standard civil-calendar calculation that accounts for leap years and 400-year calendar cycles, then returns the matching year, month, and day as numbers.

Call relations: format_utc_timestamp calls this when it has already reduced a timestamp to a number of whole days. This helper does not know about hours, minutes, config files, or marketplaces; it only supplies the date part.

Call graph: called by 1 (format_utc_timestamp).

fn utc_timestamp_formats_unix_epoch_as_rfc3339_utc()

Purpose: This test checks that timestamp formatting produces the expected UTC strings for known second counts. It protects the config timestamp format from accidental changes.

Data flow: It feeds format_utc_timestamp two fixed inputs: zero seconds since the Unix epoch and another known timestamp. It compares the returned strings with the expected RFC 3339-style UTC strings. If either output changes, the test fails.

Call relations: The test directly exercises format_utc_timestamp. It does not run during normal marketplace adding; it runs in the test suite to catch mistakes in the date formatting logic.

Call graph: 1 external calls (assert_eq!).

fn installed_marketplace_root_for_source_propagates_config_read_errors()

Purpose: This test confirms that a config.toml path that cannot be read is reported as an error, not silently treated as missing. That matters because hiding a broken config could make the add flow behave unpredictably.

Data flow: It creates a temporary Codex home folder, then creates a directory where config.toml should be, which makes reading it as a file fail. It builds Git install metadata and calls installed_marketplace_root_for_source. The expected result is an error message that includes the failed config path.

Call relations: The test builds metadata through MarketplaceInstallMetadata::from_source and then calls installed_marketplace_root_for_source. It verifies the error path used when the add flow cannot read the user's config file.

Call graph: calls 2 internal fn (from_source, installed_marketplace_root_for_source); 3 external calls (new, assert!, create_dir).

fn installed_marketplace_root_for_source_uses_local_source_root()

Purpose: This test checks that a local marketplace recorded in config resolves back to its original local source folder. It protects the behavior where local marketplaces are used in place rather than treated like copied installs.

Data flow: It creates a temporary Codex home, builds a fake local marketplace folder with the expected marketplace.json file, creates local install metadata, and records it in config.toml. It then asks installed_marketplace_root_for_source to find that source and expects the original local folder path to come back.

Call relations: The test calls MarketplaceInstallMetadata::from_source, record_added_marketplace_entry, and installed_marketplace_root_for_source in the same order the real add flow would use them. It confirms that the write-and-read path works for local sources.

Call graph: calls 3 internal fn (from_source, installed_marketplace_root_for_source, record_added_marketplace_entry); 4 external calls (new, assert_eq!, create_dir_all, write).

fn parse_marketplace_source(
    source: &str,
    explicit_ref: Option<String>,
) -> Result<MarketplaceSource, MarketplaceAddError>

Purpose: Turns the user’s source string into a MarketplaceSource, either Git or local. It also gives clear errors for empty text, unsupported formats, local files, or using a Git-only reference with a local path.

Data flow: It receives the raw source text and an optional explicit reference, such as a branch or tag. It trims the text, splits off any inline reference, decides whether the base looks like a local path, a Git URL, an SSH Git URL, or GitHub owner/repo shorthand, then returns a structured source value or an error message.

Call relations: This is the front door used by the marketplace add flow before any cloning or local reading happens. It relies on small helper checks for URL shape, path shape, GitHub shorthand, URL cleanup, reference splitting, and local path resolution; the tests call it with many examples to lock down those rules.

Call graph: calls 7 internal fn (is_git_url, is_ssh_git_url, looks_like_github_shorthand, looks_like_local_path, normalize_git_url, resolve_local_source_path, split_source_ref); called by 6 (add_marketplace_sync_with_cloner, file_url_source_is_rejected, github_shorthand_and_git_url_normalize_to_same_source, local_file_source_is_rejected, local_path_source_parses, non_git_sources_reject_ref_override); 2 external calls (InvalidRequest, format!).

fn stage_marketplace_source(
    source: &MarketplaceSource,
    sparse_paths: &[String],
    staged_root: &Path,
    clone_source: F,
) -> Result<(), MarketplaceAddError>

Purpose: Prepares a Git marketplace source in a staging directory by calling the supplied clone operation. It refuses sparse checkout requests for non-Git sources because sparse checkout is a Git feature.

Data flow: It receives a parsed source, a list of sparse paths, a destination folder, and a cloning function supplied by the caller. If the source is Git, it passes the URL, optional reference, sparse path list, and destination to that clone function; if the options do not make sense, it returns an error instead.

Call relations: After parse_marketplace_source has decided what kind of source the user gave, the marketplace add flow calls this when it needs a staged copy. The actual Git work is handed off through the clone_source callback, which keeps this function focused on policy and routing.

Call graph: called by 2 (add_marketplace_sync_with_cloner, non_git_sources_reject_sparse_checkout); 3 external calls (InvalidRequest, matches!, unreachable!).

fn validate_marketplace_source_root(root: &Path) -> Result<String, MarketplaceAddError>

Purpose: Checks that a folder really contains a valid marketplace and that its marketplace name is safe to use. This protects later plugin code from malformed or unsafe names.

Data flow: It receives a filesystem path. It asks the marketplace validator to read and verify the marketplace root, then checks the resulting marketplace name as a valid plugin name segment; it returns the marketplace name or turns validation failures into user-facing request errors.

Call relations: The marketplace add flow calls this after it has a local or staged marketplace root. It hands the heavy checking to validate_marketplace_root and validate_plugin_segment, then gives the add flow the trusted marketplace name.

Call graph: calls 1 internal fn (validate_marketplace_root); called by 1 (add_marketplace_sync_with_cloner); 1 external calls (validate_plugin_segment).

fn split_source_ref(source: &str) -> (String, Option<String>)

Purpose: Separates a source address from an optional branch, tag, or other Git reference written at the end. It understands #ref generally and @ref for non-URL shorthand forms.

Data flow: It receives one source string. It looks from the right for #, or for @ when the text is not a URL and not an SSH Git address, then returns the base source plus an optional cleaned reference.

Call relations: parse_marketplace_source calls this before deciding what kind of source it is looking at. It uses is_ssh_git_url to avoid mistaking SSH addresses for shorthand references and uses non_empty_ref so blank suffixes are ignored.

Call graph: calls 2 internal fn (is_ssh_git_url, non_empty_ref); called by 1 (parse_marketplace_source).

fn non_empty_ref(ref_name: &str) -> Option<String>

Purpose: Turns a reference suffix into None if it is blank, or a cleaned string if it contains real text. This prevents empty references from being treated as meaningful.

Data flow: It receives the reference part after a separator like # or @. It trims surrounding whitespace and returns either no value for an empty result or the trimmed reference string.

Call relations: split_source_ref calls this whenever it has found a possible reference suffix. Its result flows back into parse_marketplace_source, where an explicit --ref can override it.

Call graph: called by 1 (split_source_ref).

fn normalize_git_url(url: &str) -> String

Purpose: Cleans up Git URLs so the same GitHub repository is represented consistently. In particular, GitHub HTTPS URLs are made to end in .git.

Data flow: It receives a Git URL string. It removes trailing slashes, adds .git for https://github.com/... URLs that do not already have it, and returns the normalized URL text.

Call relations: parse_marketplace_source calls this after it has recognized a full Git URL. This helps GitHub shorthand and equivalent full GitHub URLs compare as the same source.

Call graph: called by 1 (parse_marketplace_source); 1 external calls (format!).

fn looks_like_local_path(source: &str) -> bool

Purpose: Decides whether the user’s source text looks like a path on the local machine rather than a Git repository address. This includes Unix-style paths, Windows-style paths, and home-directory paths.

Data flow: It receives the base source string. It checks for absolute paths, Windows absolute paths, relative prefixes like ./ and ../, ~/, and the special current or parent directory names; it returns true or false.

Call relations: parse_marketplace_source uses this early so local folders are not mistaken for GitHub shorthand. It delegates the Windows-specific absolute path check to looks_like_windows_absolute_path.

Call graph: calls 1 internal fn (looks_like_windows_absolute_path); called by 1 (parse_marketplace_source); 1 external calls (new).

fn looks_like_windows_absolute_path(source: &str) -> bool

Purpose: Recognizes Windows absolute paths even when the code is running on a non-Windows system. This matters because users or tests may pass paths like C:\Users\... or network shares.

Data flow: It receives a source string. It checks for a drive letter followed by : and a slash or backslash, or for a UNC network path beginning with double backslashes, then returns true or false.

Call relations: looks_like_local_path calls this as one part of its broader local-path decision. The tests specifically check that these Windows forms are recognized consistently.

Call graph: called by 1 (looks_like_local_path); 1 external calls (matches!).

fn resolve_local_source_path(source: &str) -> Result<PathBuf, MarketplaceAddError>

Purpose: Turns a local marketplace path into a real absolute filesystem path. This gives later code a stable location to read from.

Data flow: It receives a local path string. It expands ~/ if possible, joins relative paths to the current working directory, asks the operating system to canonicalize the path, and returns the resolved PathBuf or an error if it cannot be resolved.

Call relations: parse_marketplace_source calls this after deciding the source is local. It uses expand_tilde_path for home-directory shorthand and reads the current directory when needed.

Call graph: calls 1 internal fn (expand_tilde_path); called by 1 (parse_marketplace_source); 1 external calls (current_dir).

fn expand_tilde_path(source: &str) -> PathBuf

Purpose: Expands paths that start with ~/ into the user’s home directory. This lets users write familiar shell-style paths.

Data flow: It receives a path string. If the string starts with ~/ and a home directory can be found from environment variables, it replaces ~ with that home folder; otherwise it returns the original path as a path object.

Call relations: resolve_local_source_path calls this before making the path absolute and canonical. It reads HOME or USERPROFILE, which are common environment variables for the user’s home directory.

Call graph: called by 1 (resolve_local_source_path); 2 external calls (from, var_os).

fn is_ssh_git_url(source: &str) -> bool

Purpose: Checks whether a source string looks like an SSH Git address. SSH is a way to access Git repositories using secure login keys.

Data flow: It receives a source string and returns true if it starts with ssh:// or looks like the common git@host:repo form.

Call relations: parse_marketplace_source uses this to recognize Git sources. split_source_ref also uses it so the @ in addresses like git@github.com:owner/repo.git is not wrongly treated as a branch separator.

Call graph: called by 2 (parse_marketplace_source, split_source_ref).

fn is_git_url(source: &str) -> bool

Purpose: Checks whether a source string is an HTTP or HTTPS Git URL. This catches common repository addresses such as GitHub, GitLab, or other hosted Git servers.

Data flow: It receives a source string and returns true if it begins with http:// or https://.

Call relations: parse_marketplace_source calls this after local-path detection and SSH detection. If it returns true, the parser treats the source as Git and normalizes the URL where needed.

Call graph: called by 1 (parse_marketplace_source).

fn looks_like_github_shorthand(source: &str) -> bool

Purpose: Recognizes the short GitHub form owner/repo. This lets users avoid typing the full GitHub URL.

Data flow: It receives a source string, splits it on /, and checks that there are exactly two valid parts: owner and repository. It returns true only when both parts have allowed characters and there is no extra path segment.

Call relations: parse_marketplace_source calls this after ruling out local paths and full Git URLs. When it matches, the parser builds a full https://github.com/owner/repo.git URL.

Call graph: called by 1 (parse_marketplace_source).

fn is_github_shorthand_segment(segment: &str) -> bool

Purpose: Checks one part of a GitHub shorthand source, such as the owner name or repository name. It allows common GitHub name characters and rejects empty segments.

Data flow: It receives a single text segment. It returns true when every character is an ASCII letter, number, dash, underscore, or dot, and the segment is not empty.

Call relations: This helper supports the GitHub shorthand check by acting like a small quality gate for each segment. That keeps owner/repo recognition strict enough to avoid accepting random malformed text.

fn display(&self) -> String

Purpose: Creates a user-readable version of a parsed marketplace source. It is useful for messages, logs, or summaries where the source needs to be shown back to a person.

Data flow: It reads the MarketplaceSource value. For Git, it returns the URL and appends #ref when there is a reference; for local sources, it returns the path as display text.

Call relations: This method sits on the MarketplaceSource type itself, so any later marketplace-add code can ask a parsed source how it should be shown. It uses formatting only for the Git-with-reference case.

Call graph: 1 external calls (format!).

fn github_shorthand_parses_ref_suffix()

Purpose: Checks that GitHub shorthand with an @main suffix becomes a Git source with main as the reference. This protects the user-friendly shorthand syntax.

Data flow: The test gives the parser owner/repo@main and expects a normalized GitHub URL plus the main reference. If the actual parsed value differs, the assertion fails.

Call relations: The test runner calls this during automated testing. It supports confidence in the parsing behavior that parse_marketplace_source provides to the marketplace add flow.

Call graph: 1 external calls (assert_eq!).

fn git_url_parses_fragment_ref()

Purpose: Checks that a full Git URL with #v1 keeps the URL and extracts v1 as the reference. This covers the fragment-style reference syntax.

Data flow: The test feeds in https://example.com/team/repo.git#v1 and expects the base URL without the fragment plus a reference value of v1. The assertion compares expected and actual structured values.

Call relations: The test runner calls this as part of the parser test suite. It verifies the behavior that is used before Git cloning begins.

Call graph: 1 external calls (assert_eq!).

fn explicit_ref_overrides_source_ref()

Purpose: Checks that an explicit reference option wins over a reference written inside the source string. This makes command-line behavior predictable.

Data flow: The test uses a source containing @main and also supplies release as the explicit reference. It expects the parsed result to use release, not main.

Call relations: The test runner calls this to protect the precedence rule used by parse_marketplace_source. That rule matters when the marketplace add command receives both forms.

Call graph: 1 external calls (assert_eq!).

fn github_shorthand_and_git_url_normalize_to_same_source()

Purpose: Checks that owner/repo and the full GitHub .git URL produce the same parsed source. This keeps different ways of saying the same GitHub repository consistent.

Data flow: The test parses shorthand and full URL inputs, compares them to each other, and compares the result to the expected normalized Git source.

Call relations: The test runner calls this, and the test directly exercises parse_marketplace_source. It protects the normalization path that uses GitHub shorthand expansion and URL cleanup.

Call graph: calls 1 internal fn (parse_marketplace_source); 1 external calls (assert_eq!).

fn github_url_with_trailing_slash_normalizes_without_extra_path_segment()

Purpose: Checks that a GitHub URL ending in / is cleaned into a normal .git URL, not treated as a different repository path. This avoids subtle duplicate-source problems.

Data flow: The test gives a GitHub URL with a trailing slash and expects the returned Git source URL to end with .git and no extra slash segment.

Call relations: The test runner calls this as part of URL normalization coverage. It protects the behavior supplied by normalize_git_url through the parser.

Call graph: 1 external calls (assert_eq!).

fn non_github_https_source_parses_as_git_url()

Purpose: Checks that HTTPS Git URLs from hosts other than GitHub are accepted. The parser should not be GitHub-only.

Data flow: The test supplies a GitLab-style HTTPS URL and expects it to come back as a Git source without adding .git or changing the host.

Call relations: The test runner calls this to confirm parse_marketplace_source accepts generic HTTP-based Git sources. It guards the path recognized by is_git_url.

Call graph: 1 external calls (assert_eq!).

fn file_url_source_is_rejected()

Purpose: Checks that file:// URLs are rejected instead of being treated as valid marketplace sources. This keeps the accepted source formats narrow and intentional.

Data flow: The test passes a file:///tmp/... source, expects an error, and checks that the error says the source format is invalid.

Call relations: The test runner calls this, and it directly calls parse_marketplace_source. It confirms that unsupported URL schemes do not slip through as Git or local paths.

Call graph: calls 1 internal fn (parse_marketplace_source); 1 external calls (assert!).

fn local_path_source_parses()

Purpose: Checks that . is accepted as a local marketplace source and resolved to an absolute path. This supports adding a marketplace from the current directory.

Data flow: The test parses . and then inspects the result. It expects a local source variant whose path is absolute; otherwise it fails.

Call relations: The test runner calls this, and it directly exercises parse_marketplace_source. It protects the local-path branch that later marketplace add code can use without staging a clone.

Call graph: calls 1 internal fn (parse_marketplace_source); 2 external calls (assert!, panic!).

fn windows_absolute_paths_look_like_local_paths_on_every_host()

Purpose: Checks that Windows absolute paths are recognized as local paths even when tests run on another operating system. This keeps parsing behavior portable.

Data flow: The test sends several Windows path examples to the local-path detector and checks true or false results, including rejecting C:relative\path because it is not absolute.

Call relations: The test runner calls this to protect the helper behavior behind local source detection. It is especially important because path syntax differs across operating systems.

Call graph: 1 external calls (assert!).

fn local_file_source_is_rejected()

Purpose: Checks that a local source must be a directory, not a single file. A marketplace root needs directory contents, so accepting a file would fail later in a less clear way.

Data flow: The test creates a temporary directory, writes a file inside it, passes that file path as the source, and expects an error saying a directory is required.

Call relations: The test runner calls this, and it directly calls parse_marketplace_source. It confirms the parser catches local file mistakes before the add flow tries to read a marketplace root.

Call graph: calls 1 internal fn (parse_marketplace_source); 3 external calls (new, assert!, write).

fn non_git_sources_reject_ref_override()

Purpose: Checks that the explicit --ref option is rejected for local sources. A branch or tag only makes sense for Git.

Data flow: The test passes a local-looking source plus an explicit reference. It expects an error message explaining that --ref is only supported for Git marketplace sources.

Call relations: The test runner calls this, and it directly exercises parse_marketplace_source. It protects the rule that keeps Git-only options away from local folder sources.

Call graph: calls 1 internal fn (parse_marketplace_source); 1 external calls (assert!).

fn non_git_sources_reject_sparse_checkout()

Purpose: Checks that sparse checkout paths are rejected for local sources. Sparse checkout means cloning only selected paths from Git, so it does not apply to an already-local folder.

Data flow: The test builds a local MarketplaceSource, supplies a sparse path list and a dummy clone function, then expects stage_marketplace_source to return a Git-only option error.

Call relations: The test runner calls this, and it directly calls stage_marketplace_source. It verifies that staging enforces the same Git-only boundary as parsing does for references.

Call graph: calls 1 internal fn (stage_marketplace_source); 3 external calls (new, assert!, current_dir).

fn ssh_url_parses_as_git_url()

Purpose: Checks that SSH Git URLs are accepted and can include a #main reference suffix. This supports users who clone private or authenticated repositories over SSH.

Data flow: The test provides an ssh://git@github.com/...#main source and expects a Git source with the SSH URL as the base and main as the reference.

Call relations: The test runner calls this to cover the SSH path through source parsing. It protects the behavior supplied by is_ssh_git_url and reference splitting.

Call graph: 1 external calls (assert_eq!).

async fn add_marketplace(
    codex_home: PathBuf,
    request: MarketplaceAddRequest,
) -> Result<MarketplaceAddOutcome, MarketplaceAddError>

Purpose: This is the public asynchronous entry point for adding a marketplace. It lets callers start the add operation without blocking the async runtime, which is the part of the program that keeps other tasks moving.

Data flow: It receives the Codex home folder and a marketplace add request. It moves the slower file and Git work onto a blocking worker thread, runs the synchronous add logic there, and returns either a successful add outcome or a clear error.

Call relations: Higher-level flows such as plugin import and the add command call this function when a user wants to add a marketplace. It hands the real work to the synchronous add path inside a worker task so those callers do not freeze the rest of the program.

Call graph: called by 2 (import_plugins, run_add); 1 external calls (spawn_blocking).

fn is_local_marketplace_source(
    source: &str,
    explicit_ref: Option<String>,
) -> Result<bool, MarketplaceAddError>

Purpose: This helper answers a simple question: does this source string point to a local marketplace folder? Callers can use it when they need to choose different behavior for local paths versus Git sources.

Data flow: It receives the source text and an optional reference name. It parses those into a marketplace source description, checks whether that description is the local-folder kind, and returns true or false, or an error if the source text is invalid.

Call relations: This function relies on the same source parser used by the add flow, so the answer matches what adding the marketplace would believe. It does not install anything; it only classifies the source.

Call graph: 1 external calls (matches!).

fn add_marketplace_sync(
    codex_home: &Path,
    request: MarketplaceAddRequest,
) -> Result<MarketplaceAddOutcome, MarketplaceAddError>

Purpose: This is the normal synchronous version of the marketplace add operation. It exists so the main async wrapper and other plain blocking code can share one implementation.

Data flow: It receives the Codex home folder and the add request. It calls the shared add routine using the real Git cloning function, then passes back the resulting outcome or error.

Call relations: The async add function reaches the core logic through this function. This wrapper chooses the production cloner, while tests can call the deeper helper with a fake cloner.

Call graph: calls 1 internal fn (add_marketplace_sync_with_cloner).

fn add_marketplace_sync_with_cloner(
    codex_home: &Path,
    request: MarketplaceAddRequest,
    clone_source: F,
) -> Result<MarketplaceAddOutcome, MarketplaceAddError>

Purpose: This is the main installation recipe. It parses the requested source, prevents unsafe or conflicting installs, stages remote sources, validates the marketplace, writes the user's config, and reports what was added.

Data flow: It starts with a Codex home path, a request, and a function that can copy or clone a source into a destination. It parses the source, creates the install area if needed, builds metadata for the config, checks whether the same source is already recorded, and then branches. For a local source, it validates the existing folder and records it. For a Git source, it creates a temporary staging folder, places the source there, validates it, moves it into the install folder, and records it. The result is a marketplace name, a display form of the source, an absolute installed path, and a flag saying whether it was already added.

Call relations: This function is called by the normal synchronous wrapper and directly by tests. It coordinates helpers from the install, metadata, and source modules: source helpers parse and stage the marketplace, install helpers choose safe folders and move files, and metadata helpers find or write the marketplace entry in config.

Call graph: calls 13 internal fn (marketplace_install_root, ensure_marketplace_destination_is_inside_install_root, marketplace_staging_root, replace_marketplace_root, safe_marketplace_dir_name, from_source, find_marketplace_root_by_name, installed_marketplace_root_for_source, record_added_marketplace_entry, parse_marketplace_source (+3 more)); called by 5 (add_marketplace_sync, add_marketplace_sync_installs_local_directory_source_and_updates_config, add_marketplace_sync_installs_marketplace_and_updates_config, add_marketplace_sync_rejects_sparse_checkout_for_local_directory_source, add_marketplace_sync_treats_existing_local_directory_source_as_already_added); 8 external calls (new, Internal, InvalidRequest, is_openai_curated_marketplace_name, format!, create_dir_all, rename, matches!).

fn add_marketplace_sync_installs_marketplace_and_updates_config() -> Result<()>

Purpose: This test proves that adding a Git-style marketplace copies the marketplace into the install area and writes the expected config entry. It uses a fake cloner so the test does not need the network.

Data flow: It creates temporary Codex and source folders, writes a small sample marketplace into the source folder, then calls the add routine with a pretend Git URL. The fake cloner copies the sample files into the staging destination. The test then checks that the result names the marketplace correctly, marks it as newly added, leaves marketplace files in the installed root, and writes Git source details to the config file.

Call relations: This test calls the shared add routine directly with a test cloner. It also uses the helper that writes a sample marketplace and the recursive copy helper to mimic what a real Git clone would provide.

Call graph: calls 1 internal fn (add_marketplace_sync_with_cloner); 6 external calls (new, new, assert!, assert_eq!, write_marketplace_source, read_to_string).

fn add_marketplace_sync_installs_local_directory_source_and_updates_config() -> Result<()>

Purpose: This test proves that a local marketplace folder is recorded directly instead of copied into Codex's install folder. That distinction matters because local sources should stay where the user put them.

Data flow: It creates temporary folders, writes a sample marketplace in the local source folder, and calls the add routine with that folder path. The fake Git cloner would panic if used, so the test confirms the local path avoids cloning. It checks that the outcome points to the canonical local folder, no install-folder copy was made, and the config records the source type as local.

Call relations: This test exercises the local-source branch of the shared add routine. It depends on the sample marketplace writer and checks the config file produced by the metadata recording code.

Call graph: calls 2 internal fn (add_marketplace_sync_with_cloner, from_absolute_path); 7 external calls (new, new, assert!, assert_eq!, write_marketplace_source, read_to_string, from_str).

fn add_marketplace_sync_rejects_sparse_checkout_for_local_directory_source() -> Result<()>

Purpose: This test confirms that sparse checkout is rejected for local folders. Sparse checkout means selecting only parts of a Git repository, so it would not make sense for a plain local directory in this flow.

Data flow: It prepares a valid local marketplace folder, then calls the add routine with that folder plus a sparse path. The function returns an error before writing config or calling the fake cloner. The test checks the exact error message and confirms no config file was created.

Call relations: This test targets the early validation inside the shared add routine. It verifies that bad input is stopped before any install or config-writing helpers are reached.

Call graph: calls 1 internal fn (add_marketplace_sync_with_cloner); 5 external calls (new, assert!, assert_eq!, write_marketplace_source, vec!).

fn add_marketplace_sync_treats_existing_local_directory_source_as_already_added() -> Result<()>

Purpose: This test proves that adding the same local marketplace twice is safe and idempotent. Idempotent means doing the same action again does not create a duplicate or change the result unexpectedly.

Data flow: It creates a sample local marketplace and sends the same add request twice. The first call records it as newly added. The second call recognizes the same source from existing metadata, validates the folder again, and returns an outcome marked as already added with the same installed root.

Call relations: This test exercises the existing-source lookup in the shared add routine. It shows how metadata lookup prevents duplicate marketplace entries for the same local folder.

Call graph: calls 1 internal fn (add_marketplace_sync_with_cloner); 5 external calls (new, new, assert!, assert_eq!, write_marketplace_source).

fn write_marketplace_source(source: &Path, marker: &str) -> std::io::Result<()>

Purpose: This test helper creates a tiny but valid marketplace folder on disk. Tests use it as a realistic sample source without needing a real external marketplace.

Data flow: It receives a destination folder and a marker string. It creates the marketplace metadata directories, writes a marketplace JSON file that names a sample plugin, writes that plugin's own metadata file, and writes a marker text file. It returns success or an input/output error from the filesystem.

Call relations: The marketplace add tests call this helper before running the add routine. It supplies the source files that validation and installation code expect to find.

Call graph: 3 external calls (join, create_dir_all, write).

fn copy_dir_all(source: &Path, destination: &Path) -> std::io::Result<()>

Purpose: This test helper recursively copies one directory tree into another. It stands in for a Git clone during tests, so the add logic can be tested without contacting Git.

Data flow: It receives a source folder and a destination folder. It creates the destination, walks through every entry in the source, recursively copies subfolders, and copies files directly. It returns success or a filesystem error.

Call relations: The Git-style install test uses this helper inside its fake cloner. That lets the shared add routine behave as if a remote repository was cloned into the staging folder.

Call graph: 5 external calls (join, copy_dir_all, copy, create_dir_all, read_dir).

fn git_remote_revision(
    source: &str,
    ref_name: Option<&str>,
    timeout: Duration,
) -> Result<String, String>

Purpose: Finds the exact Git commit ID for a marketplace source and optional branch, tag, or commit name. This matters because upgrades should record the precise revision used, not just a moving name like main.

Data flow: It receives a repository location, an optional reference name, and a timeout. If the reference is already a full 40-character commit ID, it returns it immediately. Otherwise it runs git ls-remote, checks that Git succeeded, reads the first line of output, extracts the commit ID before the tab character, and returns that ID or a readable error.

Call relations: The marketplace upgrade flow calls this when it needs to know what remote revision it is about to use. It relies on is_full_git_sha for the quick no-network case, git_command to build a safe Git process, run_git_command_with_timeout to run it without hanging, and ensure_git_success to turn Git failures into clear errors.

Call graph: calls 4 internal fn (ensure_git_success, git_command, is_full_git_sha, run_git_command_with_timeout); called by 1 (upgrade_configured_git_marketplace); 2 external calls (from_utf8_lossy, format!).

fn clone_git_source(
    source: &str,
    ref_name: Option<&str>,
    sparse_paths: &[String],
    destination: &Path,
    timeout: Duration,
) -> Result<String, String>

Purpose: Clones a marketplace Git source into a local destination folder. It can copy the whole repository or only selected paths, which saves time and space when the marketplace data lives in part of a larger repository.

Data flow: It receives a repository location, an optional reference name, a list of sparse paths, a destination path, and a timeout. It first prepares the destination path in a Git-friendly form. If no sparse paths are requested, it runs git clone, optionally checks out the requested reference, then asks what commit was checked out. If sparse paths are requested, it clones without checking out files, configures sparse checkout for those paths, checks out the requested reference or HEAD, and returns the final commit ID.

Call relations: The marketplace upgrade flow calls this after deciding which Git source to fetch. It hands each Git operation to run_git_command_with_timeout, checks the result with ensure_git_success, uses git_command for consistent process setup, uses git_path_arg for platform-safe paths, and finishes by calling git_worktree_revision so the caller knows exactly what was cloned.

Call graph: calls 5 internal fn (ensure_git_success, git_command, git_path_arg, git_worktree_revision, run_git_command_with_timeout); called by 1 (upgrade_configured_git_marketplace).

fn git_worktree_revision(destination: &Path, timeout: Duration) -> Result<String, String>

Purpose: Reads the exact commit ID currently checked out in a cloned repository. This gives the upgrade code a reliable record of what ended up on disk.

Data flow: It receives a repository folder and a timeout. It runs git rev-parse HEAD inside that folder, verifies that Git succeeded, trims the command output, and returns the commit ID. If Git returns no commit text, it reports that as an error.

Call relations: This is called by clone_git_source after cloning and checkout are complete. It uses the same Git process builder, timeout runner, and success checker as the rest of the file so revision lookup behaves consistently with clone and remote lookup.

Call graph: calls 3 internal fn (ensure_git_success, git_command, run_git_command_with_timeout); called by 1 (clone_git_source); 1 external calls (from_utf8_lossy).

fn is_full_git_sha(value: &str) -> bool

Purpose: Checks whether a string already looks like a complete Git commit ID. A full Git commit ID is 40 hexadecimal characters, meaning digits 0-9 and letters a-f/A-F.

Data flow: It receives a text value. It checks the length and verifies every character is a hexadecimal character. It returns true if both checks pass, otherwise false.

Call relations: git_remote_revision uses this as a shortcut. When the caller already supplied an exact commit ID, the upgrade does not need to contact the remote repository just to resolve it.

Call graph: called by 1 (git_remote_revision).

fn git_command() -> Command

Purpose: Creates a new command configured to run the system git program in a non-interactive, stable way. Non-interactive means Git should fail instead of asking the user questions at a terminal.

Data flow: It creates a Command for git, then sets two environment variables: one disables optional Git locks, and the other disables terminal prompts. It returns the prepared command so callers can add subcommands and arguments.

Call relations: All Git actions in this file start here, including remote lookup, clone, checkout, sparse checkout, and revision lookup. A test also calls it to confirm it uses normal path lookup for git and sets the intended environment variables.

Call graph: called by 4 (clone_git_source, git_remote_revision, git_worktree_revision, git_command_uses_path_lookup_with_stable_noninteractive_env); 1 external calls (new).

fn git_path_arg(path: &Path) -> PathBuf

Purpose: Converts a local filesystem path into a form that can safely be passed to Git. This is mainly important on Windows, where some paths can have a special long-path prefix that Git may not accept.

Data flow: It receives a path. On Windows, it turns the path into text, tries to remove the special verbatim prefix, and returns the cleaned path if possible; otherwise it returns the original path. On non-Windows systems, it simply returns a copy of the original path.

Call relations: clone_git_source uses this before passing the destination folder to Git. On Windows it delegates the actual prefix removal to strip_windows_verbatim_path_prefix.

Call graph: calls 1 internal fn (strip_windows_verbatim_path_prefix); called by 1 (clone_git_source); 2 external calls (to_path_buf, to_string_lossy).

fn strip_windows_verbatim_path_prefix(path: &str) -> Option<String>

Purpose: Removes Windows' special \\?\ path prefix from a path string when present. This helps convert long-path forms into the more ordinary forms Git expects.

Data flow: It receives a path as text. If the path begins with \\?\, it removes that prefix. If the remaining path begins with UNC\, it turns it into a normal network path beginning with \\; otherwise it returns the stripped local path. If there is no verbatim prefix, it returns nothing.

Call relations: git_path_arg uses this during Windows path preparation. The tests call it directly to prove disk paths, network paths, and ordinary paths are treated correctly.

Call graph: called by 1 (git_path_arg).

fn run_git_command_with_timeout(
    command: &mut Command,
    context: &str,
    timeout: Duration,
) -> Result<Output, String>

Purpose: Runs a prepared Git command while enforcing a time limit. This prevents marketplace upgrades from hanging forever because of a slow network, a stuck Git process, or an unexpected prompt.

Data flow: It receives a command, a short human-readable context string, and a timeout. It starts the process with no standard input, captures standard output and standard error, then polls until the process exits. If it finishes in time, it returns the captured output. If the timeout is reached, it kills the process, collects any error text, and returns a timeout message.

Call relations: The higher-level Git operations call this whenever they need to run Git. It does not decide whether Git succeeded; after it returns output, callers pass that output to ensure_git_success for status checking.

Call graph: called by 3 (clone_git_source, git_remote_revision, git_worktree_revision); 8 external calls (from_millis, null, piped, from_utf8_lossy, stdin, format!, sleep, now).

fn ensure_git_success(output: &Output, context: &str) -> Result<(), String>

Purpose: Turns Git's exit status into a clear success or error result. Git may produce output even when it fails, so this function is the common checkpoint after each command.

Data flow: It receives captured process output and a context label. If the exit status means success, it returns success. If not, it reads Git's standard error text, trims it, and returns an error message that includes the status and, when available, Git's own explanation.

Call relations: git_remote_revision, clone_git_source, and git_worktree_revision call this after running Git commands. This keeps failure reporting consistent across remote lookup, clone, checkout, sparse checkout, and revision lookup.

Call graph: called by 3 (clone_git_source, git_remote_revision, git_worktree_revision); 2 external calls (from_utf8_lossy, format!).

fn full_git_sha_ref_is_already_a_remote_revision()

Purpose: Checks that full commit IDs are recognized correctly and shorter or named references are not mistaken for exact commits.

Data flow: It feeds is_full_git_sha one valid 40-character hexadecimal string, a branch-like name, and a short hexadecimal string. It expects only the full-length commit ID to be accepted.

Call relations: This protects the shortcut used by git_remote_revision. If this behavior changed, the upgrader might either make unnecessary remote Git calls or wrongly trust an imprecise reference.

Call graph: 1 external calls (assert!).

fn git_command_uses_path_lookup_with_stable_noninteractive_env()

Purpose: Verifies that Git commands are built in the expected safe way. In particular, Git should be found through the normal system path and should not try to prompt a user interactively.

Data flow: It creates a command with git_command, then inspects its program name and environment settings. It expects the program to be git, the non-interactive environment variables to be set, and PATH not to be overridden.

Call relations: This test directly exercises git_command. It uses tests::command_env to inspect environment variables stored on the command object.

Call graph: calls 1 internal fn (git_command); 1 external calls (assert_eq!).

fn strips_windows_verbatim_disk_prefix_for_git()

Purpose: Confirms that a Windows local disk path with the \\?\ prefix is converted into a normal-looking disk path.

Data flow: It passes a verbatim Windows path like \\?\C:\... into strip_windows_verbatim_path_prefix. It expects the returned text to drop the special prefix and keep the rest of the path.

Call relations: This test protects the Windows path cleanup used indirectly by clone_git_source through git_path_arg.

Call graph: 1 external calls (assert_eq!).

fn strips_windows_verbatim_unc_prefix_for_git()

Purpose: Confirms that a Windows network path with the verbatim UNC form is converted into a normal network path.

Data flow: It passes a path beginning with \\?\UNC\server\share... into strip_windows_verbatim_path_prefix. It expects the result to begin with \\server\share..., which is the usual Windows network path form.

Call relations: This test protects the network-path branch of strip_windows_verbatim_path_prefix, which supports git_path_arg on Windows.

Call graph: 1 external calls (assert_eq!).

fn leaves_non_verbatim_path_without_rewrite()

Purpose: Checks that ordinary Windows paths are not changed by the verbatim-prefix stripper.

Data flow: It passes a normal path such as C:\Users\alice into strip_windows_verbatim_path_prefix. It expects no rewritten path to be returned.

Call relations: This test helps ensure git_path_arg only rewrites the special paths that need rewriting and leaves normal paths alone.

Call graph: 1 external calls (assert_eq!).

fn command_env(
        command: &'a std::process::Command,
        name: &str,
    ) -> Option<Option<&'a OsStr>>

Purpose: Looks up one environment variable on a prepared command during tests. It is a small test helper, not part of the production Git workflow.

Data flow: It receives a command object and an environment variable name. It scans the command's configured environment entries and returns the value if that variable was explicitly set, or no result if it was not set.

Call relations: tests::git_command_uses_path_lookup_with_stable_noninteractive_env uses this helper to check the environment variables added by git_command.

Call graph: 1 external calls (get_envs).

fn all_succeeded(&self) -> bool

Purpose: This small helper answers whether an upgrade run finished without any marketplace errors. It is useful for callers that only need a simple yes-or-no result.

Data flow: It reads the outcome's list of errors. If that list is empty, it returns true; if any error was recorded, it returns false. It does not change the outcome.

Call relations: After an upgrade run has produced a ConfiguredMarketplaceUpgradeOutcome, other code can call this method to decide whether the whole batch should be treated as successful.

fn configured_git_marketplace_names(config_layer_stack: &ConfigLayerStack) -> Vec<String>

Purpose: This returns the names of all marketplaces in the user's config that are backed by Git. It is used when another part of the system needs to know which configured marketplaces are eligible for Git-based upgrading.

Data flow: It receives the layered configuration, asks configured_git_marketplaces to extract the Git marketplace entries, keeps only their names, sorts those names, and returns the sorted list.

Call relations: upgrade_configured_marketplaces_for_config calls this when it needs the set of configured Git marketplace names. This function relies on configured_git_marketplaces for the real config-reading and filtering work, then turns the result into a simple name list.

Call graph: calls 1 internal fn (configured_git_marketplaces); called by 1 (upgrade_configured_marketplaces_for_config).

fn upgrade_configured_git_marketplaces(
    codex_home: &Path,
    config_layer_stack: &ConfigLayerStack,
    marketplace_name: Option<&str>,
) -> ConfiguredMarketplaceUpgradeOutcome

Purpose: This is the batch upgrader for Git-backed marketplaces. It chooses the marketplaces to update, runs the per-marketplace upgrade process, and collects successes and errors into one report.

Data flow: It takes the Codex home directory, the current configuration stack, and optionally one marketplace name to target. It reads all configured Git marketplaces, filters to the requested name if one was provided, computes the install folder, then tries to upgrade each marketplace. It returns an outcome containing the selected marketplace names, the installed roots that changed, and any error messages.

Call relations: upgrade_configured_marketplaces_for_config calls this as part of the larger marketplace upgrade flow. This function calls configured_git_marketplaces to discover work, marketplace_install_root to choose where installs live, and upgrade_configured_git_marketplace for the detailed one-at-a-time update. It is the loop that turns individual upgrade attempts into a batch result.

Call graph: calls 3 internal fn (configured_git_marketplaces, marketplace_install_root, upgrade_configured_git_marketplace); called by 1 (upgrade_configured_marketplaces_for_config); 2 external calls (new, default).

fn marketplace_install_root(codex_home: &Path) -> PathBuf

Purpose: This builds the directory path where auto-installed marketplaces are stored under the Codex home directory. Keeping this path in one function prevents different parts of the upgrader from inventing different install locations.

Data flow: It receives the Codex home path and appends the fixed subdirectory .tmp/marketplaces. It returns that combined path and does not touch the filesystem.

Call relations: upgrade_configured_git_marketplaces calls this before processing marketplaces, then passes the resulting install root down into each per-marketplace upgrade.

Call graph: called by 1 (upgrade_configured_git_marketplaces); 1 external calls (join).

fn configured_git_marketplaces(
    config_layer_stack: &ConfigLayerStack,
) -> Vec<ConfiguredGitMarketplace>

Purpose: This reads the user's effective config and turns valid Git marketplace entries into internal upgrade records. It is the filter that decides which configured marketplaces this file is responsible for.

Data flow: It receives the layered config stack. It looks for the effective user config, then for a marketplaces table inside it. If that table cannot be understood, it logs a warning and returns no marketplaces. Otherwise it converts entries into ConfiguredGitMarketplace values, keeps only Git ones, sorts them by name, and returns them.

Call relations: configured_git_marketplace_names calls this when it needs just names, and upgrade_configured_git_marketplaces calls it when it needs full upgrade details. It is the shared discovery step for this file.

Call graph: calls 1 internal fn (effective_user_config); called by 2 (configured_git_marketplace_names, upgrade_configured_git_marketplaces); 2 external calls (new, warn!).

fn configured_git_marketplace_from_config(
    name: String,
    marketplace: MarketplaceConfig,
) -> Option<ConfiguredGitMarketplace>

Purpose: This converts one marketplace config entry into the internal shape used by the upgrader, but only if that entry is a Git marketplace. It also rejects Git entries that do not say where to fetch from.

Data flow: It receives a marketplace name and its parsed config. It checks the source type; if it is not Git, it returns nothing. If it is Git but has no source URL or path, it logs a warning and returns nothing. Otherwise it returns a ConfiguredGitMarketplace containing the name, source, optional branch or tag name, optional sparse paths, and last known revision.

Call relations: read_configured_git_marketplace uses this after rereading the user's config from disk, so the same Git-entry rules are applied during the final safety check. The wider discovery path also depends on this conversion behavior when building the list of upgradeable marketplaces.

Call graph: called by 1 (read_configured_git_marketplace); 1 external calls (warn!).

fn upgrade_configured_git_marketplace(
    codex_home: &Path,
    install_root: &Path,
    marketplace: &ConfiguredGitMarketplace,
) -> Result<Option<AbsolutePathBuf>, String>

Purpose: This upgrades one configured Git marketplace safely. It checks whether an update is needed, downloads into a temporary staging area, validates the result, records metadata, and then activates the new copy.

Data flow: It receives the Codex home directory, the install root, and one marketplace record. First it validates the marketplace name so it is safe to use as a path segment. It asks the remote Git source for the current revision. If the installed marketplace already has that revision and matching metadata, it returns no upgraded path. Otherwise it creates a staging directory, clones the Git source into it, validates that the staged files form a marketplace with the expected name, writes metadata, updates the user's config with the new revision and timestamp, activates the staged copy at the final destination, and returns that destination as an absolute path. If any step fails, it returns a human-readable error string.

Call relations: upgrade_configured_git_marketplaces calls this once per selected marketplace. This function coordinates several specialist helpers: Git helpers find and clone the remote revision, marketplace validation checks the downloaded files, activation helpers swap the staged directory into place, and config helpers record the new revision. Just before recording, it uses ensure_configured_git_marketplace_unchanged so an in-progress upgrade cannot overwrite a config entry that the user changed meanwhile.

Call graph: calls 8 internal fn (find_marketplace_manifest_path, validate_marketplace_root, activate_marketplace_root, installed_marketplace_metadata_matches, write_installed_marketplace_metadata, clone_git_source, git_remote_revision, try_from); called by 1 (upgrade_configured_git_marketplaces); 6 external calls (join, now, validate_plugin_segment, format!, create_dir_all, new).

fn ensure_configured_git_marketplace_unchanged(
    codex_home: &Path,
    expected: &ConfiguredGitMarketplace,
) -> Result<(), String>

Purpose: This is a race-prevention check. It confirms that the marketplace config still matches what the upgrader started with before the upgrader writes the new revision back to the user's config.

Data flow: It receives the Codex home path and the marketplace settings that were used to start the upgrade. It rereads the current config entry from disk. If the current entry still exactly matches, it returns success. If the entry changed, was removed, or is no longer a Git marketplace, it returns an error message.

Call relations: upgrade_configured_git_marketplace invokes this during activation, right before recording the upgraded marketplace in config.toml. It delegates the actual reread-and-parse work to read_configured_git_marketplace, then decides whether it is safe to continue.

Call graph: calls 1 internal fn (read_configured_git_marketplace); 1 external calls (format!).

fn read_configured_git_marketplace(
    codex_home: &Path,
    marketplace_name: &str,
) -> Result<Option<ConfiguredGitMarketplace>, String>

Purpose: This reads one marketplace entry directly from the user's config.toml file and returns it only if it is still a valid Git marketplace. It is used for the final safety check during an upgrade.

Data flow: It receives the Codex home path and a marketplace name. It builds the config.toml path, reads the file, parses it as TOML, looks for the marketplaces table, and extracts the named entry. If the file or entry is missing, it returns no marketplace. If parsing fails or the marketplaces table is invalid, it returns an error. If the entry exists, it passes it through configured_git_marketplace_from_config and returns the result.

Call relations: ensure_configured_git_marketplace_unchanged calls this when an upgrade is about to be committed. This function supplies the current on-disk truth, while configured_git_marketplace_from_config applies the same Git-marketplace rules used elsewhere in the upgrader.

Call graph: calls 1 internal fn (configured_git_marketplace_from_config); called by 1 (ensure_configured_git_marketplace_unchanged); 4 external calls (join, format!, read_to_string, from_str).

async fn remove_marketplace(
    codex_home: PathBuf,
    request: MarketplaceRemoveRequest,
) -> Result<MarketplaceRemoveOutcome, MarketplaceRemoveError>

Purpose: This is the async entry point for removing a marketplace. It lets the rest of the program ask for removal without blocking the async task runner while files and config are changed on disk.

Data flow: It receives the Codex home directory and a request containing the marketplace name. It moves that work into a blocking background task, calls the synchronous removal routine there, and then returns either the removal result or an internal error if the background task itself failed.

Call relations: The command-level removal flow calls this function when the user asks to remove a marketplace. This function does not do the detailed removal itself; it hands the work to remove_marketplace_sync so the slower filesystem operations happen off the main async path.

Call graph: called by 1 (run_remove); 1 external calls (spawn_blocking).

fn remove_marketplace_sync(
    codex_home: &Path,
    request: MarketplaceRemoveRequest,
) -> Result<MarketplaceRemoveOutcome, MarketplaceRemoveError>

Purpose: This function performs the real marketplace removal. It checks the requested name, removes the marketplace from the user's config, deletes the installed marketplace files, and reports what was actually removed.

Data flow: It starts with a Codex home path and a marketplace name. It validates the name, computes the expected installed location, asks the config layer to remove the saved marketplace entry, rejects exact-name mismatches, then asks remove_marketplace_root to delete the installed root. It returns a MarketplaceRemoveOutcome containing the marketplace name and the removed path, or an error explaining why removal could not safely happen.

Call relations: The async wrapper remove_marketplace calls this function in normal use. The tests call it directly so they can check the exact filesystem and config effects. During its work it relies on marketplace_install_root to find the install area, remove_user_marketplace_config to update config.toml, validate_plugin_segment to reject unsafe names, and remove_marketplace_root to delete files.

Call graph: calls 2 internal fn (marketplace_install_root, remove_marketplace_root); called by 6 (remove_marketplace_sync_keeps_installed_root_when_config_removal_fails, remove_marketplace_sync_rejects_case_mismatched_configured_name, remove_marketplace_sync_rejects_unknown_marketplace, remove_marketplace_sync_removes_config_and_installed_root, remove_marketplace_sync_removes_file_installed_root, remove_marketplace_sync_removes_inline_config_entry); 4 external calls (remove_user_marketplace_config, validate_plugin_segment, InvalidRequest, format!).

fn remove_marketplace_root(root: &Path) -> Result<Option<AbsolutePathBuf>, MarketplaceRemoveError>

Purpose: This helper deletes the installed marketplace path if it exists. It is careful to return the absolute path it removed, and it can clean up either a directory or an unexpected file.

Data flow: It receives a filesystem path. If nothing exists there, it returns None. If something does exist, it converts the path to an absolute path for reporting, inspects the filesystem entry, removes it as a whole directory when it is a directory or as a single file otherwise, and returns Some(path) after successful deletion.

Call relations: remove_marketplace_sync calls this after the config entry has been removed or confirmed. This helper is the file-deletion part of the larger removal process, keeping the lower-level disk details out of the main decision-making function.

Call graph: calls 1 internal fn (try_from); called by 1 (remove_marketplace_sync); 5 external calls (exists, to_path_buf, remove_dir_all, remove_file, symlink_metadata).

fn remove_marketplace_sync_removes_config_and_installed_root()

Purpose: This test proves the normal successful case: a configured and installed marketplace is fully removed. It checks that both the config entry and the installed directory disappear.

Data flow: It creates a temporary Codex home, records a marketplace named debug in the config, creates a matching installed directory with a sample marketplace file, then calls remove_marketplace_sync. Afterward it checks that the outcome names debug, reports the removed installed path, removes the config section, and deletes the installed directory.

Call relations: This test calls the same synchronous function used by the real removal path. It also uses the config-writing helper and marketplace_install_root to set up a realistic before-state, then verifies that remove_marketplace_sync coordinated config removal and filesystem cleanup correctly.

Call graph: calls 2 internal fn (marketplace_install_root, remove_marketplace_sync); 7 external calls (new, assert!, assert_eq!, record_user_marketplace, create_dir_all, read_to_string, write).

fn remove_marketplace_sync_rejects_unknown_marketplace()

Purpose: This test confirms that removing a marketplace that is neither configured nor installed is treated as a user error. That prevents a silent success when nothing was actually removed.

Data flow: It creates an empty temporary Codex home and asks remove_marketplace_sync to remove debug. Since there is no config entry and no installed root, the function returns an error, and the test checks that the message says the marketplace is not configured or installed.

Call relations: This test exercises the final safety check inside remove_marketplace_sync. It shows that the function only reports success when it made a real change to config, disk, or both.

Call graph: calls 1 internal fn (remove_marketplace_sync); 2 external calls (new, assert_eq!).

fn remove_marketplace_sync_rejects_case_mismatched_configured_name()

Purpose: This test checks that marketplace names must match the configured capitalization exactly. This avoids confusing or unsafe behavior across filesystems with different case rules.

Data flow: It creates a temporary Codex home, records a marketplace as debug, and creates its installed directory. It then tries to remove Debug with an uppercase D. The call returns an error, and the test verifies that the installed directory and config entry are still present.

Call relations: This test drives the case-mismatch branch in remove_marketplace_sync, which depends on the config removal helper reporting that a similarly named marketplace exists with different capitalization. It confirms that the removal flow stops before deleting installed files.

Call graph: calls 2 internal fn (marketplace_install_root, remove_marketplace_sync); 6 external calls (new, assert!, assert_eq!, record_user_marketplace, create_dir_all, read_to_string).

fn remove_marketplace_sync_keeps_installed_root_when_config_removal_fails()

Purpose: This test proves that file deletion does not happen if the config file cannot be safely edited. That matters because deleting installed files while leaving a broken config change half-done would make recovery harder.

Data flow: It writes an invalid config.toml file into a temporary Codex home, creates an installed marketplace directory, and calls remove_marketplace_sync. The function returns an error about failing to remove the config entry, and the test checks that the installed directory still exists.

Call relations: This test checks the ordering inside remove_marketplace_sync. Because config removal is attempted before remove_marketplace_root is called, a config parsing or editing failure stops the process before any installed files are removed.

Call graph: calls 2 internal fn (marketplace_install_root, remove_marketplace_sync); 4 external calls (new, assert!, create_dir_all, write).

fn remove_marketplace_sync_removes_file_installed_root()

Purpose: This test makes sure cleanup still works when the installed marketplace path is a file instead of a directory. That can happen after a corrupt or interrupted install, and the remover should still be able to clean it up.

Data flow: It creates a temporary Codex home, records a debug marketplace in config, then writes a plain file at the expected install path instead of creating a directory there. After calling remove_marketplace_sync, it checks that the outcome reports the removed path, the file is gone, and the config entry is gone.

Call relations: This test focuses on remove_marketplace_root as used by remove_marketplace_sync. It confirms that the helper chooses file deletion when the installed root is not a directory, while the overall removal flow still updates config correctly.

Call graph: calls 2 internal fn (marketplace_install_root, remove_marketplace_sync); 7 external calls (new, assert!, assert_eq!, record_user_marketplace, create_dir_all, read_to_string, write).

fn remove_marketplace_sync_removes_inline_config_entry()

Purpose: This test verifies that marketplace removal works even when the config stores the marketplace entry in an inline TOML table rather than a separate section. In plain terms, it checks that both supported config shapes can be cleaned up.

Data flow: It writes a config.toml containing an inline marketplace entry for debug, creates the installed root, and calls remove_marketplace_sync. It then checks that the returned outcome names debug, the installed root was removed, and the config file no longer contains the debug entry.

Call relations: This test relies on remove_marketplace_sync delegating config editing to remove_user_marketplace_config. It confirms that the main removal flow does not care about the exact text layout of the config file as long as the config layer can remove the marketplace entry.

Call graph: calls 2 internal fn (marketplace_install_root, remove_marketplace_sync); 6 external calls (new, assert!, assert_eq!, create_dir_all, read_to_string, write).

fn io(context: &'static str, source: io::Error) -> Self

Purpose: Builds a consistent error value for ordinary file-system failures. It lets the rest of the file attach a plain explanation, such as which file operation failed, to the original input/output error.

Data flow: It receives a short context message and an operating-system I/O error → wraps both into the file’s remote bundle install error type → returns that error for callers to pass upward.

Call relations: The install, extract, and JSON-writing paths use this helper whenever creating directories, reading files, writing files, or renaming folders fails, so all those failures look the same to higher-level code.

fn validate_remote_plugin_bundle(
    remote_plugin_id: &str,
    remote_marketplace_name: &str,
    plugin_name: &str,
    release_version: Option<&str>,
    bundle_download_url: Option<&str>,
    ap

Purpose: Checks the backend’s description of a remote plugin before any download begins. It makes sure the local plugin identity, release version, and bundle URL are all usable and safe.

Data flow: It receives the remote plugin id, marketplace name, plugin name, optional version, optional download URL, and optional app manifest → trims and validates the version, parses and checks the URL, and builds a PluginId → returns a ValidatedRemotePluginBundle or a specific reason why the bundle must be rejected.

Call relations: Remote install, sync, checkout, and tests call this as the first gate. It relies on the version validator and URL checks before handing a trusted bundle plan to the download and install functions.

Call graph: calls 4 internal fn (allow_test_loopback_http_bundle_downloads, is_allowed_bundle_download_url, validate_plugin_version_segment, new); called by 10 (remote_plugin_install_response, sync_remote_installed_plugin_bundles_once, checkout_remote_plugin_share, install_preserves_non_global_bundle_manifest_metadata, valid_remote_plugin_bundle, validate_remote_plugin_bundle_rejects_invalid_release_version, validate_remote_plugin_bundle_rejects_missing_download_url, validate_remote_plugin_bundle_rejects_missing_release_version, validate_remote_plugin_bundle_rejects_unsupported_download_url_scheme, validate_remote_plugin_bundle_uses_detail_name_for_local_plugin_id); 1 external calls (parse).

fn allow_test_loopback_http_bundle_downloads() -> bool

Purpose: Decides whether plain HTTP downloads are allowed for local test servers. In normal use it returns false, keeping downloads restricted to secure HTTPS.

Data flow: It reads a debug-only environment variable → accepts HTTP only when running a debug build and the variable is exactly set to 1 → returns a yes/no answer.

Call relations: The validation and download code call this before deciding whether an HTTP localhost URL is acceptable. It exists so tests can use local servers without weakening production behavior.

Call graph: called by 2 (download_remote_plugin_bundle_with_limit, validate_remote_plugin_bundle); 1 external calls (var).

fn is_allowed_bundle_download_url(url: &Url, allow_loopback_http: bool) -> bool

Purpose: Answers whether a bundle URL uses an acceptable scheme. HTTPS is always allowed; HTTP is only allowed for loopback addresses when the caller has explicitly allowed that test mode.

Data flow: It receives a parsed URL and a boolean saying whether local HTTP is allowed → checks the URL scheme and, for HTTP, whether the host is loopback → returns true for allowed URLs and false otherwise.

Call relations: Validation uses it before accepting a backend URL, and download uses it again after redirects. It delegates the localhost decision to is_loopback_url.

Call graph: calls 1 internal fn (is_loopback_url); called by 2 (download_remote_plugin_bundle_with_limit, validate_remote_plugin_bundle); 1 external calls (scheme).

fn is_loopback_url(url: &Url) -> bool

Purpose: Checks whether a URL points back to the same machine, such as localhost or 127.0.0.1. This is used only for test-only HTTP exceptions.

Data flow: It receives a parsed URL → looks at its host name or IP address → returns true for localhost, IPv4 loopback, or IPv6 loopback, and false for anything else.

Call relations: is_allowed_bundle_download_url calls this when deciding if an HTTP URL can be accepted in debug testing.

Call graph: called by 1 (is_allowed_bundle_download_url); 1 external calls (host).

async fn download_and_install_remote_plugin_bundle(
    codex_home: PathBuf,
    bundle: ValidatedRemotePluginBundle,
) -> Result<PluginInstallResult, RemotePluginBundleInstallError>

Purpose: Downloads a validated remote plugin bundle and installs it into the local plugin store. It is the main high-level path for turning a backend-approved bundle into an installed plugin.

Data flow: It receives the Codex home folder and a validated bundle plan → downloads the archive bytes within the configured size limit → moves the disk-heavy install work to a blocking worker task → returns the PluginInstallResult or a download/install error.

Call relations: Remote install and sync flows call this after validation. It hands downloading to download_remote_plugin_bundle_with_limit and installation to install_remote_plugin_bundle.

Call graph: calls 1 internal fn (download_remote_plugin_bundle_with_limit); called by 2 (remote_plugin_install_response, sync_remote_installed_plugin_bundles_once); 1 external calls (spawn_blocking).

async fn download_and_extract_remote_plugin_bundle_to_path(
    bundle: ValidatedRemotePluginBundle,
    destination: AbsolutePathBuf,
) -> Result<AbsolutePathBuf, RemotePluginBundleInstallError>

Purpose: Downloads a validated remote plugin bundle and checks it out into a chosen destination folder instead of installing it into the store. This supports flows that need a local copy of a shared remote plugin.

Data flow: It receives a validated bundle and an absolute destination path → downloads the archive bytes → runs extraction and destination activation in a blocking worker task → returns the destination path when successful.

Call relations: The remote plugin share checkout flow calls this. It shares the same download helper as installation, then hands off to extract_remote_plugin_bundle_to_path for the file work.

Call graph: calls 1 internal fn (download_remote_plugin_bundle_with_limit); called by 1 (checkout_remote_plugin_share); 1 external calls (spawn_blocking).

async fn download_remote_plugin_bundle_with_limit(
    bundle_download_url: &str,
    max_bytes: u64,
) -> Result<Vec<u8>, RemotePluginBundleInstallError>

Purpose: Fetches the bundle bytes from the network while enforcing security and size rules. It prevents unsafe redirects, failed HTTP responses, and oversized downloads from reaching the installer.

Data flow: It receives a bundle download URL and a maximum byte count → builds an HTTP client, sends a GET request with a timeout, verifies the final redirected URL, checks the status code, and reads the body with a limit → returns the downloaded bytes or a detailed download error.

Call relations: Both high-level download functions call this first. It uses the URL policy helpers and read_response_body_with_limit to keep the network step bounded and safe.

Call graph: calls 4 internal fn (allow_test_loopback_http_bundle_downloads, is_allowed_bundle_download_url, read_response_body_with_limit, build_reqwest_client); called by 2 (download_and_extract_remote_plugin_bundle_to_path, download_and_install_remote_plugin_bundle); 1 external calls (from_utf8_lossy).

async fn read_response_body_with_limit(
    mut response: Response,
    url: &str,
    max_bytes: u64,
) -> Result<Vec<u8>, RemotePluginBundleInstallError>

Purpose: Reads an HTTP response body without letting it grow past a chosen maximum. This protects memory even when the server does not honestly report its size up front.

Data flow: It receives a response, its URL for error messages, and a maximum byte count → checks the Content-Length header if present, then reads chunks one by one while counting bytes → returns the collected bytes or an error if reading fails or the limit is crossed.

Call relations: download_remote_plugin_bundle_with_limit calls this for both successful bundle bodies and small error bodies. It relies on enforce_download_size_limit before and during reading.

Call graph: calls 1 internal fn (enforce_download_size_limit); called by 1 (download_remote_plugin_bundle_with_limit); 3 external calls (new, chunk, content_length).

fn enforce_download_size_limit(
    url: &str,
    bytes: u64,
    max_bytes: u64,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Rejects a download when its known or accumulated size is too large. It is a small guardrail used while reading network data.

Data flow: It receives a URL, a byte count, and a maximum byte count → compares the count with the maximum → returns success if it fits or a DownloadTooLarge error if it does not.

Call relations: read_response_body_with_limit calls this repeatedly as data arrives. A unit test calls it directly to confirm oversized downloads are rejected.

Call graph: called by 2 (read_response_body_with_limit, download_size_limit_rejects_oversized_bundle).

fn install_remote_plugin_bundle(
    codex_home: PathBuf,
    bundle: ValidatedRemotePluginBundle,
    bundle_bytes: Vec<u8>,
) -> Result<PluginInstallResult, RemotePluginBundleInstallError>

Purpose: Unpacks a downloaded bundle in a temporary staging area, prepares its metadata, and installs it into PluginStore. It keeps half-extracted files away from the real plugin store until the bundle passes checks.

Data flow: It receives the Codex home folder, validated bundle information, and archive bytes → creates a staging directory, extracts the archive, finds the plugin root, optionally rewrites trusted metadata, converts the path to an absolute path, and asks PluginStore to install it with the backend version → returns the install result.

Call relations: download_and_install_remote_plugin_bundle runs this inside a blocking task. Tests also call it directly to check invalid archives, missing manifests, and metadata preservation.

Call graph: calls 5 internal fn (extract_plugin_bundle_tar_gz, find_extracted_plugin_root, prepare_extracted_remote_plugin_root, try_new, try_from); called by 3 (install_preserves_non_global_bundle_manifest_metadata, install_rejects_bundle_without_standard_plugin_root, install_rejects_invalid_tar_gz_bundle); 3 external calls (join, create_dir_all, new).

fn extract_remote_plugin_bundle_to_path(
    bundle: ValidatedRemotePluginBundle,
    bundle_bytes: Vec<u8>,
    destination: AbsolutePathBuf,
) -> Result<AbsolutePathBuf, RemotePluginBundleInstallErr

Purpose: Extracts a remote plugin bundle into a specific checkout directory. It verifies the destination is unused and that the bundle’s plugin.json name matches the expected plugin name.

Data flow: It receives validated bundle data, archive bytes, and an absolute destination → refuses an existing destination, creates the parent folder, extracts into a temporary sibling directory, verifies the plugin root and manifest name, then renames the temporary directory into place → returns the destination path.

Call relations: download_and_extract_remote_plugin_bundle_to_path uses this after downloading. It shares the same extraction and root-finding helpers used by the install path.

Call graph: calls 4 internal fn (load_plugin_manifest, extract_plugin_bundle_tar_gz, find_extracted_plugin_root, as_path); 5 external calls (InvalidBundle, format!, create_dir_all, rename, new).

fn prepare_extracted_remote_plugin_root(
    plugin_root: &Path,
    bundle: &ValidatedRemotePluginBundle,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Applies backend-provided metadata to an extracted plugin when the plugin comes from the global remote marketplace. Other marketplaces keep the metadata already inside the bundle.

Data flow: It receives the extracted plugin root and validated bundle details → checks the marketplace name → for global remote plugins, overwrites plugin.json version and optionally writes the app manifest → returns success or the first write/validation error.

Call relations: install_remote_plugin_bundle calls this after extraction and before installing into PluginStore. It hands the actual file updates to overwrite_plugin_manifest_version and overwrite_plugin_app_manifest.

Call graph: calls 2 internal fn (overwrite_plugin_app_manifest, overwrite_plugin_manifest_version); called by 1 (install_remote_plugin_bundle).

fn overwrite_plugin_manifest_version(
    plugin_root: &Path,
    plugin_version: &str,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Rewrites the plugin’s plugin.json file so its version matches the backend release version. This lets trusted backend release metadata be the source of truth for global remote plugins.

Data flow: It receives the plugin root and desired version → finds plugin.json, reads and parses it as JSON, confirms it is a JSON object, replaces or adds the version field, and writes it back neatly → returns success or an error.

Call relations: prepare_extracted_remote_plugin_root calls this for global remote plugins. It uses write_json_file for the final disk write.

Call graph: calls 1 internal fn (write_json_file); called by 1 (prepare_extracted_remote_plugin_root); 5 external calls (String, find_plugin_manifest_path, InvalidBundle, read_to_string, from_str).

fn overwrite_plugin_app_manifest(
    plugin_root: &Path,
    app_manifest: &JsonValue,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Writes the app manifest supplied by the backend into the extracted plugin. If the plugin manifest names a custom app manifest path, it uses that; otherwise it writes .app.json at the plugin root.

Data flow: It receives the plugin root and app manifest JSON → loads the plugin manifest to find the configured app path if one exists → writes the supplied JSON to that path → returns success or a file/JSON error.

Call relations: prepare_extracted_remote_plugin_root calls this only when the validated bundle includes an app manifest. It delegates writing to write_json_file.

Call graph: calls 2 internal fn (load_plugin_manifest, write_json_file); called by 1 (prepare_extracted_remote_plugin_root).

fn write_json_file(
    path: &Path,
    value: &JsonValue,
    context: &'static str,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Writes a JSON value to disk in a readable, pretty-printed format. It also creates the parent directory when needed.

Data flow: It receives a file path, a JSON value, and an error-context message → verifies the path has a parent, creates that parent directory, serializes the JSON with indentation plus a final newline, and writes the bytes → returns success or a clear error.

Call relations: The two metadata overwrite functions use this helper so manifest writes behave consistently.

Call graph: called by 2 (overwrite_plugin_app_manifest, overwrite_plugin_manifest_version); 4 external calls (parent, create_dir_all, write, to_vec_pretty).

fn extract_plugin_bundle_tar_gz(
    bytes: &[u8],
    destination: &Path,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Extracts a compressed tar.gz plugin archive using the standard remote bundle size limit. A tar.gz is a common archive format: tar groups files together, gzip compresses them.

Data flow: It receives archive bytes and a destination folder → calls the lower-level extractor with the configured maximum extracted size → returns success or an unpacking error translated into this file’s error type.

Call relations: Install, checkout, and extraction tests call this when they want normal production extraction rules. It is a convenience wrapper around extract_plugin_bundle_tar_gz_with_limits.

Call graph: calls 1 internal fn (extract_plugin_bundle_tar_gz_with_limits); called by 5 (extract_remote_plugin_bundle_to_path, install_remote_plugin_bundle, extraction_preserves_executable_permissions, extraction_rejects_tar_path_traversal, extraction_supports_gnu_long_name_entries).

fn extract_plugin_bundle_tar_gz_with_limits(
    bytes: &[u8],
    destination: &Path,
    max_total_bytes: u64,
) -> Result<(), RemotePluginBundleInstallError>

Purpose: Unpacks a plugin archive while enforcing a caller-chosen maximum total extracted size. It translates low-level archive errors into remote plugin install errors.

Data flow: It receives archive bytes, a destination folder, and a maximum extracted byte count → asks the shared archive unpacker to extract safely → maps oversized, I/O, and invalid-bundle failures into this file’s error enum → returns success or that mapped error.

Call relations: extract_plugin_bundle_tar_gz uses this with the production limit, while one test calls it directly with a tiny limit to confirm size protection works.

Call graph: calls 1 internal fn (unpack_plugin_bundle_tar_gz); called by 2 (extract_plugin_bundle_tar_gz, extraction_rejects_total_size_over_limit).

fn find_extracted_plugin_root(
    extraction_root: &Path,
) -> Result<PathBuf, RemotePluginBundleInstallError>

Purpose: Confirms that the extraction directory itself is a valid plugin root. It deliberately rejects bundles where the plugin root is nested inside another folder.

Data flow: It receives an extraction root path → checks whether that exact folder contains a discoverable plugin manifest → returns that path if valid, or an invalid-bundle error if not.

Call relations: Both install and checkout call this after extraction. Tests verify that a root-level manifest is accepted and a nested plugin folder is rejected.

Call graph: calls 1 internal fn (is_standard_plugin_root); called by 3 (extract_remote_plugin_bundle_to_path, install_remote_plugin_bundle, find_extracted_plugin_root_rejects_nested_plugin_root); 2 external calls (to_path_buf, InvalidBundle).

fn is_standard_plugin_root(path: &Path) -> bool

Purpose: Checks whether a folder looks like a standard plugin root by looking for its plugin manifest. This is the small yes/no check behind root validation.

Data flow: It receives a path → asks the shared manifest finder whether plugin.json exists in the expected place → returns true when found and false otherwise.

Call relations: find_extracted_plugin_root calls this to decide whether the extracted folder is acceptable.

Call graph: called by 1 (find_extracted_plugin_root); 1 external calls (find_plugin_manifest_path).

fn validate_remote_plugin_bundle_uses_detail_name_for_local_plugin_id()

Purpose: Tests that validation builds the local plugin identity from the detailed plugin name and marketplace, not from the opaque remote plugin id.

Data flow: It supplies valid remote bundle details → runs validate_remote_plugin_bundle → checks the resulting plugin name, marketplace, version, and URL.

Call relations: This test exercises the validation path directly and protects the contract expected by remote install callers.

Call graph: calls 1 internal fn (validate_remote_plugin_bundle); 1 external calls (assert_eq!).

fn validate_remote_plugin_bundle_rejects_missing_release_version()

Purpose: Tests that a bundle without a release version is rejected. Without this, installs could produce ambiguous or unsafe local version folders.

Data flow: It passes no release version into validation → receives an error → checks that the error is MissingReleaseVersion.

Call relations: This test calls validate_remote_plugin_bundle to cover one of the first backend-data checks.

Call graph: calls 1 internal fn (validate_remote_plugin_bundle); 1 external calls (assert!).

fn validate_remote_plugin_bundle_rejects_invalid_release_version()

Purpose: Tests that suspicious release version strings are rejected. The example uses path-like text that must not become part of an install path.

Data flow: It passes an invalid version string into validation → validation runs the version-segment checker → the test confirms the InvalidReleaseVersion error.

Call relations: This test guards the connection between validate_remote_plugin_bundle and the shared version validator.

Call graph: calls 1 internal fn (validate_remote_plugin_bundle); 1 external calls (assert!).

fn validate_remote_plugin_bundle_rejects_missing_download_url()

Purpose: Tests that a bundle cannot be validated without a download URL. The installer needs a real archive location before it can proceed.

Data flow: It passes a valid version but no URL → validation returns an error → the test checks for MissingBundleDownloadUrl.

Call relations: This test exercises the URL-required branch of validate_remote_plugin_bundle.

Call graph: calls 1 internal fn (validate_remote_plugin_bundle); 1 external calls (assert!).

fn validate_remote_plugin_bundle_rejects_unsupported_download_url_scheme()

Purpose: Tests that ordinary HTTP URLs are rejected before install. This protects users from insecure remote bundle downloads.

Data flow: It passes an http:// URL for a non-localhost host → validation checks the URL policy → the test confirms an UnsupportedBundleDownloadUrlScheme error.

Call relations: This test covers validate_remote_plugin_bundle together with the allowed-URL helper policy.

Call graph: calls 1 internal fn (validate_remote_plugin_bundle); 1 external calls (assert!).

fn download_size_limit_rejects_oversized_bundle()

Purpose: Tests the byte-count guard used during downloads. It proves that data larger than the configured maximum is refused.

Data flow: It calls enforce_download_size_limit with a current byte count greater than the maximum → receives an error → checks that the error is DownloadTooLarge.

Call relations: This test targets the small helper that read_response_body_with_limit depends on while reading network responses.

Call graph: calls 1 internal fn (enforce_download_size_limit); 1 external calls (assert!).

fn install_rejects_invalid_tar_gz_bundle()

Purpose: Tests that random bytes are not accepted as a plugin archive. This protects the installer from treating malformed input as a real plugin.

Data flow: It creates a temporary Codex home, builds a valid bundle plan, and passes non-archive bytes to install_remote_plugin_bundle → receives an error → checks that the message mentions reading the tar archive failed.

Call relations: This test calls the install path directly and relies on valid_remote_plugin_bundle for a reusable valid plan.

Call graph: calls 1 internal fn (install_remote_plugin_bundle); 3 external calls (assert!, valid_remote_plugin_bundle, tempdir).

fn install_rejects_bundle_without_standard_plugin_root()

Purpose: Tests that an archive without a root-level plugin.json is rejected. A plugin bundle must identify itself in the expected place.

Data flow: It builds a tar.gz containing only a README → asks install_remote_plugin_bundle to install it → receives an error → checks that the error mentions the missing standard plugin root.

Call relations: This test covers install_remote_plugin_bundle, archive creation helpers, extraction, and root validation together.

Call graph: calls 1 internal fn (install_remote_plugin_bundle); 4 external calls (assert!, tar_gz_bytes, valid_remote_plugin_bundle, tempdir).

fn install_preserves_non_global_bundle_manifest_metadata()

Purpose: Tests that bundles from non-global marketplaces keep their bundled plugin and app manifest contents. Only the install result version should use the backend release version.

Data flow: It validates a non-global bundle with backend metadata, builds an archive with its own plugin.json and .app.json, installs it, then reads the installed files → confirms the files still contain the bundled metadata while the result reports the backend version.

Call relations: This test calls validate_remote_plugin_bundle and install_remote_plugin_bundle to verify prepare_extracted_remote_plugin_root does nothing for non-global marketplaces.

Call graph: calls 2 internal fn (install_remote_plugin_bundle, validate_remote_plugin_bundle); 6 external calls (assert_eq!, tar_gz_bytes, from_str, json!, read_to_string, tempdir).

fn find_extracted_plugin_root_uses_local_manifest_discovery()

Purpose: Tests that a folder with a standard .codex-plugin/plugin.json is accepted as the plugin root.

Data flow: It creates a temporary folder with the expected manifest file → calls the root-finding behavior through the assertion → confirms the extraction root itself is returned.

Call relations: This test protects the positive case for find_extracted_plugin_root and the shared manifest discovery rule.

Call graph: 4 external calls (assert_eq!, create_dir_all, write, tempdir).

fn find_extracted_plugin_root_rejects_nested_plugin_root()

Purpose: Tests that a plugin root nested inside another folder is rejected. Remote bundles must unpack directly into the extraction root.

Data flow: It creates a temporary extraction folder with plugin.json inside a child directory → calls find_extracted_plugin_root → receives an error and checks the message.

Call relations: This test directly exercises find_extracted_plugin_root’s refusal to search for nested plugin roots.

Call graph: calls 1 internal fn (find_extracted_plugin_root); 4 external calls (assert!, create_dir_all, write, tempdir).

fn extraction_rejects_tar_path_traversal()

Purpose: Tests that an archive entry cannot escape the destination folder using a path like ../evil.txt. This is an important safety check against overwriting arbitrary files.

Data flow: It builds a tar.gz with a raw parent-directory path → tries to extract it → receives an error mentioning escape from the extraction root.

Call relations: This test calls extract_plugin_bundle_tar_gz and uses the raw-path archive helper to trigger the lower-level unpacker’s path-safety check.

Call graph: calls 1 internal fn (extract_plugin_bundle_tar_gz); 3 external calls (assert!, tar_gz_bytes_with_raw_path, tempdir).

fn extraction_rejects_total_size_over_limit()

Purpose: Tests that extraction stops when the total uncompressed files would exceed the allowed limit. This protects disk space from compressed “small outside, huge inside” archives.

Data flow: It creates an archive whose files add up beyond a tiny test limit → calls extract_plugin_bundle_tar_gz_with_limits → checks that the error is ExtractedBundleTooLarge.

Call relations: This test targets the custom-limit extraction helper directly.

Call graph: calls 1 internal fn (extract_plugin_bundle_tar_gz_with_limits); 3 external calls (assert!, tar_gz_bytes, tempdir).

fn extraction_supports_gnu_long_name_entries()

Purpose: Tests that archives using GNU tar long-name entries can still be extracted. Some valid tar files need this format for long paths.

Data flow: It builds an archive containing a deeply nested long path → extracts it → reads the resulting file and confirms its contents.

Call relations: This test calls extract_plugin_bundle_tar_gz and the normal tar-building helper to verify compatibility with long tar paths.

Call graph: calls 1 internal fn (extract_plugin_bundle_tar_gz); 4 external calls (assert_eq!, tar_gz_bytes, format!, tempdir).

fn extraction_preserves_executable_permissions()

Purpose: On Unix systems, tests that executable files stay executable after extraction. This matters for plugin helper scripts and binaries.

Data flow: It creates an archive with a plugin manifest and a helper file marked executable → extracts it → reads the file mode from disk and checks that executable permissions remain.

Call relations: This Unix-only test calls extract_plugin_bundle_tar_gz and checks behavior supplied by the archive unpacking layer.

Call graph: calls 1 internal fn (extract_plugin_bundle_tar_gz); 4 external calls (assert_eq!, tar_gz_bytes, metadata, tempdir).

fn valid_remote_plugin_bundle() -> ValidatedRemotePluginBundle

Purpose: Creates a reusable valid remote bundle plan for tests. It avoids repeating the same validation setup in multiple test cases.

Data flow: It supplies fixed valid plugin details to validate_remote_plugin_bundle → expects validation to succeed → returns the ValidatedRemotePluginBundle.

Call relations: Install-related tests call this helper before passing a bundle plan into install_remote_plugin_bundle.

Call graph: calls 1 internal fn (validate_remote_plugin_bundle).

fn tar_gz_bytes(entries: &[(&str, &[u8], u32)]) -> Vec<u8>

Purpose: Builds an in-memory tar.gz archive for tests from a list of file entries. This lets tests create plugin bundles without fixture files on disk.

Data flow: It receives paths, byte contents, and file modes → creates a gzip encoder and tar builder, appends each entry, and finishes the archive → returns the compressed bytes.

Call relations: Many extraction and install tests call this helper, which uses append_tar_entry for each file and finish_tar_gz to close the archive.

Call graph: 6 external calls (new, new, default, append_tar_entry, finish_tar_gz, new).

fn tar_gz_bytes_with_raw_path(path: &str, contents: &[u8], mode: u32) -> Vec<u8>

Purpose: Builds a special test archive with a manually written raw tar path. It is used to create unusual or unsafe paths that the normal tar builder might clean up or reject.

Data flow: It receives a raw path, contents, and mode → writes a tar header and contents directly into a gzip stream, adds padding and an end marker → returns the compressed archive bytes.

Call relations: The path-traversal test calls this to make an archive entry like ../evil.txt, then passes the result to extract_plugin_bundle_tar_gz.

Call graph: 5 external calls (new, new, default, new_gnu, vec!).

fn append_tar_entry(
        tar: &mut tar::Builder<W>,
        entry_type: tar::EntryType,
        path: &str,
        contents: &[u8],
        mode: u32,
    )

Purpose: Adds one file entry to a test tar archive with the requested path, contents, and permissions. It panics if the test archive cannot be built.

Data flow: It receives a mutable tar builder, entry type, path, contents, and mode → creates a tar header, fills in type, size, mode, and checksum, then appends the data → changes the tar builder by adding the entry.

Call relations: tests::tar_gz_bytes calls this for every requested file entry while constructing in-memory plugin bundles.

Call graph: 3 external calls (append_data, panic!, new_gnu).

fn finish_tar_gz(tar: tar::Builder<GzEncoder<Vec<u8>>>) -> Vec<u8>

Purpose: Finishes a test tar.gz archive and returns its bytes. It turns the builder state into the final compressed data used by tests.

Data flow: It receives a tar builder wrapping a gzip encoder → closes the tar builder, then finishes gzip compression → returns the final byte vector or panics if test data creation fails.

Call relations: tests::tar_gz_bytes calls this after adding all entries, so tests can pass complete archive bytes to extraction and install functions.

Call graph: 2 external calls (into_inner, panic!).

fn changed_local_cache(&self) -> bool

Purpose: This small helper answers the question: did this sync actually change anything on disk? It is used to decide whether other parts of the app need to be told that the plugin cache changed.

Data flow: It reads the outcome’s two lists of local changes: installed plugin IDs and removed cache plugin IDs. If either list has at least one item, it returns true; if both are empty, it returns false. It does not change the outcome.

Call relations: After a background sync finishes, maybe_start_remote_installed_plugin_bundle_sync checks this method before calling the optional cache-changed callback. That keeps the app from doing extra refresh work when the sync only confirmed that everything was already current.

fn maybe_start_remote_installed_plugin_bundle_sync(
    codex_home: PathBuf,
    config: RemotePluginServiceConfig,
    auth: Option<CodexAuth>,
    on_local_cache_changed: Option<Arc<dyn Fn() + Send

Purpose: This function starts a remote plugin sync in the background, but only when there is an authenticated user and no sync is already running for the same local plugin cache. It is the safe “kick off a sync if needed” entry point for this file.

Data flow: It receives the Codex home folder, remote service settings, optional authentication, and an optional callback to run if local plugin files change. If authentication is missing, it stops immediately. Otherwise it builds a cache-root key, tries to mark that key as already syncing, and if successful starts an asynchronous task. That task runs the one-time sync, logs success or failure, calls the callback if the cache changed, and finally clears the in-flight marker.

Call relations: This function uses remote_plugin_cache_root to identify the cache being protected, mark_remote_installed_plugin_bundle_sync_in_flight to prevent duplicate work, and sync_remote_installed_plugin_bundles_once to do the real sync. When the spawned task ends, it calls clear_remote_installed_plugin_bundle_sync_in_flight so a later sync can run.

Call graph: calls 4 internal fn (clear_remote_installed_plugin_bundle_sync_in_flight, mark_remote_installed_plugin_bundle_sync_in_flight, remote_plugin_cache_root, sync_remote_installed_plugin_bundles_once); 3 external calls (info!, spawn, warn!).

async fn sync_remote_installed_plugin_bundles_once(
    codex_home: PathBuf,
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<RemoteInstalledPluginBundleSyncOutcome, R

Purpose: This is the main one-shot synchronization routine. It compares the remote list of installed plugins with the local plugin cache, downloads any needed plugin bundles, and removes cached remote plugins that are no longer installed.

Data flow: It takes the local Codex home folder, remote service configuration, and authentication. First it confirms the authentication is valid for ChatGPT. Then it fetches installed remote plugins for global, workspace, and user scopes at the same time. It opens the local plugin store, builds a record of which plugin names should exist in each remote marketplace folder, and walks through every remote plugin. For each one, it creates a local plugin ID, skips it if the cached version is already the same, validates the bundle details, and downloads and installs the bundle if needed. Finally, it runs stale-cache removal on a blocking worker thread and returns an outcome listing installed plugin IDs, removed cache IDs, and failed remote IDs.

Call relations: maybe_start_remote_installed_plugin_bundle_sync calls this inside a background task. This function hands bundle checking to validate_remote_plugin_bundle, installation to download_and_install_remote_plugin_bundle, local version checks to PluginStore, and final cleanup to remove_stale_remote_plugin_caches.

Call graph: calls 4 internal fn (download_and_install_remote_plugin_bundle, validate_remote_plugin_bundle, try_new, new); called by 1 (maybe_start_remote_installed_plugin_bundle_sync); 9 external calls (from_iter, new, clone, ensure_chatgpt_auth, fetch_installed_plugins_for_scope_with_download_url, remote_plugin_canonical_marketplace_name, spawn_blocking, try_join!, warn!).

fn mark_remote_plugin_cache_mutation_in_flight(
    codex_home: &Path,
    marketplace_name: &str,
    plugin_name: &str,
) -> RemotePluginCacheMutationGuard

Purpose: This function marks one specific remote plugin cache entry as currently being changed. Callers use the returned guard to protect an install, update, or similar cache operation from being deleted by stale-cache cleanup.

Data flow: It receives the Codex home folder, marketplace name, and plugin name. It turns those into a cache mutation key, locks the shared mutation map, and increases a counter for that key. It returns a RemotePluginCacheMutationGuard that remembers the key. The counter allows nested or overlapping operations on the same plugin to be tracked safely.

Call relations: The stale-cache cleanup test calls this before running remove_stale_remote_plugin_caches to prove that cleanup skips protected entries. The guard’s Drop implementation later reverses the marker automatically when the caller is done.

Call graph: calls 1 internal fn (remote_plugin_cache_root); called by 1 (stale_remote_plugin_cleanup_skips_cache_mutations_in_progress).

fn drop(&mut self)

Purpose: This automatic cleanup runs when a cache mutation guard goes out of scope. It unregisters the protected plugin cache entry, so future stale-cache cleanup may remove it if it is no longer installed.

Data flow: It reads the key stored inside the guard, locks the shared mutation map, and lowers that key’s counter by one. If the counter reaches zero, it removes the key completely. It does not return a value; its effect is updating the shared in-flight mutation tracking.

Call relations: mark_remote_plugin_cache_mutation_in_flight creates this guard. remove_stale_remote_plugin_caches indirectly depends on it because a cache entry is skipped only while the guard still exists; once all guards are dropped, is_remote_plugin_cache_mutation_in_flight will stop reporting that entry as protected.

fn remove_stale_remote_plugin_caches(
    codex_home: &Path,
    installed_plugin_names_by_marketplace: &BTreeMap<String, BTreeSet<String>>,
) -> Result<Vec<String>, String>

Purpose: This function deletes cached remote plugin folders or files that no longer appear in the installed-plugin list. It is the cleanup step that keeps the local plugin cache from collecting old, unused remote plugins.

Data flow: It receives the Codex home folder and a map saying which plugin names are still installed in each marketplace. It checks each known remote marketplace cache folder. For every cache entry it finds, it reads the plugin name from the folder or file name, keeps it if that name is still installed, and also keeps it if another operation is currently changing that same cache entry. Otherwise it removes the directory or file from disk. It returns a sorted list of plugin IDs that were removed, or a readable error message if reading or deleting fails.

Call relations: sync_remote_installed_plugin_bundles_once calls this after downloading needed bundles, so the cache ends up matching the remote installed list. It calls is_remote_plugin_cache_mutation_in_flight before deleting anything, which prevents races with active installs or updates. The tests call it directly to check both protected-cache and stale-marketplace behavior.

Call graph: calls 2 internal fn (is_remote_plugin_cache_mutation_in_flight, new); called by 2 (stale_remote_plugin_cleanup_removes_stale_marketplace_caches_and_keeps_canonical_cache, stale_remote_plugin_cleanup_skips_cache_mutations_in_progress); 5 external calls (join, new, read_dir, remove_dir_all, remove_file).

fn remote_plugin_cache_root(codex_home: &Path) -> PathBuf

Purpose: This helper builds the path to the plugin cache directory under the user’s Codex home folder. It keeps every caller using the same idea of where cached plugins live.

Data flow: It takes a Codex home path and appends the shared plugin-cache directory name. It returns the resulting path and does not touch the filesystem.

Call relations: maybe_start_remote_installed_plugin_bundle_sync uses this path to deduplicate syncs by cache folder. mark_remote_plugin_cache_mutation_in_flight and is_remote_plugin_cache_mutation_in_flight use it to create matching keys for protected cache entries. A test also uses it when checking sync deduplication.

Call graph: called by 4 (is_remote_plugin_cache_mutation_in_flight, mark_remote_plugin_cache_mutation_in_flight, maybe_start_remote_installed_plugin_bundle_sync, remote_installed_plugin_sync_in_flight_dedupes_by_cache_root); 1 external calls (join).

fn is_remote_plugin_cache_mutation_in_flight(
    codex_home: &Path,
    marketplace_name: &str,
    plugin_name: &str,
) -> bool

Purpose: This function checks whether a specific remote plugin cache entry is currently protected because another operation is changing it. Cleanup uses it to avoid deleting files mid-install.

Data flow: It receives the Codex home folder, marketplace name, and plugin name. It looks for the shared mutation map; if none exists, it returns false. If the map exists, it locks it, builds the same key used by mark_remote_plugin_cache_mutation_in_flight, and returns whether that key is present.

Call relations: remove_stale_remote_plugin_caches calls this before deleting a stale-looking cache entry. It relies on remote_plugin_cache_root so that its lookup key matches the key created when a mutation guard was registered.

Call graph: calls 1 internal fn (remote_plugin_cache_root); called by 1 (remove_stale_remote_plugin_caches).

fn mark_remote_installed_plugin_bundle_sync_in_flight(
    key: RemoteInstalledPluginBundleSyncKey,
) -> bool

Purpose: This function records that a remote installed-plugin sync is already running for a particular plugin cache root. It returns whether the caller successfully claimed the right to run that sync.

Data flow: It receives a sync key, locks the shared set of active syncs, and tries to insert the key. If the key was not already present, insertion succeeds and it returns true. If another sync already inserted the same key, it returns false.

Call relations: maybe_start_remote_installed_plugin_bundle_sync calls this before spawning the background sync task. If it returns false, that caller does nothing, which prevents duplicate downloads and cleanup for the same cache. A test uses it to confirm this deduplication behavior.

Call graph: called by 1 (maybe_start_remote_installed_plugin_bundle_sync).

fn clear_remote_installed_plugin_bundle_sync_in_flight(key: &RemoteInstalledPluginBundleSyncKey)

Purpose: This function removes the marker that says a sync is running for a plugin cache root. It makes future sync attempts possible after the current one finishes.

Data flow: It receives a sync key, looks up the shared set of active syncs, locks it if it exists, and removes the key. It does not return anything.

Call relations: maybe_start_remote_installed_plugin_bundle_sync calls this at the end of the spawned background task, whether the sync succeeded or failed. The sync deduplication test also calls it to prove that clearing the marker allows a later sync to be marked again.

Call graph: called by 2 (maybe_start_remote_installed_plugin_bundle_sync, remote_installed_plugin_sync_in_flight_dedupes_by_cache_root).

fn remote_installed_plugin_sync_in_flight_dedupes_by_cache_root()

Purpose: This test proves that only one installed-plugin sync can be marked as running for the same cache root at a time. It also proves that clearing the marker allows a later sync to start.

Data flow: It creates a temporary Codex home folder, builds the cache-root sync key, and tries to mark it as in flight. The first mark should succeed, the second should fail because it is a duplicate, and a new mark after clearing should succeed again. The test changes only the in-memory in-flight sync set.

Call relations: The test exercises remote_plugin_cache_root, mark_remote_installed_plugin_bundle_sync_in_flight, and clear_remote_installed_plugin_bundle_sync_in_flight together. It documents the protection that maybe_start_remote_installed_plugin_bundle_sync depends on before spawning work.

Call graph: calls 2 internal fn (clear_remote_installed_plugin_bundle_sync_in_flight, remote_plugin_cache_root); 2 external calls (assert!, tempdir).

fn stale_remote_plugin_cleanup_skips_cache_mutations_in_progress()

Purpose: This test proves that stale-cache cleanup will not delete a plugin cache entry while another operation has marked that entry as being changed. It also checks that multiple guards must all be dropped before cleanup can remove the entry.

Data flow: It creates a fake cached plugin on disk, builds an installed-plugin map that says the plugin is not installed, and then registers two mutation guards for that plugin. Cleanup runs while both guards exist and removes nothing. After dropping one guard, cleanup still removes nothing. After dropping the second guard, cleanup removes the stale plugin cache and returns its plugin ID.

Call relations: The test calls mark_remote_plugin_cache_mutation_in_flight to create protection and remove_stale_remote_plugin_caches to attempt deletion. Through that path it verifies the interaction between mutation guards, their Drop behavior, and is_remote_plugin_cache_mutation_in_flight.

Call graph: calls 2 internal fn (mark_remote_plugin_cache_mutation_in_flight, remove_stale_remote_plugin_caches); 7 external calls (from_iter, new, assert!, assert_eq!, create_dir_all, write, tempdir).

fn stale_remote_plugin_cleanup_removes_stale_marketplace_caches_and_keeps_canonical_cache()

Purpose: This test proves that cleanup removes stale plugin caches from several remote marketplace folders while keeping a cache entry that is still listed as installed. It checks that cleanup respects the canonical marketplace grouping used by remote plugins.

Data flow: It creates three fake cached plugin manifests on disk: two that should be stale and one that should still be installed. It builds an installed-plugin map where only the canonical shared plugin remains installed. Then it runs cleanup and checks that the two stale cache entries are reported and deleted, while the still-installed cache file remains.

Call relations: The test directly exercises remove_stale_remote_plugin_caches. It gives confidence that the cleanup step called by sync_remote_installed_plugin_bundles_once will remove obsolete remote marketplace cache entries without deleting the current canonical cache.

Call graph: calls 1 internal fn (remove_stale_remote_plugin_caches); 8 external calls (from_iter, from, new, assert!, assert_eq!, create_dir_all, write, tempdir).

fn is_valid_remote_plugin_id(plugin_id: &str) -> bool

Purpose: Checks whether a remote plugin ID uses only the small set of safe characters Codex accepts. This prevents unsafe or malformed IDs from being sent to the remote service or used in paths and requests.

Data flow: It receives a plugin ID string, checks that it is not empty, then checks every character. It returns true only when all characters are ASCII letters, digits, underscore, dash, or tilde.

Call relations: It is the basic safety check used before plugin reads, installs, uninstalls, share operations, and recommendation filtering. validate_remote_plugin_id wraps it when callers need a structured JSON-RPC error instead of a simple true-or-false answer.

Call graph: called by 7 (plugin_share_checkout_response, plugin_share_delete_response, plugin_share_save_response, plugin_share_update_targets_response, plugin_uninstall_response, recommended_plugins_mode, validate_remote_plugin_id).

fn validate_remote_plugin_id(plugin_id: &str) -> Result<(), JSONRPCErrorError>

Purpose: Turns the raw plugin-ID safety check into an error format suitable for API responses. Callers use it when an invalid ID should stop a user-facing request cleanly.

Data flow: It receives a plugin ID, asks is_valid_remote_plugin_id whether it is safe, and returns success if so. If not, it returns a JSON-RPC error explaining which characters are allowed.

Call relations: Plugin read, skill read, install, and uninstall response builders call this before continuing. It delegates the actual character check to is_valid_remote_plugin_id.

Call graph: calls 1 internal fn (is_valid_remote_plugin_id); called by 4 (plugin_read_response, plugin_skill_read_response, remote_plugin_install_response, remote_plugin_uninstall_response).

fn api_value(self) -> &'static str

Purpose: Converts Codex's internal idea of a plugin scope into the exact word the remote API expects. For example, the internal Global scope becomes the API string "GLOBAL".

Data flow: It receives one RemotePluginScope value and returns a fixed string for that value. It does not read or change anything else.

Call relations: The page-fetching functions for directory and installed plugins call this while building query parameters for HTTP requests.

Call graph: called by 2 (get_remote_plugin_installed_page, get_remote_plugin_list_page).

fn marketplace_name(self) -> &'static str

Purpose: Maps a scope to Codex's stable internal marketplace name. This lets code refer to the global, user-created, and workspace marketplaces consistently.

Data flow: It receives a scope and returns the matching marketplace identifier string used inside Codex. No network or file access happens.

Call relations: This helper supports code that needs a canonical marketplace label for a scope, especially when building marketplace views.

fn marketplace_display_name(self) -> &'static str

Purpose: Maps a scope to the friendly marketplace name shown to people. It separates user-facing names from internal IDs.

Data flow: It receives a scope and returns a fixed display string such as "OpenAI Curated Remote" or "Workspace Directory".

Call relations: build_remote_plugin_detail calls it when filling in the display name for a plugin detail response.

Call graph: called by 1 (build_remote_plugin_detail).

fn from_marketplace_name(name: &str) -> Option<Self>

Purpose: Recognizes whether a marketplace name belongs to one of the supported remote scopes. This is a guardrail before fetching skill details.

Data flow: It receives a marketplace name string and returns the matching scope when known. Unknown names become None.

Call relations: fetch_remote_plugin_skill_detail calls it to reject unsupported marketplace names before contacting the remote service.

Call graph: called by 1 (fetch_remote_plugin_skill_detail).

fn remote_plugin_canonical_marketplace_name(
    plugin: &RemotePluginDirectoryItem,
) -> Result<&'static str, RemotePluginCatalogError>

Purpose: Finds the correct Codex marketplace bucket for a plugin returned by the remote service. Workspace plugins need extra care because listed, private, and unlisted shares are shown differently.

Data flow: It receives a remote directory item, reads its scope and sometimes its discoverability, and returns a marketplace name. If a workspace plugin is missing required sharing information, it returns an error.

Call relations: Summary building, detail fetching, installed-cache conversion, discoverable-plugin conversion, and uninstall cleanup all call this so they agree on where a remote plugin belongs. It calls workspace_plugin_discoverability for workspace-specific checks.

Call graph: calls 1 internal fn (workspace_plugin_discoverability); called by 5 (build_remote_plugin_summary, fetch_remote_plugin_detail_with_download_url_option, remote_discoverable_plugin_from_directory_item, remote_installed_plugin_to_cache_entry, uninstall_remote_plugin).

fn workspace_plugin_discoverability(
    plugin: &RemotePluginDirectoryItem,
) -> Result<RemotePluginShareDiscoverability, RemotePluginCatalogError>

Purpose: Reads the sharing visibility of a workspace plugin and treats missing visibility as a bad server response. Workspace plugins cannot be sorted into the right marketplace without this value.

Data flow: It receives a remote directory item and returns its discoverability value if present. If the field is missing, it returns an UnexpectedResponse error naming the plugin.

Call relations: remote_plugin_canonical_marketplace_name uses it to choose the marketplace bucket, and remote_plugin_share_context uses it when building share information.

Call graph: called by 2 (remote_plugin_canonical_marketplace_name, remote_plugin_share_context).

async fn fetch_remote_marketplaces(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    sources: &[RemoteMarketplaceSource],
    global_catalog_cache_path: Option<&Path>,
) -> Re

Purpose: Builds the marketplace lists shown to the user by fetching remote plugin directories and installed state. It combines what exists in the catalog with what the user has installed.

Data flow: It receives service configuration, optional authentication, requested marketplace sources, and an optional cache path. It verifies authentication, fetches the needed catalog and installed pages, optionally reads or writes the global catalog cache, merges directory and installed records, and returns marketplace objects.

Call relations: plugin_list_response calls this when it needs live remote marketplace data. Inside, it calls fetch_directory_plugins_for_scope, fetch_installed_plugins_for_scope, fetch_shared_workspace_plugins, build_remote_marketplace, and the catalog cache helpers.

Call graph: calls 7 internal fn (build_remote_marketplace, load_cached_global_directory_plugins, write_cached_global_directory_plugins, ensure_chatgpt_auth, fetch_directory_plugins_for_scope, fetch_installed_plugins_for_scope, fetch_shared_workspace_plugins); called by 1 (plugin_list_response); 3 external calls (new, iter, try_join!).

async fn fetch_and_cache_global_remote_plugin_catalog(
    codex_home: &Path,
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<(), RemotePluginCatalogError>

Purpose: Refreshes the cached copy of the global remote plugin catalog. This makes later startup or suggestion flows faster and more resilient.

Data flow: It receives the Codex home path, service config, and authentication. After checking auth, it fetches the global directory and writes the result into the catalog cache.

Call relations: Startup tasks, cache refresh loops, and suggestion flows call this when they want a fresh global catalog available locally. It relies on fetch_directory_plugins_for_scope and the cache writer.

Call graph: calls 3 internal fn (write_cached_global_directory_plugins, ensure_chatgpt_auth, fetch_directory_plugins_for_scope); called by 4 (expands_cached_remote_plugins_by_loaded_apps, maybe_start_plugin_startup_tasks_for_config, run_global_remote_catalog_cache_refresh_loop, list_tool_suggest_discoverable_plugins_includes_cached_remote_global_plugins).

async fn fetch_recommended_plugins(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<RecommendedPluginsMode, RemotePluginCatalogError>

Purpose: Asks the remote service for plugins it recommends, then converts the reply into Codex's recommendation mode. If the endpoint is not enabled, Codex falls back to legacy behavior.

Data flow: It receives config and auth, verifies auth, builds an authenticated GET request to the suggested-plugins endpoint, decodes the response, and returns either Legacy mode or a cleaned list of recommended plugins.

Call relations: It prepares the HTTP request with authenticated_request, sends it through send_and_decode, and hands the decoded response to recommended_plugins_mode for filtering.

Call graph: calls 5 internal fn (authenticated_request, ensure_chatgpt_auth, recommended_plugins_mode, send_and_decode, build_reqwest_client); 1 external calls (format!).

fn recommended_plugins_mode(response: RecommendedPluginsResponse) -> RecommendedPluginsMode

Purpose: Cleans and limits the recommendation response from the server. It drops invalid, unavailable, duplicate, or overly long entries before Codex shows them.

Data flow: It receives a decoded recommendation response. If the endpoint is not explicitly enabled, it returns Legacy mode; otherwise it validates IDs, names, policies, display names, and app IDs, then returns up to the configured maximum recommendations.

Call relations: fetch_recommended_plugins calls this after decoding the remote response. It uses is_valid_remote_plugin_id, non_empty_string, and PluginId creation to make sure recommendations can safely become local config IDs.

Call graph: calls 3 internal fn (is_valid_remote_plugin_id, non_empty_string, new); called by 1 (fetch_recommended_plugins); 3 external calls (new, new, warn!).

fn has_cached_global_remote_plugin_catalog(
    codex_home: &Path,
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> bool

Purpose: Answers whether a usable cached global catalog already exists for this user and service configuration. This lets callers decide whether they can show cached remote plugins without fetching.

Data flow: It receives Codex home, config, and optional auth. If auth is missing or unsupported, it returns false; otherwise it tries to load the cached catalog and returns whether one was found.

Call relations: plugin_list_response calls this as a quick cache availability check. It uses ensure_chatgpt_auth and the catalog cache loader.

Call graph: calls 2 internal fn (load_cached_global_directory_plugins, ensure_chatgpt_auth); called by 1 (plugin_list_response).

fn cached_global_remote_discoverable_plugins(
    codex_home: &Path,
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
) -> Vec<RemoteDiscoverablePlugin>

Purpose: Reads cached global plugins and turns them into lightweight discoverable-plugin records for suggestions. Bad cached entries are skipped rather than breaking the whole list.

Data flow: It receives Codex home, config, and auth, loads the cached global directory if present, converts each directory item into a discoverable plugin, logs conversion failures, and returns the successful entries.

Call relations: cached_global_remote_discoverable_plugins_for_config calls this when suggestions need cached remote plugin data. The conversion work is done by remote_discoverable_plugin_from_directory_item.

Call graph: calls 1 internal fn (load_cached_global_directory_plugins); called by 1 (cached_global_remote_discoverable_plugins_for_config).

async fn fetch_openai_curated_remote_collection_marketplace(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<Option<RemoteMarketplace>, RemotePluginCatalogError>

Purpose: Fetches a special curated collection from the global remote marketplace. This is used when Codex wants a narrower OpenAI-curated view instead of the full global catalog.

Data flow: It receives config and auth, verifies auth, fetches global directory plugins for the configured collection and global installed plugins in parallel, then merges them into one marketplace if any plugins exist.

Call relations: plugin_list_response calls this for the curated remote collection. It uses build_remote_marketplace after fetching the directory and installed lists.

Call graph: calls 2 internal fn (build_remote_marketplace, ensure_chatgpt_auth); called by 1 (plugin_list_response); 1 external calls (try_join!).

fn build_remote_marketplace(
    name: &str,
    display_name: &str,
    directory_plugins: Vec<RemotePluginDirectoryItem>,
    installed_plugins: Vec<RemotePluginInstalledItem>,
    include_installed

Purpose: Combines catalog entries and installed entries into one marketplace view. This is where Codex marks each listed plugin as installed or not installed.

Data flow: It receives a marketplace name, display name, directory plugin list, installed plugin list, and a flag saying whether installed-only plugins should be included. It matches installed records by remote ID, builds summaries, optionally adds installed plugins missing from the directory, and returns None if the final list is empty.

Call relations: fetch_remote_marketplaces and fetch_openai_curated_remote_collection_marketplace call this after gathering raw server data. It depends on build_remote_plugin_summary for each plugin summary.

Call graph: called by 2 (fetch_openai_curated_remote_collection_marketplace, fetch_remote_marketplaces).

async fn fetch_remote_installed_plugins(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
) -> Result<Vec<RemoteInstalledPlugin>, RemotePluginCatalogError>

Purpose: Fetches all remote plugins installed by the user across global, workspace, and user-created scopes. The result is shaped for local caching.

Data flow: It receives config and auth, verifies auth, fetches installed plugins for the three scopes in parallel, converts each installed item into a cache entry, sorts them, and returns the list.

Call relations: Installed-plugin cache builders and refresh loops call this. It uses fetch_installed_plugins_for_scope for each scope and remote_installed_plugin_to_cache_entry for conversion.

Call graph: calls 2 internal fn (ensure_chatgpt_auth, fetch_installed_plugins_for_scope); called by 2 (build_and_cache_remote_installed_plugin_marketplaces, run_remote_installed_plugins_cache_refresh_loop); 1 external calls (try_join!).

fn group_remote_installed_plugins_by_marketplaces(
    plugins: &[RemoteInstalledPlugin],
    visible_marketplaces: &[&str],
) -> Vec<RemoteMarketplace>

Purpose: Turns cached installed plugin records back into marketplace groups for display. It only includes marketplace names the caller says are visible.

Data flow: It receives installed plugin cache entries and a list of visible marketplace names. It filters hidden marketplaces, creates plugin summaries, groups them by marketplace, sorts each group by display name, and returns marketplaces in a fixed display order.

Call relations: Cache-building and cache-reading flows call this to present installed remote plugins. It uses PluginId creation and sort_remote_plugin_summaries_by_display_name to produce stable, user-friendly output.

Call graph: calls 1 internal fn (new); called by 2 (build_and_cache_remote_installed_plugin_marketplaces, build_remote_installed_plugin_marketplaces_from_cache); 1 external calls (new).

async fn fetch_remote_plugin_detail(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    marketplace_name: &str,
    plugin_id: &str,
) -> Result<RemotePluginDetail, RemotePlugin

Purpose: Fetches detailed information for one remote plugin without asking for bundle download links. This is the normal detail path for viewing a plugin.

Data flow: It receives config, auth, marketplace name, and plugin ID, then forwards the request with include-download-URLs set to false. It returns a RemotePluginDetail or an error.

Call relations: plugin_read_response calls this for plugin detail pages. It delegates all real work to fetch_remote_plugin_detail_with_download_url_option.

Call graph: calls 1 internal fn (fetch_remote_plugin_detail_with_download_url_option); called by 1 (plugin_read_response).

async fn fetch_remote_plugin_share_context(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
) -> Result<Option<RemotePluginShareContext>, RemotePluginCatalog

Purpose: Fetches just the workspace sharing context for a remote plugin. This is useful when a caller needs share metadata without the full plugin detail shape.

Data flow: It receives config, auth, and plugin ID, verifies auth, fetches the plugin detail record from the server, and extracts share context if the plugin is a workspace plugin.

Call relations: plugin_read_response calls this when share information is needed. It uses fetch_plugin_detail for the remote read and remote_plugin_share_context for translation.

Call graph: calls 3 internal fn (ensure_chatgpt_auth, fetch_plugin_detail, remote_plugin_share_context); called by 1 (plugin_read_response).

async fn fetch_remote_plugin_detail_with_download_urls(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    marketplace_name: &str,
    plugin_id: &str,
) -> Result<RemotePluginD

Purpose: Fetches detailed plugin information and asks the server to include bundle download links. This is used for install flows that may need to download plugin contents.

Data flow: It receives config, auth, marketplace name, and plugin ID, then forwards the request with include-download-URLs set to true. It returns the same detail shape as the normal detail function, with download URLs included when available.

Call relations: remote_plugin_install_response calls this after installing or preparing an install. It delegates to fetch_remote_plugin_detail_with_download_url_option.

Call graph: calls 1 internal fn (fetch_remote_plugin_detail_with_download_url_option); called by 1 (remote_plugin_install_response).

async fn fetch_remote_plugin_skill_detail(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    marketplace_name: &str,
    plugin_id: &str,
    skill_name: &str,
) -> Result<Remo

Purpose: Fetches the markdown contents for a single skill inside a remote plugin. It also checks that the server returned the same plugin ID and skill name that were requested.

Data flow: It receives config, auth, marketplace name, plugin ID, and skill name. It verifies auth and marketplace support, builds a safe URL, sends an authenticated request, decodes the response, checks IDs for consistency, and returns the skill contents.

Call relations: plugin_skill_read_response calls this when a user opens a remote skill. It uses RemotePluginScope::from_marketplace_name, remote_plugin_skill_detail_url, authenticated_request, and send_and_decode.

Call graph: calls 6 internal fn (from_marketplace_name, authenticated_request, ensure_chatgpt_auth, remote_plugin_skill_detail_url, send_and_decode, build_reqwest_client); called by 1 (plugin_skill_read_response).

async fn fetch_remote_plugin_detail_with_download_url_option(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    _marketplace_name: &str,
    plugin_id: &str,
    include_downlo

Purpose: Shared detail-fetching path for both normal detail reads and detail reads that include download links. It treats the server's plugin record as the source of truth for the actual marketplace.

Data flow: It receives config, auth, a marketplace name, plugin ID, and a download-link flag. It verifies auth, fetches the plugin record, determines the canonical marketplace from the returned record, and builds a full RemotePluginDetail.

Call relations: fetch_remote_plugin_detail and fetch_remote_plugin_detail_with_download_urls both call this. It calls fetch_plugin_detail, remote_plugin_canonical_marketplace_name, and build_remote_plugin_detail.

Call graph: calls 4 internal fn (build_remote_plugin_detail, ensure_chatgpt_auth, fetch_plugin_detail, remote_plugin_canonical_marketplace_name); called by 2 (fetch_remote_plugin_detail, fetch_remote_plugin_detail_with_download_urls).

async fn build_remote_plugin_detail(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    marketplace_name: String,
    plugin_id: &str,
    plugin: RemotePl

Purpose: Assembles the full local detail view for a remote plugin. It combines the server's plugin record with installed state, skill enablement, app connectors, MCP server routing, and display metadata.

Data flow: It receives config, auth, scope, marketplace name, plugin ID, and the remote plugin record. It fetches installed plugins for the scope, finds this plugin if installed, marks disabled skills, derives app IDs from the app manifest or app IDs, applies app-to-MCP routing policy, and returns a complete RemotePluginDetail.

Call relations: fetch_remote_plugin_detail_with_download_url_option calls this after the raw plugin has been fetched. It calls fetch_installed_plugins_for_scope, build_remote_plugin_summary, non_empty_string, apply_app_mcp_routing_policy, and app connector helpers.

Call graph: calls 6 internal fn (apply_app_mcp_routing_policy, marketplace_display_name, build_remote_plugin_summary, fetch_installed_plugins_for_scope, non_empty_string, api_auth_mode); called by 1 (fetch_remote_plugin_detail_with_download_url_option); 1 external calls (app_connector_ids_from_declarations).

fn app_declarations_from_remote_app_ids(app_ids: &[String]) -> Vec<AppDeclaration>

Purpose: Creates simple app declarations from plain app ID strings when the server did not provide a richer app manifest. This gives later routing code a consistent shape to work with.

Data flow: It receives a list of app ID strings and returns one AppDeclaration per ID, using the ID as both the app name and connector ID.

Call relations: This helper is used by the detail-building path when the plugin release has app IDs but no parsed app manifest.

async fn install_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    _marketplace_name: &str,
    plugin_id: &str,
) -> Result<RemotePluginInstallResult, RemotePlu

Purpose: Tells the remote service to install and enable a plugin for the user. It verifies that the server confirms the same plugin ID and that the plugin ended up enabled.

Data flow: It receives config, auth, marketplace name, and plugin ID. It verifies auth, sends an authenticated POST request to the install endpoint, decodes the mutation response, validates the returned ID and enabled state, and returns any app IDs that still need authentication.

Call relations: remote_plugin_install_response calls this during install handling. It uses authenticated_request and send_and_decode for the HTTP work.

Call graph: calls 4 internal fn (authenticated_request, ensure_chatgpt_auth, send_and_decode, build_reqwest_client); called by 1 (remote_plugin_install_response); 1 external calls (format!).

async fn uninstall_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: PathBuf,
    plugin_id: &str,
) -> Result<(), RemotePluginCatalogError>

Purpose: Tells the remote service to uninstall a plugin and then removes Codex's local cached copy of that plugin. This keeps local files from lingering after the remote uninstall succeeds.

Data flow: It receives config, auth, Codex home path, and plugin ID. It verifies auth, fetches plugin detail to learn its marketplace and name, sends an uninstall request, checks the server confirmed disabled state, then starts a blocking cleanup task to remove cache files.

Call relations: remote_plugin_uninstall_response calls this. It uses fetch_plugin_detail, remote_plugin_canonical_marketplace_name, authenticated_request, send_and_decode, and then hands local file cleanup to remove_remote_plugin_cache.

Call graph: calls 6 internal fn (authenticated_request, ensure_chatgpt_auth, fetch_plugin_detail, remote_plugin_canonical_marketplace_name, send_and_decode, build_reqwest_client); called by 1 (remote_plugin_uninstall_response); 2 external calls (format!, spawn_blocking).

fn remove_remote_plugin_cache(
    codex_home: PathBuf,
    marketplace_name: String,
    plugin_name: String,
    legacy_plugin_id: String,
) -> Result<(), String>

Purpose: Deletes local cached files for an uninstalled remote plugin, including an older legacy cache layout if present. This prevents stale plugin bundles from remaining on disk.

Data flow: It receives Codex home, marketplace name, plugin name, and legacy remote plugin ID. It opens the plugin store, builds the modern plugin cache ID, removes that store entry, then checks and removes the legacy path if it is different and still exists.

Call relations: uninstall_remote_plugin runs this in a blocking task after the remote service confirms uninstall. It works with PluginStore and filesystem deletion calls.

Call graph: calls 2 internal fn (try_new, new); 4 external calls (clone, join, remove_dir_all, remove_file).

fn build_remote_plugin_summary(
    plugin: &RemotePluginDirectoryItem,
    installed_plugin: Option<&RemotePluginInstalledItem>,
) -> Result<RemotePluginSummary, RemotePluginCatalogError>

Purpose: Creates the compact plugin summary used in marketplace lists. It records identity, install state, policies, display metadata, keywords, and workspace share context.

Data flow: It receives a directory plugin and an optional installed record. It determines the marketplace, creates a stable local plugin ID, extracts share context and interface information, marks whether it is installed and enabled, and returns a RemotePluginSummary.

Call relations: build_remote_plugin_detail calls this for the detail's summary, and marketplace-building code uses the same logic for list entries. It calls remote_plugin_canonical_marketplace_name, remote_plugin_share_context, and remote_plugin_interface_to_info.

Call graph: calls 4 internal fn (remote_plugin_canonical_marketplace_name, remote_plugin_interface_to_info, remote_plugin_share_context, new); called by 1 (build_remote_plugin_detail).

fn remote_discoverable_plugin_from_directory_item(
    plugin: &RemotePluginDirectoryItem,
) -> Result<RemoteDiscoverablePlugin, RemotePluginCatalogError>

Purpose: Turns a full cached directory item into a smaller record suitable for discovery and suggestions. It keeps only the fields needed to suggest or describe a plugin briefly.

Data flow: It receives a directory plugin, computes its local config ID, chooses a display name and description, records whether it has skills and which app IDs it uses, and returns a RemoteDiscoverablePlugin.

Call relations: cached_global_remote_discoverable_plugins uses this when reading cached global catalog data. It relies on remote_plugin_canonical_marketplace_name and non_empty_string.

Call graph: calls 3 internal fn (non_empty_string, remote_plugin_canonical_marketplace_name, new).

fn remote_plugin_share_context(
    plugin: &RemotePluginDirectoryItem,
) -> Result<Option<RemotePluginShareContext>, RemotePluginCatalogError>

Purpose: Extracts workspace sharing information from a plugin record. Global and user-created plugins do not have workspace share context, so they return none.

Data flow: It receives a directory plugin. For global or user-scoped plugins it returns None; for workspace plugins it checks discoverability and copies share URL, creator data, version, and share principals into a local share-context object.

Call relations: build_remote_plugin_summary and fetch_remote_plugin_share_context call this when share metadata is needed. It uses workspace_plugin_discoverability to require valid workspace visibility.

Call graph: calls 1 internal fn (workspace_plugin_discoverability); called by 2 (build_remote_plugin_summary, fetch_remote_plugin_share_context).

fn remote_installed_plugin_to_cache_entry(
    installed_plugin: &RemotePluginInstalledItem,
) -> Result<RemoteInstalledPlugin, RemotePluginCatalogError>

Purpose: Converts a server installed-plugin record into the smaller local cache record. This lets installed remote plugins be stored and shown later without refetching every detail.

Data flow: It receives an installed item, reads the embedded plugin data and enabled state, computes the marketplace name, copies policies and keywords, converts interface metadata, and returns a RemoteInstalledPlugin.

Call relations: fetch_remote_installed_plugins uses this after fetching installed plugins for all scopes. It calls remote_plugin_canonical_marketplace_name and remote_plugin_interface_to_info.

Call graph: calls 2 internal fn (remote_plugin_canonical_marketplace_name, remote_plugin_interface_to_info).

fn remote_plugin_interface_to_info(plugin: &RemotePluginDirectoryItem) -> Option<PluginInterface>

Purpose: Converts the server's release interface fields into Codex's PluginInterface shape. Empty interface data is treated as absent instead of returning a mostly blank object.

Data flow: It receives a directory plugin, trims and normalizes display name and default prompts, copies description, developer, category, URL, color, icon, logo, and screenshot fields, then returns Some(interface) only if at least one meaningful field exists.

Call relations: build_remote_plugin_summary and remote_installed_plugin_to_cache_entry call this to attach user-facing metadata. It uses non_empty_string and default-prompt normalization helpers.

Call graph: calls 1 internal fn (non_empty_string); called by 2 (build_remote_plugin_summary, remote_installed_plugin_to_cache_entry); 1 external calls (new).

fn remote_skill_interface_to_info(
    interface: Option<RemotePluginSkillInterfaceResponse>,
) -> Option<SkillInterface>

Purpose: Converts optional server skill interface data into Codex's SkillInterface shape. It avoids producing an empty interface when the server did not send useful display information.

Data flow: It receives optional skill interface data. If present, it copies display name, short description, brand color, and default prompt, then returns it only when at least one field is set.

Call relations: The plugin detail builder uses this while turning each remote skill into a RemotePluginSkill.

fn remote_plugin_display_name(plugin: &RemotePluginSummary) -> &str

Purpose: Chooses the best display name for a plugin summary. It prefers the friendly interface display name and falls back to the raw plugin name.

Data flow: It receives a plugin summary and returns a string slice pointing either to the interface display name or to the plugin's name.

Call relations: sort_remote_plugin_summaries_by_display_name uses this to sort marketplace entries by what users actually see.

fn sort_remote_plugin_summaries_by_display_name(plugins: &mut [RemotePluginSummary])

Purpose: Sorts plugin summaries in a stable, user-friendly order. It compares names without case first, then uses exact name and ID as tie breakers.

Data flow: It receives a mutable list of plugin summaries and reorders the list in place. It does not create a new list.

Call relations: group_remote_installed_plugins_by_marketplaces calls this before returning grouped installed marketplaces. It uses remote_plugin_display_name for each comparison.

Call graph: 1 external calls (sort_by).

fn non_empty_string(value: Option<&str>) -> Option<String>

Purpose: Turns optional text into a clean optional string by trimming whitespace and rejecting empty results. This keeps blank server fields from appearing as meaningful data.

Data flow: It receives an optional string slice. If the value exists and has non-whitespace characters after trimming, it returns the trimmed string; otherwise it returns None.

Call relations: Detail building, recommendation filtering, discoverable-plugin conversion, and interface conversion call this whenever they need clean user-facing text.

Call graph: called by 4 (build_remote_plugin_detail, recommended_plugins_mode, remote_discoverable_plugin_from_directory_item, remote_plugin_interface_to_info).

fn normalize_remote_default_prompts(prompts: &[String]) -> Option<Vec<String>>

Purpose: Cleans a list of default prompts from the server and limits how many Codex keeps. This prevents overly long or excessive prompt suggestions from leaking into the UI.

Data flow: It receives prompt strings, trims and validates each with normalize_remote_default_prompt, keeps only the configured maximum count, and returns None if none survive.

Call relations: remote_plugin_interface_to_info uses this when the server sends multiple default prompts for a plugin.

fn normalize_remote_default_prompt(prompt: &str) -> Option<String>

Purpose: Validates one default prompt from the server. It accepts only prompts that are non-empty after trimming and short enough for Codex's limits.

Data flow: It receives one prompt string, trims it, rejects it if empty or too long, and otherwise returns the cleaned prompt.

Call relations: normalize_remote_default_prompts uses this for lists, and remote_plugin_interface_to_info uses it for the older single-prompt field.

async fn fetch_directory_plugins_for_scope(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
) -> Result<Vec<RemotePluginDirectoryItem>, RemotePluginCatalogE

Purpose: Fetches all catalog plugins for one scope, such as global or workspace. It hides pagination so callers receive one complete list.

Data flow: It receives config, auth, and scope, then calls the shared paginated fetcher without a collection filter. It returns all directory items for that scope.

Call relations: Catalog refresh and marketplace fetching call this. It delegates to fetch_directory_plugins_for_scope_with_optional_collection.

Call graph: calls 1 internal fn (fetch_directory_plugins_for_scope_with_optional_collection); called by 2 (fetch_and_cache_global_remote_plugin_catalog, fetch_remote_marketplaces).

async fn fetch_directory_plugins_for_scope_with_collection(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    collection: &str,
) -> Result<Vec<RemotePlug

Purpose: Fetches all catalog plugins for one scope within a named collection. This supports special catalog slices such as an OpenAI-curated collection.

Data flow: It receives config, auth, scope, and collection name, then calls the shared paginated fetcher with that collection filter. It returns all matching directory items.

Call relations: The curated marketplace path uses this to narrow the global catalog. It delegates pagination to fetch_directory_plugins_for_scope_with_optional_collection.

Call graph: calls 1 internal fn (fetch_directory_plugins_for_scope_with_optional_collection).

async fn fetch_directory_plugins_for_scope_with_optional_collection(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    collection: Option<&str>,
) -> Resu

Purpose: Fetches every page of directory plugins for a scope, optionally filtered by collection. It is the common pagination loop for catalog listing.

Data flow: It starts with no page token, repeatedly requests one page, appends the returned plugins, and continues while the server provides a next-page token. It returns the combined list.

Call relations: Both directory-fetching wrappers call this. It gets each page from get_remote_plugin_list_page.

Call graph: calls 1 internal fn (get_remote_plugin_list_page); called by 2 (fetch_directory_plugins_for_scope, fetch_directory_plugins_for_scope_with_collection); 1 external calls (new).

async fn fetch_shared_workspace_plugins(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
) -> Result<Vec<RemotePluginDirectoryItem>, RemotePluginCatalogError>

Purpose: Fetches all workspace plugins explicitly shared with the user. It follows every page returned by the shared-workspace endpoint.

Data flow: It starts with no page token, requests shared workspace plugin pages, appends each page's plugins, and stops when there is no next-page token. It returns the complete shared list.

Call relations: fetch_remote_marketplaces calls this when building the "Shared with me" marketplaces. It gets each page through get_remote_shared_workspace_plugins_page.

Call graph: calls 1 internal fn (get_remote_shared_workspace_plugins_page); called by 1 (fetch_remote_marketplaces); 1 external calls (new).

async fn fetch_installed_plugins_for_scope(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
) -> Result<Vec<RemotePluginInstalledItem>, RemotePluginCatalogE

Purpose: Fetches all installed remote plugins for one scope without requesting download links. This is the normal installed-state lookup.

Data flow: It receives config, auth, and scope, then delegates to the installed pagination helper with include-download-URLs set to false. It returns installed plugin records.

Call relations: Marketplace fetching, detail building, and installed-cache refresh call this. It delegates to fetch_installed_plugins_for_scope_with_download_url.

Call graph: calls 1 internal fn (fetch_installed_plugins_for_scope_with_download_url); called by 3 (build_remote_plugin_detail, fetch_remote_installed_plugins, fetch_remote_marketplaces).

async fn fetch_installed_plugins_for_scope_with_download_url(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    include_download_urls: bool,
) -> Result<V

Purpose: Fetches every page of installed plugins for one scope, optionally asking for download URLs. It hides the remote service's pagination from callers.

Data flow: It starts with no page token, repeatedly requests installed-plugin pages, appends each page's plugins, and continues until the server stops returning a next-page token. It returns the combined installed list.

Call relations: fetch_installed_plugins_for_scope calls this with download URLs disabled. It requests each page through get_remote_plugin_installed_page.

Call graph: calls 1 internal fn (get_remote_plugin_installed_page); called by 1 (fetch_installed_plugins_for_scope); 1 external calls (new).

async fn get_remote_plugin_list_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    page_token: Option<&str>,
    collection: Option<&str>,
) -> Resul

Purpose: Requests one page of catalog plugins from the remote list endpoint. It is the low-level HTTP step behind full directory fetching.

Data flow: It receives config, auth, scope, optional page token, and optional collection. It builds the list URL, adds authentication and query parameters, sends the request, and decodes one RemotePluginListResponse.

Call relations: fetch_directory_plugins_for_scope_with_optional_collection calls this repeatedly. It uses RemotePluginScope::api_value, authenticated_request, and send_and_decode.

Call graph: calls 4 internal fn (api_value, authenticated_request, send_and_decode, build_reqwest_client); called by 1 (fetch_directory_plugins_for_scope_with_optional_collection); 1 external calls (format!).

async fn get_remote_shared_workspace_plugins_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    page_token: Option<&str>,
) -> Result<RemotePluginListResponse, RemotePluginCatalog

Purpose: Requests one page of workspace plugins shared with the user. It is the low-level HTTP step behind the shared-workspace marketplace.

Data flow: It receives config, auth, and an optional page token. It builds the shared-workspace URL, adds authentication and pagination parameters, sends the request, and decodes one list response.

Call relations: fetch_shared_workspace_plugins calls this repeatedly until all shared plugins are fetched. It uses authenticated_request and send_and_decode.

Call graph: calls 3 internal fn (authenticated_request, send_and_decode, build_reqwest_client); called by 1 (fetch_shared_workspace_plugins); 1 external calls (format!).

async fn get_remote_plugin_installed_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    scope: RemotePluginScope,
    page_token: Option<&str>,
    include_download_urls: bool,
)

Purpose: Requests one page of installed plugins for a scope. This is the low-level HTTP call behind installed-plugin lookups.

Data flow: It receives config, auth, scope, optional page token, and a download-link flag. It builds the installed URL, adds query parameters, sends the authenticated request, and decodes one installed response.

Call relations: fetch_installed_plugins_for_scope_with_download_url calls this repeatedly. It uses RemotePluginScope::api_value, authenticated_request, and send_and_decode.

Call graph: calls 4 internal fn (api_value, authenticated_request, send_and_decode, build_reqwest_client); called by 1 (fetch_installed_plugins_for_scope_with_download_url); 1 external calls (format!).

async fn fetch_plugin_detail(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    plugin_id: &str,
    include_download_urls: bool,
) -> Result<RemotePluginDirectoryItem, RemotePluginCat

Purpose: Fetches the raw server record for one plugin. Higher-level functions later translate that record into Codex's detail, share, or uninstall shapes.

Data flow: It receives config, auth, plugin ID, and a download-link flag. It builds the plugin detail URL, optionally asks for download URLs, sends the authenticated request, and returns the decoded directory item.

Call relations: Detail fetching, share-context fetching, and uninstall flows call this. It uses authenticated_request and send_and_decode.

Call graph: calls 3 internal fn (authenticated_request, send_and_decode, build_reqwest_client); called by 3 (fetch_remote_plugin_detail_with_download_url_option, fetch_remote_plugin_share_context, uninstall_remote_plugin); 1 external calls (format!).

fn remote_plugin_skill_detail_url(
    config: &RemotePluginServiceConfig,
    plugin_id: &str,
    skill_name: &str,
) -> Result<String, RemotePluginCatalogError>

Purpose: Builds a skill-detail URL safely using URL path segments. This avoids mistakes where special characters in IDs or skill names could break the path.

Data flow: It receives config, plugin ID, and skill name. It parses the base URL, appends the plugin and skill path segments, and returns the final URL string or an invalid-URL error.

Call relations: fetch_remote_plugin_skill_detail calls this before sending the skill-detail request.

Call graph: called by 1 (fetch_remote_plugin_skill_detail); 1 external calls (parse).

fn ensure_chatgpt_auth(auth: Option<&CodexAuth>) -> Result<&CodexAuth, RemotePluginCatalogError>

Purpose: Confirms that remote plugin calls have ChatGPT-backed authentication. Remote plugin catalog calls require this and do not support API-key-only authentication.

Data flow: It receives optional auth. If auth is missing, it returns AuthRequired; if the auth mode cannot use the Codex backend, it returns UnsupportedAuthMode; otherwise it returns the auth reference.

Call relations: Almost every public remote operation calls this before making a remote request, including marketplace fetches, detail reads, installs, uninstalls, recommendation fetches, and cache refreshes.

Call graph: called by 11 (fetch_and_cache_global_remote_plugin_catalog, fetch_openai_curated_remote_collection_marketplace, fetch_recommended_plugins, fetch_remote_installed_plugins, fetch_remote_marketplaces, fetch_remote_plugin_detail_with_download_url_option, fetch_remote_plugin_share_context, fetch_remote_plugin_skill_detail, has_cached_global_remote_plugin_catalog, install_remote_plugin (+1 more)).

fn authenticated_request(
    request: RequestBuilder,
    auth: &CodexAuth,
) -> Result<RequestBuilder, RemotePluginCatalogError>

Purpose: Adds the standard timeout, authentication headers, and Codex product header to an HTTP request. This keeps all remote plugin calls consistent.

Data flow: It receives a request builder and auth object, attaches a timeout, converts auth into HTTP headers, adds the product SKU header, and returns the updated request builder.

Call relations: All low-level remote calls use this before send_and_decode, including list, installed, detail, skill, recommendation, install, and uninstall requests.

Call graph: called by 8 (fetch_plugin_detail, fetch_recommended_plugins, fetch_remote_plugin_skill_detail, get_remote_plugin_installed_page, get_remote_plugin_list_page, get_remote_shared_workspace_plugins_page, install_remote_plugin, uninstall_remote_plugin); 2 external calls (timeout, auth_provider_from_auth).

async fn send_and_decode(
    request: RequestBuilder,
    url: &str,
) -> Result<T, RemotePluginCatalogError>

Purpose: Sends an HTTP request and decodes a successful JSON response into the requested Rust type. It also turns network, status-code, and JSON parsing failures into clear remote-plugin errors.

Data flow: It receives a prepared request and URL label. It sends the request, reads the status and body, returns an UnexpectedStatus error for non-success responses, and otherwise parses the body as JSON into the caller's expected type.

Call relations: Every remote HTTP operation hands its prepared request to this function. It is the final common step for list, installed, detail, skill, recommendation, install, and uninstall calls.

Call graph: called by 8 (fetch_plugin_detail, fetch_recommended_plugins, fetch_remote_plugin_skill_detail, get_remote_plugin_installed_page, get_remote_plugin_list_page, get_remote_shared_workspace_plugins_page, install_remote_plugin, uninstall_remote_plugin); 2 external calls (send, from_str).

async fn fetch_remote_featured_plugin_ids(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    product: Option<Product>,
) -> Result<Vec<String>, RemotePluginFetchError>

Purpose: Asks the remote ChatGPT plugin service for the list of featured plugin IDs. Callers use this when they want the server’s current recommendation list for a given product or platform.

Data flow: It receives the remote service configuration, optional user authentication, and an optional product name. It turns the configured base URL into a /plugins/featured request, adds a platform query value, and adds auth headers only when the provided auth is suitable for the Codex backend. It sends the request, reads the response body, rejects non-success server statuses, and finally turns the JSON response into a list of plugin ID strings.

Call relations: This is called by featured_plugin_ids_for_config when higher-level plugin code needs the featured list. Inside, it builds a standard HTTP client with build_reqwest_client, uses auth_provider_from_auth to translate login information into request headers when appropriate, and uses JSON parsing to turn the server reply into usable data.

Call graph: calls 1 internal fn (build_reqwest_client); called by 1 (featured_plugin_ids_for_config); 3 external calls (auth_provider_from_auth, format!, from_str).

async fn enable_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
) -> Result<(), RemotePluginMutationError>

Purpose: Tells the remote plugin service that a specific plugin should be enabled. It is a small public wrapper that gives the general mutation helper the concrete action name enable.

Data flow: It receives the service configuration, optional authentication, and the plugin ID to enable. It passes those values to post_remote_plugin_mutation with the action set to enable. If the remote call succeeds and the response is verified, it returns success with no extra data; otherwise it returns the detailed mutation error from the helper.

Call relations: This is called by install_plugin_with_remote_sync when a local plugin installation needs to be reflected on the remote service. It hands the real network work to post_remote_plugin_mutation, which performs authentication checks, sends the request, and validates the reply.

Call graph: calls 1 internal fn (post_remote_plugin_mutation); called by 1 (install_plugin_with_remote_sync).

async fn uninstall_remote_plugin(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
) -> Result<(), RemotePluginMutationError>

Purpose: Tells the remote plugin service that a specific plugin should be uninstalled. It is the uninstall counterpart to enable_remote_plugin.

Data flow: It receives the service configuration, optional authentication, and the plugin ID to uninstall. It forwards those values to post_remote_plugin_mutation with the action set to uninstall. If the server confirms the expected result, it returns success; if not, it returns a clear mutation error.

Call relations: This is called by uninstall_plugin_with_remote_sync when local uninstall work needs to be synchronized with the remote service. Like the enable path, it delegates the shared HTTP and validation steps to post_remote_plugin_mutation.

Call graph: calls 1 internal fn (post_remote_plugin_mutation); called by 1 (uninstall_plugin_with_remote_sync).

fn ensure_codex_backend_auth(
    auth: Option<&CodexAuth>,
) -> Result<&CodexAuth, RemotePluginMutationError>

Purpose: Checks that the caller supplied the kind of authentication required for remote plugin changes. It protects mutation requests from being sent with missing or unsupported credentials.

Data flow: It receives optional authentication. If there is no authentication, it produces an AuthRequired error. If the authentication is present but does not use the Codex backend, it produces an UnsupportedAuthMode error. If it is valid, it returns the authentication object so the request can use it.

Call relations: This is used by post_remote_plugin_mutation before any enable or uninstall request is built. It acts like a gatekeeper at the start of the mutation flow, so later code can safely create auth headers knowing the credentials are the right kind.

Call graph: called by 1 (post_remote_plugin_mutation).

async fn post_remote_plugin_mutation(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    plugin_id: &str,
    action: &str,
) -> Result<RemotePluginMutationResponse, RemotePlugi

Purpose: Performs the shared remote request for plugin-changing actions, such as enable and uninstall. It centralizes the careful parts: authentication, URL construction, HTTP sending, JSON decoding, and response sanity checks.

Data flow: It receives the service configuration, optional authentication, the plugin ID, and an action string such as enable or uninstall. It first verifies the authentication, then builds the correct URL for that plugin and action. It sends an authenticated POST request with a timeout, reads the response body, rejects failed HTTP statuses, parses the JSON response, and checks that the server replied about the same plugin and with the expected enabled state. On success, it returns the parsed response; on failure, it returns a specific mutation error.

Call relations: enable_remote_plugin and uninstall_remote_plugin both call this helper so the two public actions behave consistently. It calls ensure_codex_backend_auth to validate credentials, remote_plugin_mutation_url to build the endpoint, build_reqwest_client to create the HTTP client, auth_provider_from_auth to make request headers, and JSON parsing to decode the server’s reply.

Call graph: calls 3 internal fn (ensure_codex_backend_auth, remote_plugin_mutation_url, build_reqwest_client); called by 2 (enable_remote_plugin, uninstall_remote_plugin); 2 external calls (auth_provider_from_auth, from_str).

fn remote_plugin_mutation_url(
    config: &RemotePluginServiceConfig,
    plugin_id: &str,
    action: &str,
) -> Result<String, RemotePluginMutationError>

Purpose: Builds the exact web address for a remote plugin mutation request. It keeps URL construction in one place so enable and uninstall requests use the same path rules.

Data flow: It receives the remote service configuration, the plugin ID, and the action name. It parses the configured ChatGPT base URL, removes an empty trailing path piece if needed, then appends plugins, the plugin ID, and the action. It returns the finished URL string, or an error if the base URL is invalid or cannot accept path segments.

Call relations: This is called by post_remote_plugin_mutation just before the HTTP request is created. Its output becomes the destination for the POST request, so a bad base URL is caught early and reported as a mutation setup error rather than becoming a confusing network failure later.

Call graph: called by 1 (post_remote_plugin_mutation); 1 external calls (parse).

async fn save_remote_plugin_share(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
    plugin_path: &AbsolutePathBuf,
    remote_plugin_id: Option<&str>,

Purpose: Uploads a local plugin folder to the remote workspace plugin service and creates or updates a shared plugin record. A caller uses this when the user wants to publish a plugin or save a new version of an existing shared plugin.

Data flow: It receives service settings, optional login information, the Codex home folder, the local plugin path, an optional existing remote plugin ID, and access rules. It requires a ChatGPT login, compresses the plugin folder into a tar.gz archive, asks the server for an upload URL, sends the archive to that URL, adjusts the share targets when needed, finalizes the upload with the server, and records the remote ID to local path mapping on disk. It returns the remote plugin ID and, if the service provides one, a share URL.

Call relations: This is a top-level sharing operation called by higher-level plugin commands. Inside it, the archive work is moved to a blocking worker so the async task is not stalled, then it calls create_workspace_plugin_upload, put_workspace_plugin_upload, ensure_unlisted_workspace_target, and finalize_workspace_plugin_upload in order. After the server confirms the share, it asks local_paths::record_plugin_share_local_path to remember the local folder; if that bookkeeping fails, it warns but still treats the remote save as successful.

Call graph: calls 6 internal fn (create_workspace_plugin_upload, ensure_unlisted_workspace_target, finalize_workspace_plugin_upload, record_plugin_share_local_path, put_workspace_plugin_upload, as_path); 4 external calls (UnexpectedResponse, spawn_blocking, clone, warn!).

async fn list_remote_plugin_shares(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
) -> Result<Vec<RemotePluginShareSummary>, RemotePluginCatalogError>

Purpose: Builds the list of workspace plugins the current user has created and shared. It enriches the remote data with installation status and any remembered local folder path.

Data flow: It receives service settings, optional login information, and the Codex home folder. It fetches all created workspace plugins from the remote service, fetches currently installed workspace plugins, loads the local remote-ID-to-path mapping from disk, and combines these into share summaries. It returns a vector of summaries, or an error if required share information is missing.

Call relations: This is used when a higher-level command needs to show the user their shared plugins. It starts by calling fetch_created_workspace_plugins for the remote created list, then also relies on other remote catalog helpers and local_paths::load_plugin_share_local_paths so the final display can connect server-side plugins with local folders.

Call graph: calls 2 internal fn (fetch_created_workspace_plugins, load_plugin_share_local_paths); 1 external calls (new).

fn load_plugin_share_remote_ids_by_local_path(
    codex_home: &Path,
) -> io::Result<BTreeMap<AbsolutePathBuf, String>>

Purpose: Loads the saved mapping between local plugin folders and remote plugin IDs, but returns it in the direction that is convenient for looking up a remote ID from a local path.

Data flow: It receives the Codex home folder. It reads the stored mapping from disk, checks that every remote plugin ID looks valid, flips each pair from remote ID → local path into local path → remote ID, and returns the new map. If the saved data contains an invalid remote ID, it returns an input/output error.

Call relations: This is a utility-style public helper for code that starts from a local plugin folder and wants to know whether it already has a remote share. It delegates the actual disk read to local_paths::load_plugin_share_local_paths and adds validation plus the reversed lookup shape.

Call graph: calls 1 internal fn (load_plugin_share_local_paths).

async fn delete_remote_plugin_share(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    codex_home: &Path,
    remote_plugin_id: &str,
) -> Result<(), RemotePluginCatalogError>

Purpose: Deletes a shared workspace plugin from the remote service and removes its saved local-path record. A caller uses this when the user no longer wants a plugin share to exist.

Data flow: It receives service settings, optional login information, the Codex home folder, and the remote plugin ID to delete. It builds the delete URL, sends an authenticated HTTP DELETE request, checks that the server replied with the expected “no content” status, and then removes the local mapping from disk. It returns nothing on success.

Call relations: This is a top-level delete operation used by higher-level plugin commands. It builds a request with build_reqwest_client, hands the actual status checking to send_and_expect_status, and then asks local_paths::remove_plugin_share_local_path to clean up local bookkeeping. If that local cleanup fails, it logs a warning rather than undoing the successful remote deletion.

Call graph: calls 3 internal fn (remove_plugin_share_local_path, send_and_expect_status, build_reqwest_client); 2 external calls (format!, warn!).

async fn update_remote_plugin_share_targets(
    config: &RemotePluginServiceConfig,
    auth: Option<&CodexAuth>,
    remote_plugin_id: &str,
    targets: Vec<RemotePluginShareTarget>,
    discoverab

Purpose: Changes who can access an existing shared plugin and whether it is unlisted or private. It is used when the plugin stays the same but its sharing permissions need to change.

Data flow: It receives service settings, optional login information, a remote plugin ID, a list of target users/groups/workspaces, and the desired discoverability setting. It converts the update setting into the broader discoverability type, adds the current workspace as a target when an unlisted share needs it, sends an authenticated HTTP PUT request with the new rules, and returns the server’s updated principals and discoverability.

Call relations: This is a public update operation for sharing commands. Before sending the request, it calls ensure_unlisted_workspace_target so unlisted workspace shares remain usable, then uses the configured base URL and HTTP client to send the permission update to the remote service.

Call graph: calls 2 internal fn (ensure_unlisted_workspace_target, build_reqwest_client); 1 external calls (format!).

fn ensure_unlisted_workspace_target(
    auth: &CodexAuth,
    discoverability: Option<RemotePluginShareDiscoverability>,
    targets: Option<Vec<RemotePluginShareTarget>>,
) -> Result<Option<Vec<Remo

Purpose: Makes sure an unlisted workspace share includes the current workspace as a reader. This prevents creating an unlisted share that accidentally does not include the workspace it is meant to belong to.

Data flow: It receives the authenticated account, an optional discoverability value, and optional share targets. If the share is not unlisted, it leaves the targets unchanged. If it is unlisted, it reads the account ID from the login, creates an empty target list if needed, adds the workspace reader target when it is missing, and returns the updated list.

Call relations: Both save_remote_plugin_share and update_remote_plugin_share_targets call this before sending share rules to the server. It depends on CodexAuth::get_account_id to know the current workspace/account identifier; if that ID is unavailable for an unlisted share, it stops the operation with an error.

Call graph: calls 1 internal fn (get_account_id); called by 2 (save_remote_plugin_share, update_remote_plugin_share_targets).

async fn fetch_created_workspace_plugins(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
) -> Result<Vec<RemotePluginDirectoryItem>, RemotePluginCatalogError>

Purpose: Fetches every workspace plugin created by the current user, even when the server returns the results in pages. It hides pagination from its callers.

Data flow: It receives service settings and an authenticated account. It repeatedly asks for one page of created workspace plugins, appends those plugins to a growing list, and follows the next-page token until there are no more pages. It returns the complete list.

Call relations: list_remote_plugin_shares calls this when it needs the full created-plugin list. This function drives the loop and delegates each individual page request to get_created_workspace_plugins_page.

Call graph: calls 1 internal fn (get_created_workspace_plugins_page); called by 1 (list_remote_plugin_shares); 1 external calls (new).

async fn get_created_workspace_plugins_page(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    page_token: Option<&str>,
) -> Result<RemotePluginListResponse, RemotePluginCatalogError>

Purpose: Requests one page of created workspace plugins from the remote service. It is the small network step used by the larger pagination loop.

Data flow: It receives service settings, an authenticated account, and an optional page token. It builds the created-plugins URL, adds a page size limit and the page token when present, sends an authenticated GET request, and decodes the server response into the plugin list response type.

Call relations: fetch_created_workspace_plugins calls this once for the first page and again for each following page token. This function focuses only on one HTTP request; the caller decides whether more pages are needed.

Call graph: calls 1 internal fn (build_reqwest_client); called by 1 (fetch_created_workspace_plugins); 1 external calls (format!).

async fn create_workspace_plugin_upload(
    config: &RemotePluginServiceConfig,
    auth: &CodexAuth,
    filename: &str,
    size_bytes: usize,
    remote_plugin_id: Option<&str>,
) -> Result<Remote

Purpose: Asks the remote service for a temporary URL where the plugin archive can be uploaded. This is the first server step in saving a shared plugin.

Data flow: It receives service settings, authentication, the archive filename, archive size, and an optional existing remote plugin ID. It sends those details as JSON to the upload-url endpoint and decodes the response, which includes a file ID, an upload URL, and possibly an ETag value used later to confirm the upload.

Call relations: save_remote_plugin_share calls this after the plugin archive has been prepared. The returned upload URL is then handed to put_workspace_plugin_upload, and the returned file ID and ETag are later handed to finalize_workspace_plugin_upload.

Call graph: calls 1 internal fn (build_reqwest_client); called by 1 (save_remote_plugin_share); 1 external calls (format!).

async fn put_workspace_plugin_upload(
    upload_url: &str,
    archive_bytes: Vec<u8>,
) -> Result<(), RemotePluginCatalogError>

Purpose: Uploads the compressed plugin archive bytes to the temporary storage URL provided by the server. This sends the actual file contents, not just metadata.