anycode-py 0.1.0__py3-none-any.whl

anycode/core/orchestrator.py

@@ -0,0 +1,267 @@
+"""AnyCode — top-level coordinator for agents, teams, and task execution pipelines."""
+
+from __future__ import annotations
+
+import asyncio
+
+from anycode.collaboration.team import Team
+from anycode.core.agent import Agent
+from anycode.core.pool import AgentPool
+from anycode.core.scheduler import Scheduler
+from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage
+from anycode.tasks.queue import TaskQueue
+from anycode.tasks.task import create_task, get_task_dependency_order, validate_task_dependencies
+from anycode.tools.built_in import register_built_in_tools
+from anycode.tools.executor import ToolExecutor
+from anycode.tools.registry import ToolRegistry
+from anycode.types import (
+    AgentConfig,
+    AgentRunResult,
+    OrchestratorConfig,
+    OrchestratorEvent,
+    Task,
+    TeamConfig,
+    TeamRunResult,
+    TokenUsage,
+)
+
+
+class TaskSpec:
+    def __init__(self, title: str, description: str, assignee: str | None = None, depends_on: list[str] | None = None) -> None:
+        self.title = title
+        self.description = description
+        self.assignee = assignee
+        self.depends_on = depends_on or []
+
+
+class AnyCode:
+    """Top-level orchestration engine for agents, teams, and task pipelines."""
+
+    def __init__(self, config: OrchestratorConfig | dict[str, object] | None = None) -> None:
+        self._config = OrchestratorConfig.model_validate(config) if isinstance(config, dict) else (config or OrchestratorConfig())
+        self._pool = AgentPool(self._config.max_concurrency or 5)
+        self._scheduler = Scheduler("dependency-first")
+        self._teams: dict[str, Team] = {}
+
+    def build_agent(self, config: AgentConfig | dict[str, object]) -> Agent:
+        """Construct a fully wired Agent instance with all default tools."""
+        typed_config = AgentConfig.model_validate(config) if isinstance(config, dict) else config
+        registry = ToolRegistry()
+        register_built_in_tools(registry)
+        executor = ToolExecutor(registry)
+        return Agent(typed_config, registry, executor)
+
+    def create_team(self, name: str, config: TeamConfig) -> Team:
+        """Instantiate a team and enrol its agents into the shared pool."""
+        team = Team(config)
+        self._teams[name] = team
+        for agent_cfg in config.agents:
+            if not self._pool.get(agent_cfg.name):
+                self._pool.add(self.build_agent(agent_cfg))
+        return team
+
+    async def run_agent(self, config: AgentConfig | dict[str, object], prompt: str) -> AgentRunResult:
+        """Create and run a single agent on one prompt."""
+        typed_config = AgentConfig.model_validate(config) if isinstance(config, dict) else config
+        agent = self.build_agent(typed_config)
+        self._emit(OrchestratorEvent(type="agent_start", agent=typed_config.name))
+        try:
+            result = await agent.run(prompt)
+            self._emit(OrchestratorEvent(type="agent_complete", agent=typed_config.name, data=result))
+            return result
+        except Exception as e:
+            self._emit(OrchestratorEvent(type="error", agent=typed_config.name, data=e))
+            return AgentRunResult(success=False, output=str(e), messages=[], token_usage=EMPTY_USAGE, tool_calls=[])
+
+    async def run_team(self, team: Team, goal: str) -> TeamRunResult:
+        """Decompose a high-level goal into tasks using a coordinator agent, then execute."""
+        agents = team.get_agents()
+        if not agents:
+            return TeamRunResult(success=False, agent_results={}, total_token_usage=EMPTY_USAGE)
+
+        coordinator_cfg = agents[0]
+        coordinator = self.build_agent(coordinator_cfg)
+        coordinator_prompt = self._build_coordinator_prompt(agents, goal)
+
+        self._emit(OrchestratorEvent(type="agent_start", agent=coordinator_cfg.name))
+        plan_result = await coordinator.run(coordinator_prompt)
+        self._emit(OrchestratorEvent(type="agent_complete", agent=coordinator_cfg.name, data=plan_result))
+
+        if not plan_result.success:
+            return TeamRunResult(
+                success=False,
+                agent_results={coordinator_cfg.name: plan_result},
+                total_token_usage=plan_result.token_usage,
+            )
+
+        task_specs = self._parse_task_specs(plan_result.output, agents)
+        if not task_specs:
+            return TeamRunResult(
+                success=True,
+                agent_results={coordinator_cfg.name: plan_result},
+                total_token_usage=plan_result.token_usage,
+            )
+
+        task_results = await self._execute_tasks(team, task_specs)
+        combined = {coordinator_cfg.name: plan_result, **task_results.agent_results}
+        total = plan_result.token_usage
+        for r in task_results.agent_results.values():
+            total = merge_usage(total, r.token_usage)
+
+        return TeamRunResult(success=task_results.success, agent_results=combined, total_token_usage=total)
+
+    async def run_tasks(self, team: Team, task_specs: list[TaskSpec]) -> TeamRunResult:
+        """Run an explicit set of task specs with full dependency resolution."""
+        return await self._execute_tasks(team, task_specs)
+
+    async def _execute_tasks(self, team: Team, specs: list[TaskSpec]) -> TeamRunResult:
+        resolved = self._resolve_specs(specs)
+        queue = TaskQueue()
+        agent_results: dict[str, AgentRunResult] = {}
+        total_usage: TokenUsage = EMPTY_USAGE
+        all_succeeded = True
+
+        for task in resolved:
+            queue.add(task)
+
+        self._scheduler.auto_assign(queue, team.get_agents())
+        ordered = get_task_dependency_order(queue.list())
+        waves = self._build_waves(ordered, queue)
+
+        for wave in waves:
+            async def _run_task(task: Task) -> None:
+                nonlocal all_succeeded, total_usage
+                assignee = task.assignee
+                if not assignee:
+                    queue.fail(task.id, "Unassigned task — no agent available.")
+                    return
+
+                self._emit(OrchestratorEvent(type="task_start", task=task.id, agent=assignee, data=task))
+                queue.update(task.id, status="in_progress")
+
+                prompt = self._build_task_prompt(task, queue)
+                agent = self._pool.get(assignee) or self._build_agent_for_team(assignee, team)
+
+                self._emit(OrchestratorEvent(type="agent_start", agent=assignee))
+                try:
+                    result = await agent.run(prompt)
+                    self._emit(OrchestratorEvent(type="agent_complete", agent=assignee, data=result))
+                    if result.success:
+                        queue.complete(task.id, result.output)
+                        self._emit(OrchestratorEvent(type="task_complete", task=task.id, agent=assignee))
+                    else:
+                        queue.fail(task.id, result.output)
+                        all_succeeded = False
+                    agent_results[assignee] = result
+                    total_usage = merge_usage(total_usage, result.token_usage)
+                except Exception as e:
+                    queue.fail(task.id, str(e))
+                    all_succeeded = False
+                    agent_results[assignee] = AgentRunResult(
+                        success=False, output=str(e), messages=[], token_usage=EMPTY_USAGE, tool_calls=[]
+                    )
+
+            await asyncio.gather(*[_run_task(t) for t in wave])
+
+        return TeamRunResult(success=all_succeeded, agent_results=agent_results, total_token_usage=total_usage)
+
+    def _build_agent_for_team(self, agent_name: str, team: Team) -> Agent:
+        config = team.get_agent(agent_name)
+        if not config:
+            raise ValueError(f'AnyCode: "{agent_name}" is not part of team "{team.name}".')
+        agent = self.build_agent(config)
+        try:
+            self._pool.add(agent)
+        except ValueError:
+            pass
+        return agent
+
+    def _resolve_specs(self, specs: list[TaskSpec]) -> list[Task]:
+        title_map: dict[str, str] = {}
+        pending: list[tuple[Task, list[str]]] = []
+
+        for spec in specs:
+            task = create_task(title=spec.title, description=spec.description, assignee=spec.assignee)
+            title_map[spec.title] = task.id
+            pending.append((task, spec.depends_on))
+
+        resolved: list[Task] = []
+        for task, raw_deps in pending:
+            dep_ids = [title_map[d] for d in raw_deps if d in title_map]
+            final = task.model_copy(update={"depends_on": dep_ids}) if dep_ids else task
+            resolved.append(final)
+
+        valid, errors = validate_task_dependencies(resolved)
+        if not valid:
+            raise ValueError("AnyCode: task dependency errors:\n" + "\n".join(errors))
+
+        return resolved
+
+    def _build_waves(self, ordered: list[Task], queue: TaskQueue) -> list[list[Task]]:
+        if not ordered:
+            return []
+        done: set[str] = set()
+        remaining = list(ordered)
+        waves: list[list[Task]] = []
+
+        while remaining:
+            wave = [t for t in remaining if all(d in done for d in (t.depends_on or []))]
+            if not wave:
+                for t in remaining:
+                    queue.fail(t.id, "Unresolvable or circular dependency.")
+                break
+            waves.append(wave)
+            done.update(t.id for t in wave)
+            remaining = [t for t in remaining if t.id not in done]
+
+        return waves
+
+    def _build_coordinator_prompt(self, agents: list[AgentConfig], goal: str) -> str:
+        roster = "\n".join(f"- {a.name}: {(a.system_prompt or 'general-purpose assistant')[:80]}" for a in agents)
+        return (
+            f"You are the lead coordinator of a team. Here are your team members:\n{roster}\n\n"
+            f"Objective: {goal}\n\n"
+            "If you can accomplish this objective entirely by yourself with the tools you have, go ahead and do so now.\n"
+            "Otherwise, decompose the objective into concrete tasks and list them in the following format (one per line):\n\n"
+            "ASSIGN: <agent_name> | <task_title> | <task_description>\n\n"
+            "Only output ASSIGN: lines when you need to delegate. Pick the best-suited team member for each task.\n"
+            "List tasks in execution order — later tasks may depend on earlier ones."
+        )
+
+    def _build_task_prompt(self, task: Task, queue: TaskQueue) -> str:
+        dep_context_parts = []
+        for dep_id in task.depends_on or []:
+            dep_task = next((t for t in queue.list() if t.id == dep_id), None)
+            if dep_task and dep_task.result:
+                dep_context_parts.append(f"[{dep_task.title}]: {dep_task.result[:500]}")
+
+        context = "\n\nRelevant output from prerequisite tasks:\n" + "\n\n".join(dep_context_parts) if dep_context_parts else ""
+        return f"Task: {task.title}\n\n{task.description}{context}"
+
+    def _parse_task_specs(self, output: str, agents: list[AgentConfig]) -> list[TaskSpec]:
+        lines = [ln for ln in output.split("\n") if ln.strip().upper().startswith("ASSIGN:")]
+        if not lines:
+            return []
+
+        valid_names = {a.name for a in agents}
+        specs: list[TaskSpec] = []
+        titles: list[str] = []
+
+        for line in lines:
+            body = line.split(":", 1)[1].strip() if ":" in line else ""
+            segments = [s.strip() for s in body.split("|")]
+            if len(segments) < 3:
+                continue
+            assignee, title, *desc_parts = segments
+            description = " | ".join(desc_parts)
+            if assignee not in valid_names:
+                continue
+            depends_on = [titles[-1]] if titles else None
+            specs.append(TaskSpec(title=title, description=description, assignee=assignee, depends_on=depends_on))
+            titles.append(title)
+
+        return specs
+
+    def _emit(self, event: OrchestratorEvent) -> None:
+        if self._config.on_progress:
+            self._config.on_progress(event)

