calute.operators.subagents

Background sub-agent manager for operator tooling.

Provides SpawnedAgentManager, which creates, tracks, and orchestrates background Calute sub-agent handles. Each handle wraps a cloned Agent and can be sent work, waited on, interrupted, resumed, or closed independently.

class calute.operators.subagents.SpawnedAgentHandle(handle_id: str, agent: ~calute.types.agent_types.Agent, source_agent_id: str | None, status: str = 'idle', created_at: str = <factory>, updated_at: str = <factory>, prompt_profile: str = 'minimal', last_input: str | None = None, last_output: str | None = None, error: str | None = None, queue: list[str] = <factory>, task: _asyncio.Task | None = None, closed: bool = False)

Bases: object

State for a spawned background agent.

Each handle tracks the lifecycle of one sub-agent, including its current status, message queue, last input/output, and the asyncio.Task running its work.

handle_id

Unique identifier for this handle, used in all operator tool calls that reference the sub-agent.

Type

str

agent

The cloned Agent instance that processes work for this handle.

Type

calute.types.agent_types.Agent

source_agent_id

Identifier of the parent agent that this handle was spawned from. None when unknown.

Type

str | None

status

Current lifecycle status. One of "idle", "running", "completed", "error", "interrupted", "cancelled", or "closed".

Type

str

created_at

ISO 8601 timestamp of when the handle was created.

Type

str

updated_at

ISO 8601 timestamp of the most recent state change.

Type

str

prompt_profile

Name of the prompt profile applied to the sub-agent.

Type

str

last_input

The most recent message sent to this handle.

Type

str | None

last_output

The most recent response produced by the sub-agent.

Type

str | None

error

Error message string if the last run failed.

Type

str | None

queue

FIFO queue of messages waiting to be processed after the current task finishes.

Type

list[str]

task

The asyncio.Task running the current work, or None when idle.

Type

_asyncio.Task | None

closed

Whether the handle has been explicitly closed.

Type

bool

agent: Agent

closed: bool = False

created_at: str

error: str | None = None

handle_id: str

last_input: str | None = None

last_output: str | None = None

prompt_profile: str = 'minimal'

queue: list[str]

snapshot() → dict[str, Any]

Return a serialisable handle summary.

Produces a dictionary suitable for JSON serialisation and tool result payloads, omitting the heavy agent and task objects.

Returns

A dictionary with all scalar state fields plus derived values like queue_size and queued_preview.

source_agent_id: str | None

status: str = 'idle'

task: _asyncio.Task | None = None

updated_at: str

class calute.operators.subagents.SpawnedAgentManager(calute: Any, runtime_state: Any)

Bases: object

Manage background Calute sub-agent handles.

Maintains a registry of SpawnedAgentHandle instances and provides methods to spawn new handles, send them work, wait for completion, resume, and close them.

_calute

Reference to the parent Calute instance used for creating responses on behalf of sub-agents.

_runtime_state

Reference to the shared runtime state, used for agent override configuration.

_handles

Internal mapping from handle_id to the corresponding SpawnedAgentHandle.

close(handle_id: str) → dict[str, Any]

Close a spawned-agent handle and cancel any running task.

Marks the handle as closed, cancels its active task if one exists, and records the previous status in the returned snapshot.

Parameters

handle_id – Identifier of the handle to close.

Returns

The final handle snapshot dictionary with an additional previous_status key indicating the status before closure.

Raises

ValueError – If the handle ID is not found.

list_handles() → list[dict[str, Any]]

Return summaries for all spawned agent handles.

Returns

A list of snapshot dictionaries, one per handle.

resume(handle_id: str) → dict[str, Any]

Re-open a closed spawned-agent handle.

Clears the closed flag and resets the status to "idle" if it was "closed".

Parameters

handle_id – Identifier of the handle to resume.

Returns

The updated handle snapshot dictionary.

Raises

ValueError – If the handle ID is not found.

async send_input(handle_id: str | None = None, *, message: str | None = None, task_description: str | None = None, interrupt: bool = False) → dict[str, Any]

Queue or interrupt a spawned agent task.

If the handle has a running task and interrupt is False, the message is appended to the handle’s FIFO queue. If interrupt is True, the running task is cancelled before the new message is dispatched.

Parameters

• handle_id – Identifier of the target handle. When omitted, the most recently updated non-closed handle is used.

• message – Instruction text to deliver to the sub-agent.

• task_description – Backward-compatible alias for message used by older callers.

• interrupt – When True, cancel any running task and process this message immediately.

Returns

The updated handle snapshot dictionary.

Raises

ValueError – If the handle is not found or has been closed.

async spawn(*, message: str | None = None, task_description: str | None = None, agent_id: str | None = None, prompt_profile: str | None = None, nickname: str | None = None) → dict[str, Any]

Create a background handle and optionally start the first task.

Clones the source agent, registers the handle, configures the prompt profile override, and optionally queues the initial message for immediate processing.

Parameters

• message – Optional initial instruction to send to the sub-agent immediately after spawning.

• task_description – Backward-compatible alias for message used by older callers.

• agent_id – Registered agent ID to clone. When None, the orchestrator’s current/default agent is used.

• prompt_profile – Prompt profile name override. Defaults to PromptProfile.MINIMAL.

• nickname – Human-readable label for the handle. Also used as the handle_id when provided.

Returns

The snapshot dictionary of the newly created handle.

Raises

KeyError – If agent_id does not match a registered agent.

async wait(targets: list[str], timeout_ms: int = 30000) → dict[str, Any]

Wait for the given spawned agent handles to finish or timeout.

Collects the asyncio.Task objects for the specified handles and waits for them using asyncio.wait().

Parameters

• targets – List of handle IDs to wait on.

• timeout_ms – Maximum wait time in milliseconds. Handles whose tasks are still running after this period appear in the pending list.

Returns

• completed: Snapshots of handles whose tasks finished (or that had no running task).

• pending: Snapshots of handles still running at timeout.

Return type

A dictionary with two keys

Raises

ValueError – If any target handle ID is not found.