Struct ActorChildRunner 

pub struct ActorChildRunner { /* private fields */ }

Spawns and drives a child session as an independent actor: a bamboo-subagent worker process.

Implementations

impl ActorChildRunner

pub fn new( agent_id: String, worker_bin: PathBuf, worker_args: Vec<String>, fabric_dir: PathBuf, executor: ExecutorSpec, credentials: Vec<ScopedCredential>, default_provider: String, max_concurrent: usize, ) -> Self

pub fn with_live_provider_config(self, config: Arc<RwLock<Config>>) -> Self

pub fn with_max_spawn_depth(self, max_spawn_depth: u32) -> Self

pub fn with_approval_registry(self, registry: SharedApprovalRegistry) -> Self

pub fn with_permission_config(self, config: Arc<PermissionConfig>) -> Self

pub fn with_bus(self, bus: Option<BusEndpoint>) -> Self

Run children over the mailbox bus (the unified actor+mailbox transport). When set, local children dial this bus and are driven by mailbox id; when unset they use the legacy direct-WS path. The server passes its in-process broker here (subagents.broker); tests without a broker leave it unset.

pub fn with_approval_decider( self, decider: Arc<dyn ChildApprovalDecider>, ) -> Self

Wire the host-side decider for child gated-tool approval requests (Phase 2). Without this the host fail-closed DENYs every request.

pub fn with_approval_reviewer( self, reviewer: Arc<dyn ChildApprovalReviewer>, ) -> Self

pub fn with_codex_run_tokens( self, authority: Option<Arc<dyn CodexRunTokenAuthority>>, ) -> Self

pub fn with_remote_placements( self, placements: HashMap<String, ResolvedRemotePlacement>, ) -> Self

Pin specific sub-agent roles to remote resident workers (#193). The map is keyed by role (subagent_type); a child whose role is present connects over wss:// to the resolved endpoint instead of spawning a local subprocess. Default (empty) keeps every role on the local path — exactly today’s behavior.

pub fn with_schedulable_placements( self, placements: HashMap<String, ResolvedSchedulablePlacement>, ) -> Self

Route specific sub-agent roles to a registry-SCHEDULED worker (#181, P2b). The map is keyed by role (subagent_type); a child whose role is present (and NOT already pinned by remote_placements, which takes precedence) is run on a live worker discovered from the registry instead of a local subprocess. Default (empty) keeps every role on the local path.

Trait Implementations

impl ExternalChildRunner for ActorChildRunner

fn validate_required_child_context_route<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 Session, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

A narrow, pre-persistence compatibility check on the actual registered runner. Unknown/custom routes fail closed for required one-shot packets.

fn should_handle<'life0, 'life1, 'async_trait>( &'life0 self, session: &'life1 Session, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Returns true if this runner should handle the given child session.

fn set_escalation_bridge(&self, bridge: Option<HostBridge>)

Bind this runner’s per-run escalation host bridge (#68). A nested worker’s run() installs its OWN host bridge here so the runner can hand it to each grandchild’s drive() AT SPAWN time (captured into the drive task, not read later), letting the grandchild re-proxy a non-bypass approval request UP to its parent run for its whole lifetime — even when it outlives the run that spawned it. Default no-op for runners that don’t escalate (e.g. A2A).

fn set_session_inbox_runtime(&self, binding: Option<SessionInboxRuntimeBinding>)

Bind the owning runtime’s canonical SessionInbox resources. Actor runners use this to bridge active local/remote/warm workers without a process-global live-session registry.

fn set_actor_directory_store(&self, store: Option<Arc<SessionStoreV2>>)

Optional actual host Store for the local zero-tool named-profile route. This does not enable owned Inbox claims or grant authority to custom runners.

fn set_canonical_subagent_tool(&self, tool: Option<Arc<dyn Tool>>)

Bind the application-owned logical SubAgent tool after its canonical scheduler/adapter exist. Actor runners use it only for fenced child RPCs.

fn set_ticket_service(&self, service: Option<Arc<TicketService>>)

Opt-in, host-owned scope authority. It is never copied into the Worker.

fn set_actor_event_observer( &self, observer: Option<Arc<dyn ActorEventObserver>>, )

Optional host-owned, redacted canonical Actor event observer.

fn prepare_durable_child_delivery<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 Session, activation_run_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<bool, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Persist a Host-only broker receipt before the final Child checkpoint. Ok(true) selects the append-safe final checkpoint. An unprepared broker terminal must never be ACKed after a merely ordinary save.

fn commit_durable_child_delivery<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 Session, activation_run_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Commit and read back any Host-only proof required for this terminal delivery after the final Child Session save. Failure (including timeout) prevents a committed completion source and successful runner finalization. When the source is pending, publish its terminal status and seal with an exact-snapshot canonical write before returning; the SDK verifies readback. Legacy/default runners need no separate proof and retain save-only behavior.

fn confirm_durable_child_delivery<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 Session, activation_run_id: &'life2 str, save_succeeded: bool, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

ACK transport delivery only after the final Child save and required Host proof commit both succeed. The exact Child birth and activation run identify the pending receipt; failed commitment leaves it unacknowledged. ACK delivery failure does not invalidate an already-proven completion.

fn execute_external_child<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session: &'life1 mut Session, job: &'life2 SpawnJob, event_tx: Sender<AgentEvent>, cancel_token: CancellationToken, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Execute the child session using an external runtime.

fn supports_native_ticket_budget(&self) -> bool

Capability of the actually assembled backend, independent of hot config. Only the in-process backend consumes canonical Ticket request ceilings.

fn set_local_child_skill_factory( &self, _factory: Option<Arc<dyn LocalChildSkillFactory>>, )

App catalog/read services for the owned local backend only. Process and remote adapters deliberately retain the default no-op.

fn set_local_task_runtime(&self, _runtime: Option<LocalTaskRuntime>)

Bind the Host’s in-process execution resources. Process/remote adapters deliberately ignore this capability and retain their existing mode.

fn prepare_child_execution<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session: &'life1 Session, _run_id: &'life2 str, _cancel: CancellationToken, ) -> Pin<Box<dyn Future<Output = Result<Option<Arc<dyn RuntimeSessionPersistence>>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Acquire this backend’s exact durable writer before the canonical running checkpoint. A default writer is never substituted after claim.

fn abandon_child_execution<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session: &'life1 Session, _run_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Roll back a prepared execution whose initial canonical checkpoint failed. Local implementations must close the launch gate and prove resource drain.

fn quarantine_child_execution(&self, _session: &Session, _run_id: &str)

Record a setup panic without inventing a successful resource stop.

fn track_child_task( &self, _session_id: &str, _run_id: &str, handle: JoinHandle<()>, ) -> Option<JoinHandle<()>>

Keep a local coordinator handle owned until it really exits. Returning the handle leaves supervision to an outer composite or legacy caller.

fn finish_child_execution<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session: &'life1 Session, _run_id: &'life2 str, _history_committed: bool, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

End the exact backend writer after terminal persistence and the history barrier, before publishing runner replacement eligibility.

fn shutdown<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Stop admission, request cancellation, and await owned task/resource completion. This is called by the Host’s graceful shutdown path.