Struct SettingsManager 

pub struct SettingsManager { /* private fields */ }

Settings manager: loads, migrates, merges, and persists global and trust-gated project settings.

Internally documents are raw JSON objects; merges and migrations operate at the JSON level exactly like the TypeScript implementation. Writes are performed synchronously inside setters; storage errors are recorded and surfaced through Self::drain_errors. The only methods that return errors are project writes while untrusted and the timeout getter/setter validations.

Implementations

impl SettingsManager

pub fn create( cwd: impl AsRef<Path>, agent_dir: Option<impl AsRef<Path>>, options: SettingsManagerCreateOptions, ) -> Self

Create a manager backed by settings files under agent_dir (default: get_agent_dir) and {cwd}/.pi.

pub fn from_storage( storage: Box<dyn SettingsStorage>, options: SettingsManagerCreateOptions, ) -> Self

Create a manager from an arbitrary storage backend.

pub fn in_memory( settings: &Settings, options: SettingsManagerCreateOptions, ) -> Self

Create an in-memory manager (no file I/O) seeded with settings.

pub fn get_global_settings(&self) -> Settings

Typed view of the global settings document.

pub fn get_project_settings(&self) -> Settings

Typed view of the project settings document (empty while untrusted).

pub const fn is_project_trusted(&self) -> bool

Whether the project is currently trusted.

pub fn set_project_trusted(&mut self, trusted: bool)

Change project trust. false discards project data; true reloads it.

pub fn reload(&mut self)

Reload both scopes from storage, discarding pending modifications.

pub fn apply_overrides(&mut self, overrides: &Map<String, Value>)

Apply additional overrides on top of the merged settings.

Overrides are not persisted and are discarded by the next save (TS parity).

pub fn flush(&self)

Wait for any in-process write to finish.

Setters acquire the same mutex around persistence, so this blocks until concurrent writers (if any) complete, matching TypeScript flush after the write queue drains.

pub fn drain_errors(&mut self) -> Vec<SettingsError>

Take all recorded errors, leaving the error list empty.

pub fn get_last_changelog_version(&self) -> Option<String>

lastChangelogVersion from merged settings.

pub fn set_last_changelog_version(&mut self, version: &str)

Set lastChangelogVersion (global).

pub fn get_session_dir(&self) -> Option<String>

sessionDir with ~ expansion; empty string returned verbatim.

pub fn get_default_provider(&self) -> Option<String>

defaultProvider from merged settings.

pub fn get_default_model(&self) -> Option<String>

defaultModel from merged settings.

pub fn set_default_provider(&mut self, provider: &str)

Set defaultProvider (global).

pub fn set_default_model(&mut self, model_id: &str)

Set defaultModel (global).

pub fn set_default_model_and_provider(&mut self, provider: &str, model_id: &str)

Set both defaultProvider and defaultModel with one save (global).

pub fn get_default_thinking_level(&self) -> Option<ModelThinkingLevel>

defaultThinkingLevel from merged settings.

pub fn set_default_thinking_level(&mut self, level: ModelThinkingLevel)

Set defaultThinkingLevel (global).

pub fn get_enabled_models(&self) -> Option<Vec<String>>

enabledModels from merged settings.

pub fn set_enabled_models(&mut self, patterns: Option<Vec<String>>)

Set enabledModels; None removes the key (global).

pub fn get_thinking_budgets(&self) -> Option<ThinkingBudgetsSettings>

thinkingBudgets from merged settings.

pub fn get_steering_mode(&self) -> QueueMode

Steering queue drain mode (default: one-at-a-time).

pub fn set_steering_mode(&mut self, mode: QueueMode)

Set steeringMode (global).

pub fn get_follow_up_mode(&self) -> QueueMode

Follow-up queue drain mode (default: one-at-a-time).

pub fn set_follow_up_mode(&mut self, mode: QueueMode)

Set followUpMode (global).

pub fn get_transport(&self) -> Transport

Streaming transport preference (default: auto).

pub fn set_transport(&mut self, transport: Transport)

Set transport (global).

pub fn get_theme_setting(&self) -> Option<String>

Raw theme setting when it is a string.

pub fn get_theme(&self) -> Option<String>

Theme name; None when unset or path-like (contains /).

pub fn set_theme(&mut self, theme: &str)

Set theme (global).

pub fn get_theme_paths(&self) -> Vec<String>

themes resource paths from merged settings.

pub fn set_theme_paths(&mut self, paths: Vec<String>)

Set themes resource paths (global).

pub fn set_project_theme_paths( &mut self, paths: Vec<String>, ) -> Result<(), SettingsManagerError>

Set themes resource paths in the project file.

Errors

Returns SettingsManagerError::ProjectNotTrusted when untrusted.

