calute.runtime.context

Contents

calute.runtime.context#

Runtime context assembly for Calute system prompts.

Builds rich system prompt sections that include: - Runtime/environment context (date, platform, version) - Workspace context (working directory, project info) - Sandbox status - Skills index - Tooling summary - Safety/guardrail reminders - Bootstrap file injections from hooks

Supports PromptProfile to control verbosity (full, compact, minimal, none) for sub-agent delegation.

class calute.runtime.context.PromptContext(runtime_section: str = '', workspace_section: str = '', datetime_section: str = '', reasoning_section: str = '', sandbox_section: str = '', skills_section: str = '', enabled_skills_section: str = '', tools_section: str = '', guardrails_section: str = '', bootstrap_section: str = '')[source]#

Bases: object

Assembled context sections for system prompt enrichment.

Each field holds a pre-rendered string for one logical section of the system prompt. Fields that are empty ("") indicate that the corresponding section was disabled by the active PromptProfileConfig.

runtime_section#

Platform, Python version, and Calute version block.

Type

str

workspace_section#

Working directory and project name block.

Type

str

datetime_section#

Current local date/time and timezone block.

Type

str

reasoning_section#

Profile name and reasoning guidance block.

Type

str

sandbox_section#

Sandbox mode and tool routing block.

Type

str

skills_section#

Index of all discovered skills from the registry.

Type

str

enabled_skills_section#

Full instruction text for skills that are currently enabled for the agent.

Type

str

tools_section#

List of available tool names for this run.

Type

str

guardrails_section#

Active guardrail rules for safety enforcement.

Type

str

bootstrap_section#

Injected project/bootstrap content from hook runners.

Type

str

bootstrap_section: str = ''#
datetime_section: str = ''#
enabled_skills_section: str = ''#
guardrails_section: str = ''#
reasoning_section: str = ''#
runtime_section: str = ''#
sandbox_section: str = ''#
skills_section: str = ''#
tools_section: str = ''#
workspace_section: str = ''#
class calute.runtime.context.PromptContextBuilder(skill_registry: SkillRegistry | None = None, plugin_registry: PluginRegistry | None = None, hook_runner: HookRunner | None = None, sandbox_config: SandboxConfig | None = None, guardrails: list[str] | None = None, profile: PromptProfile | PromptProfileConfig | None = None, workspace_root: str | None = None)[source]#

Bases: object

Builds enriched prompt context from runtime state.

Orchestrates the construction of all system-prompt sections that describe the runtime environment, available tools, skills, sandbox configuration, guardrails, and workspace context. The builder supports multiple verbosity levels via PromptProfile and can produce agent-specific overrides.

skill_registry#

Registry of discovered skills.

plugin_registry#

Registry of discovered plugins.

hook_runner#

Hook runner for bootstrap file injection.

sandbox_config#

Default sandbox configuration.

guardrails#

Default list of guardrail rule strings.

default_profile_config#

Resolved default prompt profile config.

workspace_root#

Optional explicit workspace directory path.

Example

>>> builder = PromptContextBuilder(skill_registry=my_registry)
>>> ctx = builder.build(agent_id="coder")
>>> print(ctx.runtime_section)
assemble_system_prompt_prefix(agent_id: str | None = None, tool_names: list[str] | None = None, sandbox_config: SandboxConfig | None = None, guardrails: list[str] | None = None, enabled_skills: list[Skill] | None = None, profile: PromptProfile | PromptProfileConfig | str | None = None) → str[source]#

Build the full enriched prefix for a system prompt.

Assembles identity, tooling, safety, skills, workspace, sandbox, runtime, execution policy, and output style blocks into a single string that should be prepended to the agent’s instructions in the system message.

For the PromptProfile.NONE profile, returns only a single identity line with no runtime context sections.

Parameters

  • agent_id – Optional agent identifier for hook dispatch and per-agent customisation.

  • tool_names – Optional list of tool names available to the agent.

  • sandbox_config – Optional sandbox configuration override.

  • guardrails – Optional guardrail list override.

  • enabled_skills – Optional list of enabled Skill objects.

  • profile – Optional prompt profile override. When None, the builder’s default profile is used (which itself defaults to PromptProfile.FULL).

Returns

The assembled system prompt prefix string with all applicable blocks joined by double newlines.

build(agent_id: str | None = None, tool_names: list[str] | None = None, profile: calute.runtime.profiles.PromptProfile | calute.runtime.profiles.PromptProfileConfig | str | None = None) → PromptContext[source]#

Build all prompt context sections using default overrides.

Convenience wrapper around build_with_overrides() that forwards the most common parameters.

