Struct SubAgentManager 

pub struct SubAgentManager { /* private fields */ }

Manages sub-agent lifecycle: definitions, spawning, cancellation, and result collection.

Implementations

impl SubAgentManager

pub fn new(max_concurrent: usize) -> Self

Create a new manager with the given concurrency limit.

pub fn reserve_slots(&mut self, n: usize)

Reserve n concurrency slots for the orchestration scheduler.

Reserved slots count against the concurrency limit in spawn so that the scheduler can guarantee capacity for tasks it is about to launch. Call release_reservation when the scheduler finishes.

pub fn release_reservation(&mut self, n: usize)

Release n previously reserved concurrency slots.

pub fn set_transcript_config(&mut self, dir: Option<PathBuf>, max_files: usize)

Configure transcript storage settings.

pub fn set_stop_hooks(&mut self, hooks: Vec<HookDef>)

Set config-level lifecycle stop hooks (fired when any agent finishes or is cancelled).

pub fn load_definitions( &mut self, dirs: &[PathBuf], ) -> Result<(), SubAgentError>

Load sub-agent definitions from the given directories.

Higher-priority directories should appear first. Name conflicts are resolved by keeping the first occurrence. Non-existent directories are silently skipped.

Errors

Returns SubAgentError if any definition file fails to parse.

pub fn load_definitions_with_sources( &mut self, ordered_paths: &[PathBuf], cli_agents: &[PathBuf], config_user_dir: Option<&PathBuf>, extra_dirs: &[PathBuf], ) -> Result<(), SubAgentError>

Load definitions with full scope context for source tracking and security checks.

Errors

Returns SubAgentError if a CLI-sourced definition file fails to parse.

pub fn definitions(&self) -> &[SubAgentDef]

Return all loaded definitions.

pub fn definitions_mut(&mut self) -> &mut Vec<SubAgentDef>

Return mutable access to definitions, for testing and dynamic registration.

pub fn insert_handle_for_test(&mut self, id: String, handle: SubAgentHandle)

Insert a pre-built handle directly into the active agents map.

Used in tests to simulate an agent that has already run and left a pending secret request in its channel without going through the full spawn lifecycle.

pub fn spawn( &mut self, def_name: &str, task_prompt: &str, provider: AnyProvider, tool_executor: Arc<dyn ErasedToolExecutor>, skills: Option<Vec<String>>, config: &SubAgentConfig, ctx: SpawnContext, ) -> Result<String, SubAgentError>

Spawn a sub-agent by definition name with real background execution.

Returns the task_id (UUID string) that can be used with cancel and collect.

Errors

Returns SubAgentError::NotFound if no definition with the given name exists, SubAgentError::ConcurrencyLimit if the concurrency limit is exceeded, or SubAgentError::Invalid if the agent requests bypass_permissions but the config does not allow it (allow_bypass_permissions: false).

pub fn shutdown_all(&mut self)

Cancel all active sub-agents. Called during main agent shutdown.

pub fn cancel(&mut self, task_id: &str) -> Result<(), SubAgentError>

Cancel a running sub-agent by task ID.

Errors

Returns SubAgentError::NotFound if the task ID is unknown.

pub fn cancel_all(&mut self)

Cancel all active sub-agents immediately.

Used during shutdown or Ctrl+C handling when DagScheduler may not be running. For coordinated cancellation via the scheduler, use DagScheduler::cancel_all().

pub fn approve_secret( &mut self, task_id: &str, secret_key: &str, ttl: Duration, ) -> Result<(), SubAgentError>

Approve a secret request for a running sub-agent.

Called after the user approves a vault secret access prompt. The secret key must appear in the sub-agent definition’s allowed secrets list; otherwise the request is auto-denied.

Errors

Returns SubAgentError::NotFound if the task ID is unknown, SubAgentError::Invalid if the key is not in the definition’s allowed list.

pub fn deliver_secret( &mut self, task_id: &str, key: String, ) -> Result<(), SubAgentError>

