pool

name	pool
description	Run N tasks under a concurrency cap K via a sliding-window worker pool. Use when many subagent invocations would otherwise hit provider rate limits.

Pool Pattern

Many tasks (say 20) to run via subagents, but provider RPM/TPM (or memory) caps how many can run at once (say 6). Maintain a sliding window of K active subagents.

Usage

tasks = [task_1, task_2, ..., task_N]
K = 6                          # concurrency cap
active = {}                    # sid -> task_id
done = {}                      # task_id -> final result text

while tasks or active:
    # Fill the pool up to K
    while tasks and len(active) < K:
        t = tasks.pop(0)
        r = call_subagent(agent_name="worker", request=t.prompt, mode="async")
        active[r.session_id] = t.id

    # Short-poll for any one to finish, then drain
    for sid in list(active.keys()):
        r = wait_for_subagent(sid, timeout=1.0)
        if r.success and r.state in ("sleeping", "unloaded"):
            done[active[sid]] = read_inbox_for(sid)
            del active[sid]
            break  # restart fill loop

Key points:

• No first-completed multi-wait primitive yet. wait_for_subagent with a small timeout polls; loop until one finishes.
• K depends on the provider. Hosted Anthropic / OpenAI vs local LiteLLM proxy → very different limits. Start with 4-6.
• Order of completion is unpredictable. Don't assume done-order matches submission order.
• Failed tasks free their slot like any other completion. Retry failed ones in a separate pass, or feed them into the multi-model pattern.

Common Use Cases

• Batch evaluation: N CTF / SWE-bench tasks on one orchestrator
• Bulk code review on many files
• Fan-out exploration when each branch is independent

Requires Sandbox

None — pure orchestration.