Parameters

  • agent_id – Optional agent identifier for bootstrap hook dispatch and per-agent customisation.

  • tool_names – Optional list of tool names available to the agent in this run.

  • profile – Optional prompt profile override. When None, the builder’s default profile is used.

Returns

A PromptContext with all applicable sections populated.

build_compact_prefix(agent_id: str | None = None, tool_names: list[str] | None = None, sandbox_config: SandboxConfig | None = None, guardrails: list[str] | None = None, enabled_skills: list[Skill] | None = None) → str[source]#

Build a system prompt prefix using the COMPACT profile.

The compact profile drops workspace/bootstrap sections and caps skill instructions and tool lists, yielding a shorter prefix suitable for sub-agent delegation.

Parameters

  • agent_id – Optional agent identifier for hook dispatch.

  • tool_names – Optional list of available tool names.

  • sandbox_config – Optional sandbox configuration override.

  • guardrails – Optional guardrail list override.

  • enabled_skills – Optional list of enabled Skill objects.

Returns

A compact system prompt prefix string.

build_minimal_prefix(agent_id: str | None = None, tool_names: list[str] | None = None, sandbox_config: SandboxConfig | None = None, guardrails: list[str] | None = None, enabled_skills: list[Skill] | None = None) → str[source]#

Build a system prompt prefix using the MINIMAL profile.

The minimal profile includes only sandbox info, guardrails, and a short tool list (capped at 10 entries). All other sections are omitted, producing the smallest useful prefix for internal delegation.

Parameters

  • agent_id – Optional agent identifier for hook dispatch.

  • tool_names – Optional list of available tool names.

  • sandbox_config – Optional sandbox configuration override.

  • guardrails – Optional guardrail list override.

  • enabled_skills – Optional list of enabled Skill objects.

Returns

A minimal system prompt prefix string.

build_none_prefix() → str[source]#

Build an OpenClaw-style identity-only system prompt prefix.

Returns only the bare identity line with no runtime sections, useful when the caller supplies all context externally.

Returns

A single-line identity string for the system prompt.

build_with_overrides(agent_id: str | None = None, tool_names: list[str] | None = None, sandbox_config: SandboxConfig | None = None, guardrails: list[str] | None = None, enabled_skills: list[Skill] | None = None, profile: PromptProfile | PromptProfileConfig | str | None = None) → PromptContext[source]#

Build all prompt context sections with agent-specific overrides.

This is the full-control entry point. Each parameter can override the builder’s defaults for a single invocation, enabling per-agent customisation without mutating shared state.

Parameters

  • agent_id – Optional agent identifier forwarded to bootstrap hooks.

  • tool_names – Optional list of tool names available to the agent.

  • sandbox_config – Optional per-agent sandbox configuration that overrides the builder’s default.

  • guardrails – Optional per-agent guardrail list that overrides the builder’s default.

  • enabled_skills – Optional list of resolved Skill objects whose instruction text should be injected.

  • profile – Optional prompt profile override. Accepts a PromptProfile enum, a string name, or a PromptProfileConfig. When None, the builder’s default profile is used.

Returns

A PromptContext with each section populated (or left empty) according to the resolved profile configuration.

class calute.runtime.context.RuntimeInfo(timestamp: str = '', timezone: str = '', platform: str = '', python_version: str = '', calute_version: str = '', working_directory: str = '', workspace_name: str = '')[source]#

Bases: object

Snapshot of runtime environment information.

Captures a point-in-time view of the host environment including timestamps, platform details, Python and Calute versions, and the current workspace directory. Used by PromptContextBuilder to populate runtime and workspace prompt sections.

timestamp#

ISO 8601 formatted local timestamp with timezone offset.

Type

str

timezone#

Name of the local timezone (e.g. "UTC", "PST").

Type

str

platform#

Operating system name and release (e.g. "Darwin 23.4.0").

Type

str

python_version#

Python interpreter version string (e.g. "3.12.3").

Type

str

calute_version#

Installed Calute package version.

Type

str

working_directory#

Absolute path to the resolved workspace directory.

Type

str

workspace_name#

Base name of the workspace directory.

Type

str

calute_version: str = ''#
classmethod capture(workspace_root: str | None = None) → RuntimeInfo[source]#

Capture a snapshot of the current runtime environment.

Reads the local clock, platform details, Python version, and the installed Calute version to produce a frozen RuntimeInfo instance.

Parameters

workspace_root – Optional explicit workspace directory. When None, falls back to the current working directory.

Returns

A new RuntimeInfo populated with current environment data.

platform: str = ''#
python_version: str = ''#
timestamp: str = ''#
timezone: str = ''#
working_directory: str = ''#
workspace_name: str = ''#
Contents