Deliver a secret value to a waiting sub-agent loop.

Should be called after the user approves the request and the vault value has been resolved. Returns an error if no such agent is found.

Errors

Returns SubAgentError::NotFound if the task ID is unknown.

pub fn deny_secret(&mut self, task_id: &str) -> Result<(), SubAgentError>

Deny a pending secret request — sends None to unblock the waiting sub-agent loop.

Errors

Returns SubAgentError::NotFound if the task ID is unknown, SubAgentError::Channel if the channel is full or closed.

pub fn try_recv_secret_request(&mut self) -> Option<(String, SecretRequest)>

Try to receive a pending secret request from a sub-agent (non-blocking).

Returns Some((task_id, SecretRequest)) if a request is waiting.

pub async fn collect(&mut self, task_id: &str) -> Result<String, SubAgentError>

Collect the result from a completed sub-agent, removing it from the active set.

Writes a final TranscriptMeta sidecar with the terminal state and turn count.

Errors

Returns SubAgentError::NotFound if the task ID is unknown, SubAgentError::Spawn if the task panicked.

pub fn resume( &mut self, id_prefix: &str, task_prompt: &str, provider: AnyProvider, tool_executor: Arc<dyn ErasedToolExecutor>, skills: Option<Vec<String>>, config: &SubAgentConfig, ) -> Result<(String, String), SubAgentError>

Resume a previously completed (or failed/cancelled) sub-agent session.

Loads the transcript from the original session into memory and spawns a new agent loop with that history prepended. The new session gets a fresh UUID.

Returns (new_task_id, def_name) on success so the caller can resolve skills by name.

Errors

Returns SubAgentError::StillRunning if the agent is still active, SubAgentError::NotFound if no transcript with the given prefix exists, SubAgentError::AmbiguousId if the prefix matches multiple agents, SubAgentError::Transcript on I/O or parse failure, SubAgentError::ConcurrencyLimit if the concurrency limit is exceeded.

pub fn def_name_for_resume( &self, id_prefix: &str, config: &SubAgentConfig, ) -> Result<String, SubAgentError>

Look up the definition name for a resumable transcript without spawning.

Used by callers that need to resolve skills before calling resume().

Errors

Returns the same errors as TranscriptReader::find_by_prefix and TranscriptReader::load_meta.

pub fn statuses(&self) -> Vec<(String, SubAgentStatus)>

Return a snapshot of all active sub-agent statuses.

pub fn agents_def(&self, task_id: &str) -> Option<&SubAgentDef>

Return the definition for a specific agent by task_id.

pub fn agent_transcript_dir(&self, task_id: &str) -> Option<&Path>

Return the transcript directory for a specific agent by task_id.

pub fn spawn_for_task<F>( &mut self, def_name: &str, task_prompt: &str, provider: AnyProvider, tool_executor: Arc<dyn ErasedToolExecutor>, skills: Option<Vec<String>>, config: &SubAgentConfig, ctx: SpawnContext, on_done: F, ) -> Result<String, SubAgentError>

where F: FnOnce(String, Result<String, SubAgentError>) + Send + 'static,

Spawn a sub-agent for an orchestrated task.

Identical to spawn but wraps the JoinHandle to send a [crate::orchestration::TaskEvent] on the provided channel when the agent loop terminates. This allows the DagScheduler to receive completion notifications without polling (ADR-027).

The event_tx channel is best-effort: if the scheduler is dropped before all agents complete, the send will fail silently with a warning log.

Errors

Same error conditions as spawn.

Panics

Panics if the internal agent entry is missing after a successful spawn call. This is a programming error and should never occur in normal operation. Spawn a sub-agent and attach a completion callback invoked when the agent terminates.

The callback receives the agent handle ID and the agent’s result. The caller is responsible for translating this into orchestration events.

Errors

Same error conditions as spawn.

Panics

Panics if the internal agent entry is missing after a successful spawn call. This is a programming error and should never occur in normal operation.

Trait Implementations

impl Debug for SubAgentManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.