Pixir.Subagents (pixir v0.1.4)

Public facade for BEAM-native Subagent orchestration (ADR 0011).

Subagents move through a small lifecycle state machine. The usual path is queued -> running -> completed, but failures, timeouts, cancellation, and detached restored children must remain explicit so parents and diagnostics can tell "finished cleanly" apart from "needs operator attention".

Summary

Functions

child_spec(opts)

Application child spec.

close(parent_session_id, id, opts \\ [])

Close a Subagent thread.

default_limits()

Default runtime limits.

list(parent_session_id, opts \\ [])

List Subagents for a parent Session.

reconstruct(history)

Reconstruct Subagent relationships and terminal state from parent History.

send_input(parent_session_id, subagent_id, prompt, opts \\ [])

Send follow-up input to an idle Subagent.

spawn_agent(parent_session_id, args, opts \\ [])

Spawn or queue a Subagent.

statuses()

All known Subagent lifecycle statuses.

summarize(agents)

Summarize agent maps for model-facing output.

summarize_wait_outcome(arg1)

Build model-facing text for a structured wait outcome.

terminal?(status)

Whether a status is terminal.

terminal_statuses()

Statuses that no longer have a live child runtime.

transition_allowed?(from, to)

Whether the public lifecycle contract allows a status transition.

wait(parent_session_id, ids, timeout_ms \\ 30000, opts \\ [])

Wait for selected Subagents to reach a terminal status.

wait_outcome(parent_session_id, ids, timeout_ms \\ 30000, opts \\ [])

Wait for selected Subagents and return a structured outcome.

Functions

child_spec(opts)

Application child spec.

close(parent_session_id, id, opts \\ [])

Close a Subagent thread.

default_limits()

Default runtime limits.

list(parent_session_id, opts \\ [])

List Subagents for a parent Session.

reconstruct(history)

Reconstruct Subagent relationships and terminal state from parent History.

send_input(parent_session_id, subagent_id, prompt, opts \\ [])

Send follow-up input to an idle Subagent.

spawn_agent(parent_session_id, args, opts \\ [])

Spawn or queue a Subagent.

statuses()

All known Subagent lifecycle statuses.

summarize(agents)

Summarize agent maps for model-facing output.

summarize_wait_outcome(arg1)

Build model-facing text for a structured wait outcome.

terminal?(status)

Whether a status is terminal.

terminal_statuses()

Statuses that no longer have a live child runtime.

transition_allowed?(from, to)

Whether the public lifecycle contract allows a status transition.

closed is retained as Pixir's local close/cleanup state. Completed, failed, timed-out, and cancelled Subagents may be restarted by send_input/4; detached children cannot be resumed because there is no live process handle.

wait(parent_session_id, ids, timeout_ms \\ 30000, opts \\ [])

Wait for selected Subagents to reach a terminal status.

wait_outcome(parent_session_id, ids, timeout_ms \\ 30000, opts \\ [])

Wait for selected Subagents and return a structured outcome.

Unlike wait/4, this keeps partial fanout visible: timed-out, failed, detached, cancelled, and still-incomplete children are bucketed instead of turning the parent tool call into an opaque failure. The returned "partial" boolean is true for any non-completed aggregate status; consumers should use "status" when they need to distinguish "partial" from "incomplete".