Struct LiveConfigReadGuard 

pub struct LiveConfigReadGuard<'a> { /* private fields */ }

Short-lived paired read of the published config and its revision.

Dereferences to Config so ordinary read sites keep their shape. The guard is a parking_lot read guard: it is !Send and must never be held across an .await — clone out what crosses an async boundary.

Implementations

impl LiveConfigReadGuard<'_>

pub fn revision(&self) -> ConfigRevision

The revision of the config this guard exposes, observed under the same lock acquisition as the config itself.

Methods from Deref<Target = Config>

pub fn secret_fields(&self) -> Vec<SecretFieldInfo>

Returns metadata about all #[secret] fields on this struct and nested children.

pub fn prop_fields(&self) -> Vec<PropFieldInfo>

Returns metadata about all property fields on this struct and nested children.

pub fn get_prop(&self, name: &str) -> Result<String>

Get a property value by its full dotted name, returning it as a display string.

pub fn get_map_keys(&self, section_path: &str) -> Option<Vec<String>>

Return the current alias keys at section_path, or None if the path doesn’t resolve to a map-keyed section in this tree.

pub fn nested_option_entries(&self) -> Vec<NestedOptionEntry>

pub fn resolve_alias_source(&self, source: AliasSource) -> Vec<String>

Resolve the configured alias values valid for an crate::traits::AliasSource. Two-tier sources return dotted <type>.<alias> keys; flat sources return bare alias keys. The single resolver every surface uses for PropKind::AliasRef pickers and validation.

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

Return the first concrete model string available for use as a default: the model declared by the first entry that has one. Entries are visited in macro slot order, then sorted alias order within each slot, as implemented by ModelProviders::first_entry_with_model. Returns None only when no model-provider entry has any model configured at all.

pub fn risk_profile_for_agent( &self, agent_alias: &str, ) -> Option<&RiskProfileConfig>

Resolve the risk profile for an explicit agent alias.

Each agent’s risk_profile field names a [risk_profiles.<alias>] entry that gates its actions. There is no “global” risk profile in every callsite must come through an agent. When the agent has no profile set or names a missing entry, returns None and the caller decides how to handle it (validation rejects this shape at load time; the runtime treating None as a config error).

pub fn reachable_delegate_target_configs( &self, caller_alias: &str, ) -> Vec<DelegateTargetConfig>

Resolve the delegate targets caller_alias may reach: same-profile peers when delegate_same_risk_profile is set, unioned with the explicit delegates roster, minus the caller. Single source of truth for delegate reach and mode; gating (delegation_policy) is enforced separately by the caller. Deduped, sorted; unknown caller yields empty. Disabled targets are never reachable. Explicit entries override the bounded mode used for implicit same-profile peers.

pub fn reachable_delegate_targets(&self, caller_alias: &str) -> Vec<String>

Resolve only the agent aliases reachable by caller_alias. Use Self::reachable_delegate_target_configs when the target mode matters.

pub fn delegate_target_mode( &self, caller_alias: &str, target_alias: &str, ) -> Option<DelegateExecutionMode>

Resolve the execution mode for one reachable delegate target.

Target aliases are normalized the same way the reachable roster normalizes explicit delegates entries. This keeps callers that need one target mode aligned with the canonical roster resolver instead of creating a subtly different admission rule.

pub fn runtime_profile_for_agent( &self, agent_alias: &str, ) -> Option<&RuntimeProfileConfig>

Resolve the [runtime_profiles.<alias>] entry owned by an agent (via agents.<alias>.runtime_profile). Returns None when the agent has no runtime profile set or names a missing entry. Unlike risk_profile_for_agent, the missing case is not a hard error because runtime budgets and tunables fall back to global defaults.

pub fn effective_summary_provider( &self, agent_alias: &str, ) -> Option<ModelProviderRef>

Effective context-compression summarizer provider for an agent: agent-level summary_provider override → the runtime profile’s context_compression.summary_provider → None (the caller then reuses the agent’s own provider+model, optionally via the deprecated summary_model swap). Unlike the inert agent-inline tunables below, the agent-level override IS consulted — it’s an explicit per-agent choice, mirroring classifier_provider’s “empty = inherit” semantics.

pub fn effective_max_tool_iterations(&self, agent_alias: &str) -> usize

pub fn effective_single_tool_rounds(&self, agent_alias: &str) -> bool

pub fn effective_max_execution_tree_iterations( &self, agent_alias: &str, ) -> Option<usize>

pub fn effective_max_history_messages(&self, agent_alias: &str) -> usize

pub fn effective_structured_max_history_messages( &self, agent_alias: &str, ) -> usize

