calute.runtime.features

calute.runtime.features#

Runtime feature integration for Calute.

This module owns the opt-in OpenClaw-style runtime capability layer: - plugin and skill discovery - hook registration - tool policy configuration - loop detection configuration - sandbox routing configuration - prompt enrichment helpers

class calute.runtime.features.AgentRuntimeOverrides(policy: calute.security.policy.ToolPolicy | None = None, loop_detection: calute.runtime.loop_detection.LoopDetectionConfig | None = None, sandbox: calute.security.sandbox.SandboxConfig | None = None, enabled_skills: list[str] | None = None, guardrails: list[str] | None = None, prompt_profile: calute.runtime.profiles.PromptProfile | str | None = None)[source]#

Bases: object

Per-agent runtime feature overrides.

Allows individual agents to deviate from global runtime settings. A field set to None means “inherit the global runtime setting”. Empty lists explicitly clear list-valued globals (e.g. setting guardrails=[] removes all guardrails for that agent even when the global config has guardrails defined).

policy#

Agent-specific tool policy. None inherits the global policy.

Type: calute.security.policy.ToolPolicy | None

loop_detection#

Agent-specific loop detection configuration. None inherits the global loop detection config.

Type: calute.runtime.loop_detection.LoopDetectionConfig | None

sandbox#

Agent-specific sandbox configuration. None inherits the global sandbox config.

Type: calute.security.sandbox.SandboxConfig | None

enabled_skills#

List of skill names enabled for the agent. None inherits the global enabled skills.

Type: list[str] | None

guardrails#

List of guardrail rule strings for the agent. None inherits the global guardrails.

Type: list[str] | None

prompt_profile#

Prompt profile name or enum for system prompt verbosity. None inherits the global default.

Type: calute.runtime.profiles.PromptProfile | str | None

enabled_skills: list[str] | None = None#

guardrails: list[str] | None = None#

loop_detection: calute.runtime.loop_detection.LoopDetectionConfig | None = None#

policy: calute.security.policy.ToolPolicy | None = None#

prompt_profile: calute.runtime.profiles.PromptProfile | str | None = None#

sandbox: calute.security.sandbox.SandboxConfig | None = None#

class calute.runtime.features.RuntimeFeaturesConfig(enabled: bool = False, workspace_root: str | None = None, plugin_dirs: list[str] = <factory>, skill_dirs: list[str] = <factory>, discover_conventional_extensions: bool = True, guardrails: list[str] = <factory>, policy: calute.security.policy.ToolPolicy | None = None, loop_detection: calute.runtime.loop_detection.LoopDetectionConfig | None = None, sandbox: calute.security.sandbox.SandboxConfig | None = None, enabled_skills: list[str] = <factory>, default_prompt_profile: calute.runtime.profiles.PromptProfile | str | None = None, audit_collector: calute.audit.collector.AuditCollector | None = None, session_store: calute.session.store.SessionStore | None = None, operator: calute.operators.config.OperatorRuntimeConfig | None = None, agent_overrides: dict[str, calute.runtime.features.AgentRuntimeOverrides] = <factory>)[source]#

Bases: object

Public configuration for Calute runtime features.

This is the top-level configuration object passed by the user to enable and customise the runtime feature layer. All fields have safe defaults, so the minimal configuration is simply RuntimeFeaturesConfig(enabled=True).

enabled#

Master switch. When False, the entire runtime feature layer is a no-op.

Type: bool

workspace_root#

Explicit workspace root directory. When None, the current working directory is used.

Type: str | None

plugin_dirs#

List of directory paths to scan for plugins.

Type: list[str]

skill_dirs#

List of directory paths to scan for skills.

Type: list[str]

discover_conventional_extensions#

When True, also look for plugins/ and skills/ directories under the workspace root using conventional layout conventions.

Type: bool

guardrails#

Global list of guardrail rule strings injected into every agent’s system prompt.

Type: list[str]

policy#

Global tool policy applied to all agents unless overridden per-agent.

Type: calute.security.policy.ToolPolicy | None

loop_detection#

Global loop detection configuration. None disables loop detection.

Type: calute.runtime.loop_detection.LoopDetectionConfig | None

sandbox#

Global sandbox configuration. None disables sandboxing.

