Repository navigation
Sub-agents: working slots - #323
Merged
Merged
Conversation
SlotPool lets a set number of runs work at once; the others wait in a heap ordered by priority, then arrival, a run taking its slot back ahead of the runs that have not started (asyncio.Semaphore wakes in arrival order, with no priority). A run lends its slot while it waits, nested lends counting once, and takes it back after; a child's slot can go straight back to the parent waiting on it alone. A cancelled waiter leaves the heap, one handed a slot as it is cancelled hands it on, and a run cancelled while it lends takes nothing back.
A run's record says running from its start, and queued (waiting for a free working slot) or input_required (waiting on the user) when an AGENT_RUN says so, until its end; a working status after the end changes nothing. /agents shows running, queued and needs you, and the events box writes a run's line when it waits for a slot or for the user and when it works again.
Each conversation's runs share a pool of SubAgentPolicy.max_active working slots, at any depth; the root takes none. A run takes a slot right before its hook and its time limit start, waiting queued (then running) when every slot is held, and gives it back at its end. A run that delegates lends its slot while it waits for its children, and the child that ends last hands it straight back, so the tree in progress goes on ahead of the runs that have not started and nested fan-out never deadlocks. A queued run cancelled, by its turn or alone, leaves the queue; the time it waited is not counted against its timeout.
waiting_on_user(): a sub-agent run says input_required, lends its working slot for the wait, takes a slot back ahead of the runs that have not started and says running; nested waits count once, a cancel takes nothing back, the root's work is untouched. request_user_input waits so, and the permission engine from before its one-prompt lock until after it: a run waiting for its slot while holding the lock would hold every other run's prompt, which with one slot and two runs at prompts was a deadlock.
The limits paragraph of task's description now opens with "At most 4 sub-agents work at once; more calls in one response wait for a free slot.", the number the policy's max_active, before the runs a turn may start.
Two waits of one run that do not overlap (two calls of one response, one asking the user after the other's answer) could each queue to take the run's slot back: the second started while the first waited in the heap, found the slot lent and lent nothing, and both then took a slot. With one slot the run held it while its other call waited for another, a deadlock; with more, the pool lost a slot for the rest of the manager's life. A run's slot now has one take-back at a time: a wait that starts while one is queued withdraws it (that wait ends without the slot, since the run waits again) and takes it back itself, and a hand-back or a release withdraws it too; a slot handed to a withdrawn wait in the same tick goes on to the next waiter.
The CHANGELOG says that at most max_active sub-agent runs work at once (more parallel delegations queue, a run waiting on its children or the user lends its slot), and gives the working statuses of a run's AGENT_RUN, its record and /agents; CLAUDE.md's structure lines and the sub-agent passage describe the pool, the lending and waiting_on_user; the README's limits passage and project tree name them.
A take-back handed the slot before it could go on, while another wait of the same run started and ended at once (a prompt answered without waiting), left that wait's own take-back in the heap: the run held its slot while one of its calls waited for another, a hang with one slot. A take-back that holds the slot now withdraws any queued since, which ends without one. The pool test's two cancels in a finally are two statements.
The parent's wait is over and it waits in the heap for its slot when its child hands the slot back: that take-back ends without one, and the parent holds the child's slot.
Headless (no input callback for the turn), a sub-agent run's permission prompt is denied at once, yet the engine lent the run's slot first: the run queued for one took it and worked its whole run before the asking run could go on. BaseWorkflowManager.can_request_user_input() says whether a request could reach the user now (a callback set for this context, its turn not ended), and the engine lends only when it can; request_user_input already raised before lending. A callback that answers without waiting still lends, as its docstring says.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sub-agent runs work in slots: at most
SubAgentPolicy.max_active(default 4) runs work at once per conversation, at any depth. The root never takes one.workflow/agents/slots.py::SlotPoolis an asyncio counter with a heap of waiting runs, ordered by priority, then arrival. A run waiting for its slot back (RETURNING) goes ahead of runs that have not started (NEW).AGENT_RUNqueued, thenrunningonce it has a slot. A working run's record status isrunning,queuedorinput_required, as/agentsand the events box show.hand_back), so nested fan-out withmax_active=1completes. A slot is taken back once, by the run's last wait. A take-back queued meanwhile ends without a slot.request_user_input) and a permission prompt (the engine lends around its prompt lock, so two runs at prompts with one slot cannot deadlock). The run reportsinput_required, thenrunning.BaseWorkflowManager.can_request_user_input(), new, is false when no input callback is set or the turn has ended.task's description says how many sub-agents work at once.Tests: new tests written first and seen failing. Pool unit tests cover each cancellation case. Contract scenarios on both backends cover:
The full offline suite passes in the worktree, except
TestChildImportOrigin, which fails the same way on develop under the worktree wrapper.