Resolve the whole-turn history cap used by structured Agent sessions.

The legacy config key is named max_history_messages, but structured Agent sessions enforce it at complete user-turn boundaries. Tool-call and tool-result rows therefore do not consume independent slots there.

pub fn effective_max_context_tokens(&self, agent_alias: &str) -> Option<usize>

pub fn effective_context_compact_ratio(&self, agent_alias: &str) -> Option<f64>

Optional fraction of the selected model’s context window at which proactive trimming fires. Invalid values are treated as unset so they cannot silently opt an existing profile into model-relative budgeting.

pub fn configured_model_context_window( &self, agent_alias: &str, ) -> Option<usize>

The model’s context window exactly as configured, or None when no provider profile declares one.

None means unknown, not “small”. Report it to an operator as unset rather than resolving it to UNCONFIGURED_CONTEXT_WINDOW_FALLBACK, which would present a stub as though it were the model’s real capacity. Use Config::effective_model_context_window when a number is required for budget arithmetic.

pub fn effective_model_context_window(&self, agent_alias: &str) -> usize

Returns the model’s context window size (max input tokens). Source: provider config context_window → UNCONFIGURED_CONTEXT_WINDOW_FALLBACK. Does NOT check runtime profile (that’s for output budget).

pub fn resolved_model_context_window( &self, agent_alias: &str, ) -> ResolvedModelContextWindow

Resolve model capacity and its provenance for an agent’s configured route. Unknown agents and unconfigured capacities retain the numeric compatibility fallback while remaining explicitly identifiable.

pub fn effective_model_context_window_for_route( &self, model_provider_ref: &str, selected_model: &str, ) -> usize

Resolve model capacity for the provider alias and model selected for a turn. context_window describes the model configured on that alias; a different per-session model override therefore falls back to the legacy unknown-capacity value instead of borrowing metadata for another model.

pub fn resolved_model_context_window_for_route( &self, model_provider_ref: &str, selected_model: &str, ) -> ResolvedModelContextWindow

Resolve capacity for exactly the selected provider profile and model. A model mismatch or missing positive context_window is an explicit compatibility fallback, never borrowed metadata from another model.

pub fn resolved_context_limits_for_route( &self, agent_alias: &str, model_provider_ref: &str, selected_model: &str, ) -> ResolvedContextLimits

Resolve one route’s capacity and proactive budget from their canonical owners: the selected provider alias/model and the agent runtime profile.

pub fn model_provider_context_window_opt( &self, provider_ref: &str, model: &str, ) -> Option<usize>

Provider’s explicit context_window for the served model, or None. Use on wire boundaries: emitting the 32k stub from effective_model_context_window() would freeze the client meter at 32k instead of the profile budget. Use this instead of the agent-alias variant when the live provider identity is known (e.g., from Agent.attribution_fields().1 or SessionOverrides.model_provider). Returns None when the ref is unparseable, the entry has no context_window, or the served model does not match the entry’s configured primary model, so the wire omission path preserves absence (no 32k stub leak) and fallback/vision/override models never borrow another model’s capacity.

pub fn effective_memory_recall_limit(&self, agent_alias: &str) -> usize

pub fn effective_compact_context(&self, agent_alias: &str) -> bool

pub fn effective_parallel_tools(&self, agent_alias: &str) -> bool

pub fn effective_tool_dispatcher(&self, agent_alias: &str) -> String

pub fn effective_tool_call_dedup_exempt(&self, agent_alias: &str) -> Vec<String>

pub fn effective_max_system_prompt_chars(&self, agent_alias: &str) -> usize

pub fn effective_max_tool_result_chars(&self, agent_alias: &str) -> usize

pub fn effective_keep_tool_context_turns(&self, agent_alias: &str) -> usize

pub fn resolved_agent_config( &self, agent_alias: &str, ) -> Option<AliasedAgentConfig>

Return a clone of the named agent’s AliasedAgentConfig with all runtime-profile overrides baked in. Use this when an Agent (or any other struct) needs to own a self-contained, already-resolved view of the agent’s runtime knobs without holding a reference to the full Config.

Returns None when agent_alias is not present in agents.

Semantics: every field touched here mirrors the matching effective_* helper above. If you add a new runtime_profile knob, add it both to an effective_* helper and to this function so downstream consumers see consistent values regardless of which surface they read from.

pub fn effective_skills_prompt_mode( &self, agent_alias: &str, ) -> SkillsPromptInjectionMode

Resolve the effective skills prompt-injection mode for an agent: use an explicit runtime-profile override when set, otherwise inherit the global [skills] prompt_injection_mode value.