Type: calute.security.sandbox.SandboxConfig | None

enabled_skills#

Global list of skill names to enable for all agents.

Type: list[str]

default_prompt_profile#

Default prompt profile name or enum controlling system prompt verbosity.

Type: calute.runtime.profiles.PromptProfile | str | None

audit_collector#

Optional audit collector for emitting audit events during tool execution.

Type: calute.audit.collector.AuditCollector | None

session_store#

Optional session store backend for persisting agent session state.

Type: calute.session.store.SessionStore | None

operator#

Optional runtime operator configuration for power tools.

Type: calute.operators.config.OperatorRuntimeConfig | None

agent_overrides#

Mapping from agent ID to per-agent runtime overrides.

Type: dict[str, calute.runtime.features.AgentRuntimeOverrides]

agent_overrides: dict[str, calute.runtime.features.AgentRuntimeOverrides]#

audit_collector: calute.audit.collector.AuditCollector | None = None#

default_prompt_profile: calute.runtime.profiles.PromptProfile | str | None = None#

discover_conventional_extensions: bool = True#

enabled: bool = False#

enabled_skills: list[str]#

guardrails: list[str]#

loop_detection: calute.runtime.loop_detection.LoopDetectionConfig | None = None#

operator: calute.operators.config.OperatorRuntimeConfig | None = None#

plugin_dirs: list[str]#

policy: calute.security.policy.ToolPolicy | None = None#

sandbox: calute.security.sandbox.SandboxConfig | None = None#

session_store: calute.session.store.SessionStore | None = None#

skill_dirs: list[str]#

workspace_root: str | None = None#

class calute.runtime.features.RuntimeFeaturesState(config: ~calute.runtime.features.RuntimeFeaturesConfig, plugin_registry: ~calute.extensions.plugins.PluginRegistry = <factory>, skill_registry: ~calute.extensions.skills.SkillRegistry = <factory>, hook_runner: ~calute.extensions.hooks.HookRunner = <factory>, sandbox_backend: calute.security.sandbox.SandboxBackend | None = None, operator_state: calute.operators.state.OperatorState | None = None)[source]#

Bases: object

Internal state holder for runtime feature integration.

Created from a RuntimeFeaturesConfig and manages all runtime sub-systems: plugin/skill discovery, hook registration, policy engine, sandbox routing, audit emission, session management, and prompt context building. Intended to be instantiated once per Calute runtime lifecycle.

config#

The user-provided runtime features configuration.

Type: calute.runtime.features.RuntimeFeaturesConfig

plugin_registry#

Registry of discovered plugins.

Type: calute.extensions.plugins.PluginRegistry

skill_registry#

Registry of discovered skills.

Type: calute.extensions.skills.SkillRegistry

hook_runner#

Hook runner for plugin-contributed callbacks.

Type: calute.extensions.hooks.HookRunner

sandbox_backend#

Optional instantiated sandbox execution backend.

Type: calute.security.sandbox.SandboxBackend | None

operator_state#

Optional runtime operator state for power tools.

Type: calute.operators.state.OperatorState | None

Build the enriched system prompt prefix for a specific agent.

Resolves all agent-specific overrides (sandbox, guardrails, enabled skills, prompt profile) and delegates to the PromptContextBuilder to assemble the full prefix.

Parameters

agent_id – The agent identifier used to resolve per-agent overrides.
tool_names – Optional list of tool names available to the agent in this run.
profile – Optional prompt profile override. When None, the agent’s resolved prompt profile is used.

Returns

The assembled system prompt prefix string.

config: RuntimeFeaturesConfig#

create_loop_detector(agent_id: str | None) → calute.runtime.loop_detection.LoopDetector | None[source]#

Create a LoopDetector for an agent.

Resolves the effective loop detection config for the agent and instantiates a fresh LoopDetector. Returns None when loop detection is not configured.

Parameters: agent_id – The agent identifier used to resolve the effective loop detection configuration.
Returns: A new LoopDetector instance, or None if no loop detection config is available.

discover_extensions() → None[source]#

Discover configured and conventional plugins/skills, then validate dependencies.

Scans all configured plugin and skill directories (including conventional plugins/ and skills/ directories under the workspace root when discover_conventional_extensions is enabled). After discovery, validates that all plugin and skill dependency requirements are satisfied.

