calute.operators.state

Operator runtime state and tool construction.

Provides OperatorState, the central composition root for the operator subsystem. It owns the PTY, browser, plan, user-prompt, and sub-agent managers and exposes a build_tools() method that returns all operator tool callables ready for registration in the Calute runtime.

class calute.operators.state.OperatorState(config: OperatorRuntimeConfig)

Bases: object

Own runtime managers and expose operator tool callables.

Acts as the single entry point for the operator subsystem. On construction it creates all sub-managers (PTY, browser, plan, user-prompt) and defers sub-agent manager creation until the runtime is attached via attach_runtime().

config

The OperatorRuntimeConfig governing this operator instance.

pty_manager

Manages persistent PTY shell sessions.

browser_manager

Manages Playwright browser pages.

plan_manager

Manages the structured execution plan.

user_prompt_manager

Manages user clarification questions.

calute

Reference to the parent Calute instance, set by attach_runtime().

runtime_state

Reference to the shared runtime state, set by attach_runtime().

subagent_manager

Manages spawned background sub-agents. None until attach_runtime() is called.

attach_runtime(calute: Any, runtime_state: Any) → None

Bind the operator runtime to a concrete Calute instance.

This must be called before any sub-agent tools can be used. It stores references to the parent runtime and creates the SpawnedAgentManager.

Parameters

• calute – The parent Calute instance.

• runtime_state – The shared runtime state object that holds policy, configuration, and audit emitter references.

build_tools() → list[Callable]

Build and cache the operator tool functions.

On first call, instantiates all operator tool closures and caches the list. Subsequent calls return a shallow copy of the cached list.

Returns

A list of callable operator tool functions, each decorated with operator_tool() metadata.

create_reinvoke_message(result: Any) → calute.types.messages.UserMessage | None

Convert special operator tool results into a reinvocation message.

When the tool result is an ImageInspectionResult, a multimodal UserMessage is constructed containing both a text summary and the image data, enabling the LLM to inspect the image in the next turn.

Parameters

result – The raw tool result to inspect.

Returns

A UserMessage with text and image chunks when the result is an ImageInspectionResult, or None for all other result types.

list_operator_state() → dict[str, Any]

Return summaries for operator-managed runtime state.

Aggregates status from every sub-manager into a single dictionary suitable for TUI display or API responses.

Returns

• power_tools_enabled: Current power-tools flag.

• pty_sessions: List of PTY session summaries.

• browser_pages: List of tracked browser page summaries.

• spawned_agents: List of sub-agent handle snapshots.

• plan: Current plan state dictionary.

• pending_user_prompt: Pending question dictionary, or None.

Return type

A dictionary containing

set_power_tools_enabled(enabled: bool) → None

Update the power-tools flag and effective optional-tools policy.

When enabling, removes high-power tools from the policy engine’s optional_tools set so they become available. When disabling, adds them back so the policy engine blocks them.

Parameters

enabled – True to activate high-power tools, False to deactivate them.

summarize_result(result: Any) → tuple[Any, dict[str, Any]]

Return a tool-message-safe result plus serialisable metadata.

For ImageInspectionResult, the heavy PIL image is replaced by a compact text summary in the first element, and the metadata dictionary contains all scalar fields.

Parameters

result – The raw tool result to summarise.

Returns

A two-tuple of (safe_result, metadata) where safe_result is suitable for inclusion in a tool-call message and metadata is a JSON-serialisable dictionary (empty for non-image results).