Keyed on the resolved runtime profile — the sanctioned surface for per-agent runtime tunables — so agent-inline knobs stay inert. Centralizing the fallback here keeps the system-prompt builder and the read_skill tool-registration gate in lockstep on one effective mode, so a compact prompt is never paired with a missing read_skill tool (or a full prompt with a spurious one).

pub fn model_provider_for_agent( &self, agent_alias: &str, ) -> Option<&ModelProviderConfig>

Resolve an agent’s model_provider reference ("<type>.<alias>") to its concrete ModelProviderConfig entry. Returns None when the agent doesn’t exist, the reference is unparseable, or the <type>.<alias> pair doesn’t resolve in providers.models.

This is the lookup the orchestrator uses to build per-agent model_provider runtime options via explicit <type>.<alias> resolution — there is no concept of a “first” or “default” provider. The matching split logic lives in crates/zeroclaw-runtime/src/tools/delegate.rs::resolve_brain for the delegation path; this helper exposes the same contract for the channel-server startup path.

pub fn resolved_model_provider_for_agent( &self, agent_alias: &str, ) -> Option<(&'static str, &str, &ModelProviderConfig)>

Resolve (provider_type, provider_alias, &ModelProviderConfig) for an agent. Same lookup as model_provider_for_agent but also returns the 'static type key that downstream provider factories (create_routed_model_provider_with_options, etc.) need. Returns None when the agent has no model_provider set, when the reference is unparseable, or when the resolved entry has been deleted from providers.models.

pub fn agent_for_channel(&self, channel_alias: &str) -> Option<&str>

Reverse-lookup the agent alias that owns a configured channel (<type>.<alias>). Returns the first agent listing the channel in its channels field. None when no agent owns the channel — orphaned channels are a config error the orchestrator surfaces at startup.

pub fn channel_workspace_dir(&self, channel_ref: &str) -> PathBuf

Workspace dir a channel’s inbound-media handler writes into. Resolves the channel’s owning agent and returns <install>/agents/<alias>/workspace/; falls back to data_dir for orphan channels (no owning agent enabled).

pub fn channels_by_alias(&self) -> Vec<ChannelAliasInfo>

Schema-walk: every populated [channels.<type>.<alias>] block. Type names come from the prop_fields() enumeration (kebab as the macro emits them) so adding a new channel type via the macro surfaces here without touching this code. Alias keys are HashMap keys; not kebab-converted.

pub fn agent_for_cron_job(&self, cron_alias: &str) -> Option<&str>

The single enabled agent that claims cron_alias through [agents.<alias>].cron_jobs, or None when the claim is not unique. This is the answer to “who owns this cron job” for ownership that lives only in configuration: the scheduler’s execution fallback, declarative sync, and upgrade ownership recovery all use it. A job row that already carries a stored owner is resolved through that stored alias first (see the runtime’s owner resolution), so this rule governs empty-alias rows and not-yet-materialized declarative ids. agents is a hash map, so an id claimed by two enabled agents would otherwise resolve to whichever one iteration yields first, differing between processes; such a job is refused rather than run under a coin-flip authority. See Config::cron_job_claim for the reason a claim is not unique.

pub fn cron_job_claim(&self, cron_alias: &str) -> CronJobClaim<'_>

How [agents.<alias>].cron_jobs membership claims cron_alias.

pub fn agent_workspace_dir(&self, agent_alias: &str) -> PathBuf

Resolve the per-agent workspace directory for alias.

Returns the agent’s [agents.<alias>.workspace.path] override when set (operator-explicit, e.g. for putting a workspace on a different disk), otherwise derives <install>/agents/<alias>/workspace/ from the install root (the directory containing config.toml).

Per-agent workspaces live under <install>/agents/<alias>/workspace/ and hold the agent’s markdown memory (MEMORY.md), identity files (IDENTITY.md, SOUL.md), and any other per-agent plaintext state. Shared databases (SQLite memory, sessions, cost records) live under config.data_dir instead and partition by agent at the row level. Per-agent overrides via [agents.<alias>.workspace.path] pin an arbitrary filesystem path (e.g. a different mount).

pub fn mcp_servers_for_agent(&self, agent_alias: &str) -> Vec<McpServerConfig>

Effective MCP servers granted to an agent by its mcp_bundles.

Secure by default: omission is not a grant. An agent is reached via resolved_agent_config; an unknown alias or one with no mcp_bundles receives NO MCP servers. See Self::mcp_servers_for_bundles for how a non-empty bundle list resolves to servers.

pub fn mcp_servers_for_bundles( &self, bundle_aliases: &[String], ) -> Vec<McpServerConfig>

Resolve a set of [mcp_bundles.<alias>] references to the concrete [mcp.servers] entries they grant.

Secure by default: omission is not a grant.

• An empty bundle_aliases grants NO servers (Vec::new()).
• The grant is the union of each referenced bundle’s servers, in first-seen order with duplicates dropped.
• Deny wins: a server name listed in ANY referenced bundle’s exclude is removed from the grant, regardless of which bundle included it.
• An unknown bundle alias grants nothing (it is skipped, not an error) and a server name with no matching [mcp.servers] entry grants nothing. Both fail closed: a misconfiguration narrows access, never widens it.

pub fn shared_workspace_dir(&self) -> PathBuf

<install>/shared/ — directory shared across every agent on this host. Holds skills, skill bundles, knowledge bundles, and any other content not scoped to a single agent’s workspace. Distinct from agent_workspace_dir(alias) (per-agent state) and data_dir (databases + runtime state).

pub fn install_root_dir(&self) -> PathBuf

Install root: <install>/ derived from config_path’s parent. Used to compute <install>/shared/, <install>/agents/, and the skill-bundle directory defaults. Public so consumers (gateway, CLI, SkillsService) share the same anchor.

pub fn agent(&self, agent_alias: &str) -> Option<&AliasedAgentConfig>

Resolve an aliased-agent config by alias. None when the alias isn’t configured; callers should treat this as a config error rather than synthesizing a default.

pub fn resolved_runtime_agent_alias(&self) -> Option<&str>

Resolve the runtime-active agent alias the orchestrator binds channels to. Mirrors the same selection logic as start_channels() in zeroclaw-channels: prefer the migration- synthesized "default" agent, otherwise fall back to the lexicographically-smallest enabled alias. Returns None only when no enabled agent is configured.

Used by per-agent infrastructure (TtsManager, TranscriptionManager) to pick which agent’s tts_provider / transcription_provider drives the manager’s resolved alias. Until the per-channel dispatch refactor lands, the orchestrator runs in single-agent mode, so all manager instances share the same resolved agent.

pub fn resolve_active_storage(&self) -> ActiveStorage<'_>

Resolve the active storage backend for the memory subsystem.

MemoryConfig.backend is a dotted reference (<backend>.<alias>) into Config.storage.<backend>.<alias>. Bare backend names are interpreted as <backend>.default for back-compat.

Returns ActiveStorage::None when no backend is configured, when the backend is "none", or when the dotted alias does not resolve to a configured entry.

pub fn validate_auth(&self) -> Result<()>

Validate the inbound-authentication sections ([oidc.<alias>], [users], [permission_profiles]) on their own.

This is the ONE auth-specific validation boundary (RFC 7141). Full Config::validate calls it, but so does authorization-policy compilation: load_or_init deliberately tolerates a semantically invalid config so an operator can boot to repair it, which means the resolver cannot assume its input was validated. Running exactly these checks again at compile/replace time guarantees that duplicate uids or effective principal ids, invalid issuers, and dangling profile references can never be installed as a serving policy — without making auth activation contingent on every unrelated config field being valid. Keys are sorted so the first error reported is deterministic.

pub fn application_capability(&self, path: &[String]) -> ApplicationCapability

Resolve potential application from generated metadata, defaulting to reload.

Builds this snapshot’s property metadata on every call. To classify several paths against one snapshot, build Config::application_capabilities once and query it per path.

pub fn application_capabilities(&self) -> ApplicationCapabilities

Snapshot this config’s per-property application metadata once, so many paths can be classified without re-deriving prop_fields().

pub fn channel_external_peers( &self, channel_type: &str, alias: &str, ) -> Vec<String>

The resolved peer policy for <channel_type>.<alias>: every granted entry, plus every ignore entry as a PEER_DENY_PREFIX marker.

A [peer_groups.<name>] contributes when its channel field either matches channel_type (type-wide group, applies to every alias of that type) or matches the full dotted "<channel_type>.<alias>" (instance-scoped group, applies to that one alias only).

This is an authorization input, not a list of addresses. Pass it to the channel’s allowlist helpers, which apply denies before grants under that channel’s identity rules. For a reachable account use channel_addressable_peers.

pub fn channel_external_peers_for( &self, channel_types: &[&str], alias: &str, ) -> Vec<String>

channel_external_peers for a channel written more than one way in peer_groups (WeCom WebSocket is both wecom-ws and wecom_ws).

Resolving each spelling separately and concatenating the results loses denies: an ignore under one spelling and a wildcard grant under the other never meet. One pass over every matching group keeps the contract whole.

Grants and denies are both returned as the operator wrote them, and neither is applied here. Deciding a deny at this layer would need an identity comparison, and only the channel knows what identity means: Reddit reads u/alice and alice as one account, WhatsApp reads +1555... and 1555... as one number, Nostr rewrites npub to hex. Subtracting with a generic rule instead resolved the two sides under different semantics, so an ignore the channel would have matched disappeared before the channel ever saw it. The peer list now carries the whole policy to the one place that can apply it consistently.

pub fn channel_addressable_peers( &self, channel_type: &str, alias: &str, ) -> Vec<String>

Peers on <channel_type>.<alias> that name one reachable account.

channel_external_peers answers “who is authorized”, so it carries wildcards and deny markers, neither of which is an address. Callers that need somewhere to send a message want this instead.

pub fn channel_modality_peers( &self, channel_type: &str, alias: &str, modality: OutputModality, ) -> Vec<String>

Peer usernames for <channel_type>.<alias> from every [peer_groups.<name>] whose channel matches (type-wide or dotted) and whose output_modality is modality. Deduped, in group iteration order.

This is the live-resolve counterpart of channel_external_peers, filtered to one output modality. No cache — single source of truth is self.peer_groups.

pub fn channel_voice_peers( &self, channel_type: &str, alias: &str, ) -> Vec<String>

Voice-peer usernames for <channel_type>.<alias> that should always receive TTS voice replies: the channel_modality_peers of output_modality = "voice".

pub fn channel_agent_scope_admins( &self, channel_type: &str, alias: &str, agent_alias: &str, ) -> Vec<String>

Sender usernames authorized to issue /model --agent <model> on <channel_type>.<alias> for agent agent_alias. A [peer_groups.<name>] contributes when its channel matches (type-wide or dotted), its admin_for_agent_scope = true, and its agents list (if non-empty) contains agent_alias. Returns deduped and sorted. Live-resolve against the Config this method is called on — no internal cache. Edits to peer_groups take effect at the next Config::channel_agent_scope_admins call; the orchestrator gate reads through a snapshot of this Config, so operator edits become visible after the runtime context is rebuilt (daemon restart).

pub fn integration_descriptors(&self) -> Vec<IntegrationDescriptor>

Collect the IntegrationDescriptor from every nested config that declares one via #[integration(...)]. Adding a new toggleable integration is one struct-level attribute on the new config + one row in this method. The integrations registry consumes the result without per-vendor branches.

pub fn prop_is_env_overridden(&self, path: &str) -> bool

Returns true if path was populated by a ZEROCLAW_* env-var override at load time. O(1) HashSet lookup; safe to call per row in list-rendering paths (config list, dashboard, quickstart).

pub fn collect_warnings(&self) -> Vec<ValidationWarning>

Collect non-fatal validation warnings — config that loads and validates successfully (validate() returns Ok(())) but will fail at runtime because of a logical inconsistency the schema cannot enforce structurally.

Called by validate() (which emits each warning via tracing::warn! for log visibility) and by the gateway HTTP API (which returns the structured list in PropResponse / PatchResponse so dashboard callers see the same signal the CLI sees on stderr).

Adding a new warning: append a check here, pick a stable code, and document the code in validation_warnings.rs.

pub fn reply_pacing_entries(&self) -> Vec<(String, &dyn HasReplyPacing)>

Walk every channel HashMap that carries reply pacing fields and yield (dotted-path-prefix, &dyn HasReplyPacing) pairs. Used by validation and by anywhere that wants a single source of truth for which channel types participate in pacing.

pub fn validate(&self) -> Result<()>

Validate configuration values that would cause runtime failures.

Called after TOML deserialization and env-override application to catch obviously invalid values early instead of failing at arbitrary runtime points.

pub async fn save(&self) -> Result<()>

Full save. Refuses to overwrite an existing config file unless this value was loaded from that exact file (loaded_from), so a default, programmatically built, or repointed Config cannot replace an operator’s config with a near-empty snapshot. Creating a missing file (first run) always succeeds — a value that never read a file gets exactly one create and must then reload or use force_save(); force_save() is the explicit overwrite path.

pub async fn force_save(&self) -> Result<()>

Same as save(), but skips the loaded-provenance guard. Only for callers that verifiably intend to replace an existing file with a Config that never read it.

Destination-path checks still apply. To replace an existing file, set config_path to the intended path with a nonempty parent directory. A bare filename such as config.toml is refused if its runtime-resolved destination already exists.

Trait Implementations

impl AsRef<Config> for LiveConfigReadGuard<'_>

fn as_ref(&self) -> &Config

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for LiveConfigReadGuard<'_>

type Target = Config

The resulting type after dereferencing.

fn deref(&self) -> &Config

Dereferences the value.