Raises: ValueError – If any plugin or skill has unmet dependencies.

get_agent_overrides(agent_id: str | None) → AgentRuntimeOverrides[source]#

Return per-agent runtime overrides, or an empty default if not configured.

Parameters: agent_id – The agent identifier to look up. When None or not found in the overrides map, returns a default AgentRuntimeOverrides with all fields as None.
Returns: The AgentRuntimeOverrides for the given agent, or a default instance.

get_enabled_skill_names(agent_id: str | None) → list[str][source]#

Return the list of enabled skill names for an agent.

Checks for per-agent overrides first; falls back to the global enabled skills list from the configuration.

Parameters: agent_id – The agent identifier to look up overrides for.
Returns: The list of skill name strings enabled for this agent.

get_enabled_skills(agent_id: str | None) → list[calute.extensions.skills.Skill][source]#

Return resolved Skill objects for all enabled skill names for an agent.

Looks up each enabled skill name in the skill registry. Skills that were configured but not discovered are logged as warnings and omitted from the result.

Parameters: agent_id – The agent identifier used to determine which skills are enabled.
Returns: List of resolved Skill objects that are both enabled and discovered.

get_guardrails(agent_id: str | None) → list[str][source]#

Return the effective guardrail list for an agent.

Checks for per-agent overrides first; falls back to the global guardrail list from the configuration.

Parameters: agent_id – The agent identifier to look up overrides for.
Returns: The list of guardrail rule strings applicable to this agent.

get_loop_detection_config(agent_id: str | None) → calute.runtime.loop_detection.LoopDetectionConfig | None[source]#

Return the effective loop detection config for an agent.

Checks for per-agent overrides first; falls back to the global loop detection configuration.

Parameters: agent_id – The agent identifier to look up overrides for.
Returns: The LoopDetectionConfig for this agent, or None if loop detection is not configured.

get_prompt_profile(agent_id: str | None) → calute.runtime.profiles.PromptProfile | calute.runtime.profiles.PromptProfileConfig | str | None[source]#

Resolve the prompt profile for an agent.

Checks for a per-agent prompt profile override first; falls back to the global default prompt profile from the configuration.

Parameters: agent_id – The agent identifier to look up overrides for.
Returns: The prompt profile specification for this agent, or None if no profile is configured globally or per-agent.

get_sandbox_config(agent_id: str | None) → calute.security.sandbox.SandboxConfig | None[source]#

Return the effective sandbox config for an agent.

Checks for per-agent overrides first; falls back to the global sandbox configuration.

Parameters: agent_id – The agent identifier to look up overrides for.
Returns: The SandboxConfig for this agent, or None if sandboxing is not configured.

get_sandbox_router(agent_id: str | None) → calute.security.sandbox.SandboxRouter | None[source]#

Return a cached-or-new SandboxRouter for an agent.

Maintains an internal cache of SandboxRouter instances keyed by agent ID. A cached router is reused when the config and backend match; otherwise a new router is created and cached.

Parameters: agent_id – The agent identifier used to resolve sandbox config and cache the router.
Returns: A SandboxRouter instance for the agent, or None if sandbox is not configured.

hook_runner: HookRunner#

merge_operator_tools(agent: Agent) → None[source]#

Attach runtime operator tools to an agent if enabled.

If the operator state is active, builds the operator tool set and appends each allowed tool to the agent’s functions list. Silently skips tools that are already present or not in the operator’s allowed tool set.

Parameters: agent – The agent whose functions list will be extended with operator tools.

merge_plugin_tools(agent: Agent) → None[source]#

Attach plugin-contributed tools to an agent’s function list.

Iterates over all tools registered by discovered plugins and appends them to the agent’s functions list. Raises an error if any plugin tool name collides with an existing function.

Parameters: agent – The agent whose functions list will be extended with plugin tools.
Raises: ValueError – If a plugin tool name conflicts with an existing function already registered on the agent.

operator_state: calute.operators.state.OperatorState | None = None#

plugin_registry: PluginRegistry#

sandbox_backend: calute.security.sandbox.SandboxBackend | None = None#

skill_registry: SkillRegistry#

calute.runtime.features

Contents

calute.runtime.features#