pub fn get_compaction_enabled(&self) -> bool

compaction.enabled (default: true).

pub fn set_compaction_enabled(&mut self, enabled: bool)

Set compaction.enabled (global, nested merge).

pub fn get_compaction_reserve_tokens(&self) -> u64

compaction.reserveTokens (default: 16384).

pub fn get_compaction_keep_recent_tokens(&self) -> u64

compaction.keepRecentTokens (default: 20000).

pub fn get_compaction_settings(&self) -> ResolvedCompactionSettings

Fully-resolved compaction settings.

pub fn get_branch_summary_settings(&self) -> ResolvedBranchSummarySettings

Fully-resolved branch-summary settings.

pub fn get_branch_summary_skip_prompt(&self) -> bool

branchSummary.skipPrompt (default: false).

pub fn get_retry_enabled(&self) -> bool

retry.enabled (default: true).

pub fn set_retry_enabled(&mut self, enabled: bool)

Set retry.enabled (global, nested merge).

pub fn get_retry_settings(&self) -> ResolvedRetrySettings

Fully-resolved automatic retry settings.

pub fn get_provider_retry_settings(&self) -> ResolvedProviderRetrySettings

Fully-resolved provider retry settings (maxRetryDelayMs default 60000).

pub fn get_http_idle_timeout_ms(&self) -> Result<u64, SettingsManagerError>

httpIdleTimeoutMs (default: 300000).

Errors

Returns SettingsManagerError::InvalidSetting when a stored value is present but not a usable timeout.

pub fn set_http_idle_timeout_ms( &mut self, timeout_ms: f64, ) -> Result<(), SettingsManagerError>

Set httpIdleTimeoutMs (global); the value is floored.

Errors

Returns SettingsManagerError::InvalidSetting when non-finite or negative.

pub fn get_web_socket_connect_timeout_ms( &self, ) -> Result<Option<u64>, SettingsManagerError>

websocketConnectTimeoutMs; None when unset.

Errors

Returns SettingsManagerError::InvalidSetting when a stored value is present but not a usable timeout.

pub fn get_hide_thinking_block(&self) -> bool

hideThinkingBlock (default: false).

pub fn get_show_cache_miss_notices(&self) -> bool

showCacheMissNotices (default: false).

pub fn get_external_editor_command(&self) -> String

External editor command: configured → VISUAL → EDITOR → notepad/nano.

pub fn set_hide_thinking_block(&mut self, hide: bool)

Set hideThinkingBlock (global).

pub fn set_show_cache_miss_notices(&mut self, show: bool)

Set showCacheMissNotices (global).

pub fn get_quiet_startup(&self) -> bool

quietStartup (default: false).

pub fn set_quiet_startup(&mut self, quiet: bool)

Set quietStartup (global).

pub fn get_double_escape_action(&self) -> DoubleEscapeAction

doubleEscapeAction (default: tree).

pub fn set_double_escape_action(&mut self, action: DoubleEscapeAction)

Set doubleEscapeAction (global).

pub fn get_tree_filter_mode(&self) -> TreeFilterMode

treeFilterMode; an unrecognized stored value yields default.

pub fn set_tree_filter_mode(&mut self, mode: TreeFilterMode)

Set treeFilterMode (global).

pub fn get_show_hardware_cursor(&self) -> bool

showHardwareCursor; falls back to PI_HARDWARE_CURSOR === "1".

pub fn set_show_hardware_cursor(&mut self, enabled: bool)

Set showHardwareCursor (global).

pub fn get_editor_padding_x(&self) -> u64

editorPaddingX (default: 0; the setter clamps to 0..=3).

pub fn set_editor_padding_x(&mut self, padding: f64)

Set editorPaddingX (global), clamped to 0..=3 after flooring.

pub fn get_output_pad(&self) -> OutputPad

outputPad; only an exact numeric 0 yields OutputPad::Zero.

pub fn set_output_pad(&mut self, padding: OutputPad)

Set outputPad (global).

pub fn get_autocomplete_max_visible(&self) -> u64

autocompleteMaxVisible (default: 5; the setter clamps to 3..=20).

pub fn set_autocomplete_max_visible(&mut self, max_visible: f64)

Set autocompleteMaxVisible (global), clamped to 3..=20 after flooring.

pub fn get_shell_path(&self) -> Option<String>

shellPath with ~ expansion; empty string returned verbatim.

pub fn set_shell_path(&mut self, path: Option<String>)

Set shellPath; None removes the key (global).

pub fn get_shell_command_prefix(&self) -> Option<String>

shellCommandPrefix from merged settings.

pub fn set_shell_command_prefix(&mut self, prefix: Option<String>)

Set shellCommandPrefix; None removes the key (global).

