Struct ActAtom 

pub struct ActAtom<T, E>
where
    T: ToolExecutor,
    E: PhaseEffectSink,
{ /* private fields */ }

Atom that executes a batch of tool calls via the [tool_scheduler]

This atom:

1. Emits act.started event
2. Schedules all tool calls (emitting tool.started/completed for each): concurrent by default, serialized within a concurrency class, capped, and with cpu_bound tools offloaded to their own task
3. Handles errors, timeouts, and cancellations gracefully
4. Emits act.completed event
5. Returns comprehensive results for all tools

Tool results are emitted as events and returned in ActResult. Messages are derived from events by the message store.

Implementations

impl<T, E> ActAtom<T, E>

where T: ToolExecutor, E: PhaseEffectSink,

pub fn new(tool_executor: T, event_emitter: E) -> ActAtom<T, E>

Create a new ActAtom with default hooks (ConnectionSetup + ClientSideTool).

pub fn with_file_store( tool_executor: T, event_emitter: E, file_store: Arc<dyn SessionFileSystem>, ) -> ActAtom<T, E>

Create a new ActAtom with a file store for context-aware tools

pub fn with_context_services( self, services: ToolContextServices, ) -> ActAtom<T, E>

Replace the complete runtime-owned service snapshot used for every per-call [ToolContext]. Production hosts should prefer this over assembling individual services on the atom.

pub fn with_hook(self, hook: Box<dyn PostActHook>) -> ActAtom<T, E>

Add a custom post-act hook.

pub fn with_final_post_tool_hook( self, hook: Arc<dyn PostToolExecHook>, ) -> ActAtom<T, E>

Add a runtime-owned final post-tool hook. Hosts use this for portable policies that must run after capability hooks but before the hard output limit.

pub fn with_storage_store( self, store: Arc<dyn SessionStorageStore>, ) -> ActAtom<T, E>

Set the session storage store on this atom

pub fn with_image_store( self, store: Arc<dyn ImageArtifactStore>, ) -> ActAtom<T, E>

Set the image artifact store on this atom

pub fn with_provider_credential_store( self, store: Arc<dyn ProviderCredentialStore>, ) -> ActAtom<T, E>

Set the provider credential store on this atom

pub fn with_utility_llm_service( self, service: Arc<dyn UtilityLlmService>, ) -> ActAtom<T, E>

Set the utility LLM service on this atom.

pub fn with_mcp_invoker(self, invoker: Arc<dyn McpToolInvoker>) -> ActAtom<T, E>

Set the scoped-MCP tool invoker on this atom (guardrails mcp check).

pub fn with_egress_service( self, service: Arc<dyn EgressService>, ) -> ActAtom<T, E>

Set the outbound egress service on this atom.

pub fn with_connection_resolver( self, resolver: Arc<dyn UserConnectionResolver>, ) -> ActAtom<T, E>

Set the user connection resolver on this atom

pub fn with_session_store(self, store: Arc<dyn SessionStore>) -> ActAtom<T, E>

Set session store for context-aware tools.

pub fn with_agent_store(self, store: Arc<dyn AgentStore>) -> ActAtom<T, E>

Set agent store for context-aware tools.

pub fn with_schedule_store( self, store: Arc<dyn SessionScheduleStore>, ) -> ActAtom<T, E>

Set session schedule store for scheduling tools.

pub fn with_subagent_delegate( self, store: Arc<dyn SubagentSessionDelegate>, ) -> ActAtom<T, E>

Set platform store for org-level management tools.

pub fn with_leased_resource_store( self, store: Arc<dyn LeasedResourceStore>, ) -> ActAtom<T, E>

Set leased resource store for lifecycle-managed provider resources.

pub fn with_session_resource_registry( self, registry: Arc<dyn SessionResourceRegistry>, ) -> ActAtom<T, E>

Set session resource registry.

pub fn with_session_task_registry( self, registry: Arc<dyn SessionTaskRegistry>, ) -> ActAtom<T, E>

Add a session task registry passed to tool contexts.

pub fn with_capability_registry( self, registry: CapabilityRegistry, ) -> ActAtom<T, E>

pub fn with_tool_registry(self, registry: Arc<ToolRegistry>) -> ActAtom<T, E>

Set the active built-in tool registry for meta-tools like spawn_background.

pub fn with_post_tool_hooks( self, hooks: Vec<Arc<dyn PostToolExecHook>>, ) -> ActAtom<T, E>

Add capability-contributed post-tool-exec hooks. Callers should pass hooks from the active capabilities for this session, not from the full platform registry.

pub fn with_pre_tool_hooks( self, hooks: Vec<Arc<dyn PreToolUseHook>>, ) -> ActAtom<T, E>

Add capability-contributed pre-tool-use hooks. Pre-hooks fire before each tool call and can mutate or block it; see act_hooks::PreToolUseHook and knowledge/runtime-resources/user-hooks.md.

pub fn with_tool_call_hooks( self, hooks: Vec<Arc<dyn ToolCallHook>>, ) -> ActAtom<T, E>

pub fn with_org_id(self, org_id: TypedId<OrgIdMarker>) -> ActAtom<T, E>

Set org ID for org-scoped operations.

pub fn with_network_access( self, network_access: Option<NetworkAccessList>, ) -> ActAtom<T, E>

Set the merged network access list for URL filtering in tools.

pub fn with_budget_checker( self, checker: Arc<dyn BudgetChecker>, ) -> ActAtom<T, E>

Set the budget checker for the check_budget tool.

pub fn with_payment_authority( self, authority: Arc<dyn PaymentAuthority>, ) -> ActAtom<T, E>

Set the internal payment authority for paid capability tools.

pub fn with_session_creation_authority( self, authority: Arc<dyn SessionCreationAuthority>, ) -> ActAtom<T, E>

Set the authority used to authorize detached peer-session creation.

pub fn with_outbound_tool_rate_limiter( self, limiter: Arc<dyn OutboundToolRateLimiter>, ) -> ActAtom<T, E>

Set the per-org outbound tool-call rate limiter (TM-TOOL-009).

pub fn with_durable_tool_result_store( self, store: Arc<dyn DurableToolResultStore>, ) -> ActAtom<T, E>

Set the durable per-tool-call idempotency store (EVE-530).

pub fn with_subagent_spawn_store( self, store: Arc<dyn SubagentSpawnStore>, ) -> ActAtom<T, E>

Set the durable subagent spawn handle store (EVE-535).

pub fn with_subagent_nesting_policy( self, policy: SubagentNestingPolicy, ) -> ActAtom<T, E>

Set the resolved subagent nesting policy for tool contexts.

pub fn with_reasoning_effort_handle( self, handle: ReasoningEffortHandle, ) -> ActAtom<T, E>

Set the live reasoning-effort handle (EVE-595). When set, each tool’s ToolContext receives a clone so a tool can change the reasoning effort mid-turn for subsequent LLM steps in the same turn.

impl<T, E> ActAtom<T, E>

where T: ToolExecutor + Send + Sync + 'static, E: EventEmitter + Send + Sync + 'static,

pub fn name(&self) -> &'static str

Stable phase name used by logs and durable activity adapters.

pub async fn execute( &self, input: ActInput, ) -> Result<ActResult, AgentLoopError>

Execute one scheduled tool-call batch through injected contracts.