anycode/core/pool.py

@@ -0,0 +1,99 @@
+"""Agent registry with semaphore-bounded concurrency and round-robin dispatch."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from anycode.helpers.concurrency_gate import Semaphore
+from anycode.helpers.usage_tracker import EMPTY_USAGE
+from anycode.types import AgentRunResult, PoolStatus
+
+if TYPE_CHECKING:
+    from anycode.core.agent import Agent
+
+
+class AgentPool:
+    """Manages named agents with bounded concurrency."""
+
+    def __init__(self, max_concurrency: int = 5) -> None:
+        self._agents: dict[str, Agent] = {}
+        self._semaphore = Semaphore(max_concurrency)
+        self._rr_index = 0
+
+    def add(self, agent: Agent) -> None:
+        if agent.name in self._agents:
+            raise ValueError(f'Pool: agent "{agent.name}" already exists in the registry.')
+        self._agents[agent.name] = agent
+
+    def remove(self, name: str) -> None:
+        if name not in self._agents:
+            raise ValueError(f'Pool: no agent named "{name}" is registered.')
+        del self._agents[name]
+
+    def get(self, name: str) -> Agent | None:
+        return self._agents.get(name)
+
+    def list(self) -> list[Agent]:
+        return list(self._agents.values())
+
+    async def run(self, agent_name: str, prompt: str) -> AgentRunResult:
+        agent = self._require(agent_name)
+        await self._semaphore.acquire()
+        try:
+            return await agent.run(prompt)
+        finally:
+            self._semaphore.release()
+
+    async def run_parallel(self, jobs: list[dict[str, str]]) -> dict[str, AgentRunResult]:
+        results: dict[str, AgentRunResult] = {}
+
+        async def _job(agent_name: str, prompt: str) -> None:
+            try:
+                results[agent_name] = await self.run(agent_name, prompt)
+            except Exception as e:
+                results[agent_name] = AgentRunResult(
+                    success=False, output=str(e), messages=[], token_usage=EMPTY_USAGE, tool_calls=[]
+                )
+
+        await asyncio.gather(*[_job(j["agent"], j["prompt"]) for j in jobs])
+        return results
+
+    async def run_any(self, prompt: str) -> AgentRunResult:
+        agents = self.list()
+        if not agents:
+            raise ValueError("Pool: run_any() requires at least one registered agent.")
+        self._rr_index = self._rr_index % len(agents)
+        agent = agents[self._rr_index]
+        self._rr_index = (self._rr_index + 1) % len(agents)
+
+        await self._semaphore.acquire()
+        try:
+            return await agent.run(prompt)
+        finally:
+            self._semaphore.release()
+
+    def get_status(self) -> PoolStatus:
+        idle = running = completed = error = 0
+        for agent in self._agents.values():
+            s = agent.get_state().status
+            if s == "idle":
+                idle += 1
+            elif s == "running":
+                running += 1
+            elif s == "completed":
+                completed += 1
+            elif s == "error":
+                error += 1
+        return PoolStatus(total=len(self._agents), idle=idle, running=running, completed=completed, error=error)
+
+    async def shutdown(self) -> None:
+        for agent in self._agents.values():
+            agent.reset()
+
+    def _require(self, name: str) -> Agent:
+        agent = self._agents.get(name)
+        if agent is None:
+            available = ", ".join(self._agents.keys())
+            raise ValueError(f'Pool: "{name}" not found. Available agents: [{available}]')
+        return agent

anycode/core/runner.py

@@ -0,0 +1,176 @@
+"""Agentic dialogue driver — manages LLM interactions, tool dispatch, and turn looping."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncGenerator, Callable
+
+from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage
+from anycode.tools.executor import ToolExecutor
+from anycode.tools.registry import ToolRegistry
+from anycode.types import (
+    AgentInfo,
+    ContentBlock,
+    LLMAdapter,
+    LLMChatOptions,
+    LLMMessage,
+    RunnerOptions,
+    RunResult,
+    StreamEvent,
+    TextBlock,
+    TokenUsage,
+    ToolCallRecord,
+    ToolResult,
+    ToolResultBlock,
+    ToolUseBlock,
+    ToolUseContext,
+)
+
+
+def _pull_text(blocks: list[ContentBlock]) -> str:
+    return "".join(b.text for b in blocks if isinstance(b, TextBlock))
+
+
+def _filter_tool_calls(blocks: list[ContentBlock]) -> list[ToolUseBlock]:
+    return [b for b in blocks if isinstance(b, ToolUseBlock)]
+
+
+class AgentRunner:
+    """Orchestrates the full model-tool-model turn loop until completion or limit."""
+
+    def __init__(
+        self,
+        adapter: LLMAdapter,
+        tool_registry: ToolRegistry,
+        tool_executor: ToolExecutor,
+        options: RunnerOptions,
+    ) -> None:
+        self._adapter = adapter
+        self._registry = tool_registry
+        self._executor = tool_executor
+        self._options = options
+        self._turn_limit = options.max_turns or 10
+
+    async def run(
+        self,
+        messages: list[LLMMessage],
+        on_message: Callable[[LLMMessage], None] | None = None,
+    ) -> RunResult:
+        fallback = RunResult(messages=[], output="", tool_calls=[], token_usage=EMPTY_USAGE, turns=0)
+        async for event in self.stream(messages, on_message=on_message):
+            if event.type == "done":
+                return event.data  # type: ignore[return-value]
+        return fallback
+
+    async def stream(
+        self,
+        seed_messages: list[LLMMessage],
+        on_message: Callable[[LLMMessage], None] | None = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        conversation = list(seed_messages)
+        cumulative_usage: TokenUsage = EMPTY_USAGE
+        tool_calls: list[ToolCallRecord] = []
+        last_output = ""
+        turn_count = 0
+
+        # Prepare tool defs
+        all_defs = self._registry.to_tool_defs()
+        active_defs = (
+            [d for d in all_defs if d.name in self._options.allowed_tools]
+            if self._options.allowed_tools
+            else all_defs
+        )
+
+        chat_params = LLMChatOptions(
+            model=self._options.model,
+            tools=active_defs if active_defs else None,
+            max_tokens=self._options.max_tokens,
+            temperature=self._options.temperature,
+            system_prompt=self._options.system_prompt,
+        )
+
+        try:
+            while turn_count < self._turn_limit:
+                turn_count += 1
+                response = await self._adapter.chat(conversation, chat_params)
+                cumulative_usage = merge_usage(cumulative_usage, response.usage)
+
+                assistant_msg = LLMMessage(role="assistant", content=response.content)
+                conversation.append(assistant_msg)
+                if on_message:
+                    on_message(assistant_msg)
+
+                turn_text = _pull_text(response.content)
+                if turn_text:
+                    yield StreamEvent(type="text", data=turn_text)
+
+                tool_blocks = _filter_tool_calls(response.content)
+                for block in tool_blocks:
+                    yield StreamEvent(type="tool_use", data=block)
+
+                if not tool_blocks:
+                    last_output = turn_text
+                    break
+
+                ctx = self._build_context()
+                results: list[tuple[ToolResultBlock, ToolCallRecord]] = []
+
+                for block in tool_blocks:
+                    began = time.monotonic()
+                    try:
+                        result = await self._executor.execute(block.name, block.input, ctx)
+                    except Exception as e:
+                        result = ToolResult(data=str(e), is_error=True)
+
+                    result_block = ToolResultBlock(
+                        tool_use_id=block.id,
+                        content=result.data,
+                        is_error=result.is_error,
+                    )
+                    record = ToolCallRecord(
+                        tool_name=block.name,
+                        input=block.input,
+                        output=result.data,
+                        duration=time.monotonic() - began,
+                    )
+                    results.append((result_block, record))
+
+                result_blocks: list[ContentBlock] = [r[0] for r in results]
+                for _, record in results:
+                    tool_calls.append(record)
+                    yield StreamEvent(type="tool_result", data=record)
+
+                tool_msg = LLMMessage(role="user", content=result_blocks)
+                conversation.append(tool_msg)
+                if on_message:
+                    on_message(tool_msg)
+
+        except Exception as e:
+            yield StreamEvent(type="error", data=e)
+            return
+
+        if not last_output and conversation:
+            for msg in reversed(conversation):
+                if msg.role == "assistant":
+                    last_output = _pull_text(msg.content)
+                    break
+
+        yield StreamEvent(
+            type="done",
+            data=RunResult(
+                messages=conversation[len(seed_messages):],
+                output=last_output,
+                tool_calls=tool_calls,
+                token_usage=cumulative_usage,
+                turns=turn_count,
+            ),
+        )
+
+    def _build_context(self) -> ToolUseContext:
+        return ToolUseContext(
+            agent=AgentInfo(
+                name=self._options.agent_name or "runner",
+                role=self._options.agent_role or "assistant",
+                model=self._options.model,
+            )
+        )

anycode/core/scheduler.py

@@ -0,0 +1,126 @@
+"""Scheduling strategies for distributing tasks across agents."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from anycode.types import AgentConfig, SchedulingStrategy, Task
+
+if TYPE_CHECKING:
+    from anycode.tasks.queue import TaskQueue
+
+NOISE_WORDS = {
+    "the", "and", "for", "that", "this", "with", "are", "from", "have",
+    "will", "your", "you", "can", "all", "each", "when", "then", "they",
+    "them", "about", "into", "more", "also", "should", "must", "been",
+    "some", "what", "than",
+}
+
+
+def _tokenize(text: str) -> list[str]:
+    words = set(re.split(r"\W+", text.lower()))
+    return [w for w in words if len(w) > 3 and w not in NOISE_WORDS]
+
+
+def _relevance_score(text: str, terms: list[str]) -> int:
+    lower = text.lower()
+    return sum(1 for t in terms if t in lower)
+
+
+def _downstream_block_count(task_id: str, children: dict[str, list[str]], task_ids: set[str]) -> int:
+    seen: set[str] = set()
+    frontier = [task_id]
+    while frontier:
+        current = frontier.pop(0)
+        for child in children.get(current, []):
+            if child not in seen and child in task_ids:
+                seen.add(child)
+                frontier.append(child)
+    return len(seen)
+
+
+def _build_children_map(tasks: list[Task]) -> tuple[dict[str, list[str]], set[str]]:
+    task_ids = {t.id for t in tasks}
+    children: dict[str, list[str]] = {}
+    for t in tasks:
+        for dep_id in t.depends_on or []:
+            children.setdefault(dep_id, []).append(t.id)
+    return children, task_ids
+
+
+class Scheduler:
+    """Distributes tasks across agents using one of four strategies."""
+
+    def __init__(self, strategy: SchedulingStrategy = "dependency-first") -> None:
+        self._strategy = strategy
+        self._rr_cursor = 0
+
+    def schedule(self, tasks: list[Task], agents: list[AgentConfig]) -> dict[str, str]:
+        if not agents:
+            return {}
+        pending = [t for t in tasks if t.status == "pending" and not t.assignee]
+
+        match self._strategy:
+            case "round-robin":
+                return self._round_robin(pending, agents)
+            case "least-busy":
+                return self._least_busy(pending, agents, tasks)
+            case "capability-match":
+                return self._capability_match(pending, agents)
+            case "dependency-first":
+                return self._dependency_first(pending, agents, tasks)
+
+    def auto_assign(self, queue: TaskQueue, agents: list[AgentConfig]) -> None:
+        snapshot = queue.list()
+        assignments = self.schedule(snapshot, agents)
+        for task_id, agent_name in assignments.items():
+            try:
+                queue.update(task_id, assignee=agent_name)
+            except Exception:
+                pass
+
+    def _round_robin(self, pending: list[Task], agents: list[AgentConfig]) -> dict[str, str]:
+        result: dict[str, str] = {}
+        for task in pending:
+            result[task.id] = agents[self._rr_cursor % len(agents)].name
+            self._rr_cursor = (self._rr_cursor + 1) % len(agents)
+        return result
+
+    def _least_busy(self, pending: list[Task], agents: list[AgentConfig], all_tasks: list[Task]) -> dict[str, str]:
+        workload = {a.name: 0 for a in agents}
+        for t in all_tasks:
+            if t.status == "in_progress" and t.assignee:
+                workload[t.assignee] = workload.get(t.assignee, 0) + 1
+
+        result: dict[str, str] = {}
+        for task in pending:
+            pick = min(agents, key=lambda a: workload.get(a.name, 0))
+            result[task.id] = pick.name
+            workload[pick.name] = workload.get(pick.name, 0) + 1
+        return result
+
+    def _capability_match(self, pending: list[Task], agents: list[AgentConfig]) -> dict[str, str]:
+        agent_terms = {a.name: _tokenize(f"{a.name} {a.system_prompt or ''} {a.model}") for a in agents}
+        result: dict[str, str] = {}
+        for task in pending:
+            task_text = f"{task.title} {task.description}"
+            task_terms = _tokenize(task_text)
+            best = max(
+                agents,
+                key=lambda a: _relevance_score(f"{a.name} {a.system_prompt or ''}", task_terms)
+                + _relevance_score(task_text, agent_terms.get(a.name, [])),
+            )
+            result[task.id] = best.name
+        return result
+
+    def _dependency_first(self, pending: list[Task], agents: list[AgentConfig], all_tasks: list[Task]) -> dict[str, str]:
+        children, task_ids = _build_children_map(all_tasks)
+        ranked = sorted(pending, key=lambda t: _downstream_block_count(t.id, children, task_ids), reverse=True)
+        result: dict[str, str] = {}
+        cursor = self._rr_cursor
+        for task in ranked:
+            result[task.id] = agents[cursor % len(agents)].name
+            cursor = (cursor + 1) % len(agents)
+        self._rr_cursor = cursor
+        return result

anycode/helpers/__init__.py

@@ -0,0 +1,4 @@
+from anycode.helpers.concurrency_gate import Semaphore
+from anycode.helpers.usage_tracker import EMPTY_USAGE, merge_usage
+
+__all__ = ["Semaphore", "EMPTY_USAGE", "merge_usage"]