pub fn get_npm_command(&self) -> Option<Vec<String>>

npmCommand argv from merged settings.

pub fn set_npm_command(&mut self, command: Option<Vec<String>>)

Set npmCommand; None removes the key (global).

pub fn get_default_project_trust(&self) -> DefaultProjectTrust

defaultProjectTrust from the global settings only.

pub fn set_default_project_trust( &mut self, default_project_trust: DefaultProjectTrust, )

Set defaultProjectTrust (global).

pub fn get_collapse_changelog(&self) -> bool

collapseChangelog (default: false).

pub fn set_collapse_changelog(&mut self, collapse: bool)

Set collapseChangelog (global).

pub fn get_enable_install_telemetry(&self) -> bool

enableInstallTelemetry (default: true).

pub fn set_enable_install_telemetry(&mut self, enabled: bool)

Set enableInstallTelemetry (global).

pub fn get_enable_analytics(&self) -> bool

enableAnalytics (default: false).

pub fn get_tracking_id(&self) -> Option<String>

trackingId from merged settings.

pub fn set_enable_analytics(&mut self, enabled: bool)

Set analytics opt-in; generates a UUIDv4 tracking id on first opt-in.

pub fn get_packages(&self) -> Vec<PackageSource>

packages from merged settings.

pub fn set_packages(&mut self, packages: &[PackageSource])

Set packages (global).

pub fn set_project_packages( &mut self, packages: &[PackageSource], ) -> Result<(), SettingsManagerError>

Set packages in the project file.

Errors

Returns SettingsManagerError::ProjectNotTrusted when untrusted.

pub fn get_extension_paths(&self) -> Vec<String>

extensions resource paths from merged settings.

pub fn set_extension_paths(&mut self, paths: Vec<String>)

Set extensions resource paths (global).

pub fn set_project_extension_paths( &mut self, paths: Vec<String>, ) -> Result<(), SettingsManagerError>

Set extensions resource paths in the project file.

Errors

Returns SettingsManagerError::ProjectNotTrusted when untrusted.

pub fn get_skill_paths(&self) -> Vec<String>

skills resource paths from merged settings.

pub fn set_skill_paths(&mut self, paths: Vec<String>)

Set skills resource paths (global).

pub fn set_project_skill_paths( &mut self, paths: Vec<String>, ) -> Result<(), SettingsManagerError>

Set skills resource paths in the project file.

Errors

Returns SettingsManagerError::ProjectNotTrusted when untrusted.

pub fn get_prompt_template_paths(&self) -> Vec<String>

prompts resource paths from merged settings.

pub fn set_prompt_template_paths(&mut self, paths: Vec<String>)

Set prompts resource paths (global).

pub fn set_project_prompt_template_paths( &mut self, paths: Vec<String>, ) -> Result<(), SettingsManagerError>

Set prompts resource paths in the project file.

Errors

Returns SettingsManagerError::ProjectNotTrusted when untrusted.

pub fn get_enable_skill_commands(&self) -> bool

enableSkillCommands (default: true).

pub fn set_enable_skill_commands(&mut self, enabled: bool)

Set enableSkillCommands (global).

pub fn get_show_images(&self) -> bool

terminal.showImages (default: true).

pub fn set_show_images(&mut self, show: bool)

Set terminal.showImages (global, nested merge).

pub fn get_image_width_cells(&self) -> u64

terminal.imageWidthCells (default: 60; floored, min 1).

pub fn set_image_width_cells(&mut self, width: f64)

Set terminal.imageWidthCells (global, nested merge); floored, min 1.

pub fn get_clear_on_shrink(&self) -> bool

terminal.clearOnShrink; falls back to PI_CLEAR_ON_SHRINK === "1".

pub fn set_clear_on_shrink(&mut self, enabled: bool)

Set terminal.clearOnShrink (global, nested merge).

pub fn get_show_terminal_progress(&self) -> bool

terminal.showTerminalProgress (default: false).

pub fn set_show_terminal_progress(&mut self, enabled: bool)

Set terminal.showTerminalProgress (global, nested merge).

pub fn get_image_auto_resize(&self) -> bool

images.autoResize (default: true).

pub fn set_image_auto_resize(&mut self, enabled: bool)

Set images.autoResize (global, nested merge).

pub fn get_block_images(&self) -> bool

images.blockImages (default: false).

pub fn set_block_images(&mut self, blocked: bool)

Set images.blockImages (global, nested merge).

pub fn get_code_block_indent(&self) -> String

markdown.codeBlockIndent (default: two spaces).

pub fn get_warnings(&self) -> WarningSettings

warnings object (empty when absent).

pub fn set_warnings(&mut self, warnings: &WarningSettings)

Set warnings (global, full overlay).