feat(impl): mixture-of-agents modes — generative + advisory (#668)

[anderskev]

Summary

• Adds generative mixture-of-agents (MoA) mode where N Developer proposer agents run concurrently in isolated git worktrees, then an Aggregator selects the best candidate and applies its diff
• Individual proposer failures degrade gracefully — the aggregator works with whatever valid candidates are available
• Wired into the implementation pipeline graph behind a config flag, with a routing function that skips MoA when disabled

Motivation

Closes #668

Generative tasks (feature implementation, bug fixes) often have multiple valid approaches. Mixture-of-agents lets multiple Developer agents independently attempt the same task in isolated worktrees, then selects the strongest candidate — improving output quality through diversity while preserving isolation between concurrent attempts.

Changes

Added

• MoAConfig dataclass in types.py with validation (proposer count, model selection, isolation settings)
• GenerativeMoACandidate state model in state.py
• generative_moa_proposers_node — concurrent fan-out across N isolated worktrees
• generative_moa_aggregator_node — candidate selection + diff application
• Graph wiring in graph.py with routing function to enable/disable MoA mode
• Worktree isolation helpers in utils.py
• 41 unit tests covering config validation, proposer concurrency/failure handling, aggregation behavior, and graph wiring

Changed

• routing.py updated to route through MoA nodes when enabled
• state.py extended with MoA candidate tracking fields

Test Plan

• 41 unit tests added (tests/unit/pipelines/test_generative_moa_*.py, tests/unit/core/test_moa_config.py)
  • Config validation (proposer count, model config)
  • Proposer concurrency and graceful failure handling
  • Aggregation behavior (candidate selection, diff application)
  • Graph wiring and routing function
• uv run ruff check . — clean
• uv run mypy . — clean (no issues in 205 source files)
• Full unit test suite passes (uv run pytest tests/unit — 2701 passed)

Checklist

• Tests pass locally (uv run pytest)
• Linting passes (uv run ruff check)
• Type checking passes (uv run mypy)
• Documentation updated (deferred to follow-up)

---

Follow-up Changes (2026-07-02): advisory MoA merged in

This PR now also carries the advisory MoA planning pipeline (the sibling
feature described in #668's background), reconciled from feat/moa-pipeline
into a single implementation. The two MoA stages are independent and compose:

• Advisory MoA (options['moa'] on the architect agent): N Architect
  proposers plan the same issue concurrently, each writing a distinct
  -proposerN plan file; an Aggregator agent (amelia/agents/aggregator.py)
  synthesizes one canonical plan via write_plan for plan_validator_node.
  A single surviving proposer is promoted directly without synthesis. Wired at
  graph-build time — the resolved profile is threaded through
  GraphRunner.create_server_graph / ImplementationPipeline.create_graph.
• Generative MoA (options['moa'] on the developer agent): unchanged
  from the original PR — N Developer proposers in isolated worktrees, first
  successful candidate diff applied atomically.

Reconciliation decisions

• One MoAConfig, stage selected by placement. The mode enum
  (advisory|generative) is gone: config on the architect agent means
  advisory, on the developer agent means generative. Placement expresses
  intent exactly and removes contradictory states (e.g. mode=advisory on
  the developer, which previously warned and fell back).
• proposer_count defaults to 2 (was 1): a mixture of one agent isn't a
  mixture; enabling MoA without an explicit count should actually fan out.
• Aggregator decoupled from pipeline state: Aggregator.aggregate()
  yields AggregatorResult (raw agentic outputs); the node builds its own
  state update, so the agent has no dependency on ImplementationState.
• Stage-symmetric naming: advisory nodes/state are
  advisory_moa_proposers_node / advisory_moa_aggregator_node /
  advisory_moa_proposer_plans, mirroring the generative_moa_* names.
• Optional aggregator agent seeded by amelia config init (not added to
  REQUIRED_AGENTS; the node falls back to the architect config for legacy
  profiles), plus an aggregator.system prompt default and tool profile.

New tests

• tests/integration/test_advisory_moa_pipeline.py — end-to-end advisory MoA
  through the production OrchestratorService + real Postgres + real
  LangGraph run; only ApiDriver.execute_agentic (the LLM boundary) is
  mocked. Covers 2-proposer synthesis and best-effort survivor promotion.
• Unit tests for the Aggregator agent, advisory proposers/aggregator nodes,
  conditional graph wiring, server profile threading, and config CLI seeding.

Verification

• uv run ruff check amelia tests — clean
• uv run mypy amelia — clean (206 files)
• uv run pytest — 2728 passed
• uv run pytest -m integration — 407 passed, 4 skipped (includes the new
  advisory MoA end-to-end test; one unrelated-looking failure from a
  deprecated OpenRouter model id was fixed here via cherry-pick aa5c182f)
• Full pre-push gate (ruff, mypy, pytest, dashboard build) — passed

[anderskev]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 007c9e97-a436-41c0-a1c4-b4a9cac9f9ad

📥 Commits

Reviewing files that changed from the base of the PR and between e3462af and 41fcd74.

📒 Files selected for processing (37)

• amelia/agents/aggregator.py
• amelia/agents/prompts/defaults.py
• amelia/agents/tool_profiles.py
• amelia/cli/config.py
• amelia/core/types.py
• amelia/pipelines/implementation/graph.py
• amelia/pipelines/implementation/moa.py
• amelia/pipelines/implementation/nodes.py
• amelia/pipelines/implementation/pipeline.py
• amelia/pipelines/implementation/routing.py
• amelia/pipelines/implementation/state.py
• amelia/pipelines/nodes.py
• amelia/server/database/migrator.py
• amelia/server/orchestrator/runner.py
• amelia/server/routes/settings.py
• dashboard/src/components/settings/profile-form/AgentsSection.tsx
• dashboard/src/components/settings/profile-form/__tests__/AgentsSection.test.tsx
• dashboard/src/components/settings/profile-form/__tests__/useProfileForm.test.ts
• dashboard/src/components/settings/profile-form/types.ts
• dashboard/src/components/settings/profile-form/useProfileForm.ts
• dashboard/src/hooks/__tests__/useRecentModels.test.ts
• dashboard/src/pages/ProfileDetailPage.tsx
• tests/integration/test_advisory_moa_pipeline.py
• tests/integration/test_task_based_execution.py
• tests/unit/agents/test_aggregator.py
• tests/unit/cli/test_config_cli.py
• tests/unit/cli/test_profile_update.py
• tests/unit/core/test_moa_config.py
• tests/unit/core/test_types.py
• tests/unit/pipelines/test_advisory_moa_aggregator_node.py
• tests/unit/pipelines/test_advisory_moa_graph_wiring.py
• tests/unit/pipelines/test_advisory_moa_proposers_node.py
• tests/unit/pipelines/test_developer_node_config.py
• tests/unit/pipelines/test_generative_moa_aggregator_node.py
• tests/unit/pipelines/test_generative_moa_graph_wiring.py
• tests/unit/server/orchestrator/test_runner.py
• tests/unit/tools/test_knowledge_registration.py

Walkthrough

This PR adds a Generative Mixture-of-Agents (MoA) execution path to the implementation pipeline. New MoAMode, MoAIsolation, and MoAConfig types are added to amelia/core/types.py. The pipeline state gains GenerativeMoACandidate discriminated union types and two new ImplementationState fields. A new amelia/pipelines/implementation/moa.py module implements generative_moa_proposers_node (concurrent Developer runs in isolated git worktrees) and generative_moa_aggregator_node (sequential diff application via scratch worktrees with fast-forward merge). The LangGraph implementation graph is rewired to route post-approval to developer, MoA, or reject. commit_task_changes gains an early-exit guard when MoA has already committed. Unit tests cover all new types, nodes, routing, and graph wiring.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.94% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR implements the linked MoA requirements: concurrent isolated proposers, diff aggregation, graceful failure handling, and configurable count/model selection.
Out of Scope Changes check	✅ Passed	The added tests and helper updates support the MoA feature and do not appear unrelated to the stated objectives.
Description check	✅ Passed	The description clearly matches the changeset, describing generative MoA worktrees, aggregation, routing, and tests.
Title check	✅ Passed	The title clearly summarizes the main change: adding implementation MoA modes for generative and advisory routing.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (2)

tests/unit/pipelines/test_generative_moa_graph_wiring.py (1)

1-1: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Place this under tests/unit/pipelines/implementation/ to mirror the source module.

This file exercises amelia/pipelines/implementation/graph.py and routing.py, but it lives one level higher in tests/unit/pipelines/. Moving it under the mirrored implementation/ test package will keep discovery and ownership consistent. As per coding guidelines, tests should mirror module structure in tests/ with subdirectories for unit/, integration/, e2e/, and perf/.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/unit/pipelines/test_generative_moa_graph_wiring.py` at line 1, This
test file is in the wrong place and should be moved to mirror the source module
structure under the implementation test package. Relocate the generative MoA
graph wiring test into tests/unit/pipelines/implementation/ so it aligns with
the code it covers, specifically the graph.py and routing.py modules, and keep
the existing test name/content intact after the move.

Source: Coding guidelines

amelia/pipelines/implementation/routing.py (1)

30-45: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Deduplicate resolve_moa_config.

The same helper body also exists in amelia/pipelines/implementation/moa.py, so routing and proposer execution can drift the next time MoA option parsing changes. Prefer a single shared definition and import it from both call sites.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@amelia/pipelines/implementation/routing.py` around lines 30 - 45, Deduplicate
the MoA config resolver by making resolve_moa_config a single shared
implementation instead of keeping identical copies in routing.py and moa.py.
Move or centralize the helper in one module, then update both the routing path
and the proposer execution path to import and use that shared resolve_moa_config
so MoA option parsing stays consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@amelia/core/types.py`:
- Around line 344-377: MoAConfig currently allows unknown fields to be ignored,
so typos in the “moa” options silently fall back to the default config. Update
MoAConfig’s validation in core/types.py to forbid extra keys at the config
boundary, and keep from_options() using model_validate() so invalid dicts fail
fast instead of being treated as disabled. Use the MoAConfig class and its
from_options() method as the touchpoints for the fix.

In `@amelia/pipelines/implementation/moa.py`:
- Around line 148-176: The scratch worktree commit path in
_commit_scratch_worktree currently drops any non-zero git commit result, so
hook-driven rewrites can cause a valid MoA candidate to be lost. Update
_commit_scratch_worktree to use the same hook-aware retry behavior as
commit_task_changes(): after a failed commit, restage the worktree changes and
retry the commit before returning None, keeping the existing _run_git and
logger.debug flow for unexpected failures.

In `@amelia/pipelines/implementation/state.py`:
- Around line 125-128: `call_developer_node` currently clears
`driver_session_id` but leaves the MoA fields in `ImplementationState`, so stale
`generative_moa_selected` / `generative_moa_candidates` can block
`commit_task_changes` on retries or later tasks. Update the state reset in the
developer-path transition to explicitly clear both MoA fields when returning to
`developer_node`, using the existing `call_developer_node` flow and the
`ImplementationState` fields `generative_moa_selected` and
`generative_moa_candidates`.

In `@amelia/pipelines/implementation/utils.py`:
- Around line 409-416: The commit skip in commit_task_changes is too broad
because state.generative_moa_selected persists after the MoA task and can cause
later tasks to bypass commits incorrectly. Scope this check to the task that
actually created the MoA selection by either clearing the flag after the MoA
task completes or storing the originating task id alongside the selected
candidate and comparing it before returning early. Use the existing
commit_task_changes logic and state.generative_moa_selected reference to keep
the skip limited to the correct task.

---

Nitpick comments:
In `@amelia/pipelines/implementation/routing.py`:
- Around line 30-45: Deduplicate the MoA config resolver by making
resolve_moa_config a single shared implementation instead of keeping identical
copies in routing.py and moa.py. Move or centralize the helper in one module,
then update both the routing path and the proposer execution path to import and
use that shared resolve_moa_config so MoA option parsing stays consistent.

In `@tests/unit/pipelines/test_generative_moa_graph_wiring.py`:
- Line 1: This test file is in the wrong place and should be moved to mirror the
source module structure under the implementation test package. Relocate the
generative MoA graph wiring test into tests/unit/pipelines/implementation/ so it
aligns with the code it covers, specifically the graph.py and routing.py
modules, and keep the existing test name/content intact after the move.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 45880543-fff5-40a6-a68b-ad61e521def4

📥 Commits

Reviewing files that changed from the base of the PR and between 4e025d3 and e3462af.

📒 Files selected for processing (12)

• amelia/core/types.py
• amelia/pipelines/implementation/graph.py
• amelia/pipelines/implementation/moa.py
• amelia/pipelines/implementation/routing.py
• amelia/pipelines/implementation/state.py
• amelia/pipelines/implementation/utils.py
• tests/unit/core/test_moa_config.py
• tests/unit/pipelines/conftest.py
• tests/unit/pipelines/implementation/test_state.py
• tests/unit/pipelines/test_generative_moa_aggregator_node.py
• tests/unit/pipelines/test_generative_moa_graph_wiring.py
• tests/unit/pipelines/test_generative_moa_proposers_node.py

[anderskev]

🔀 Merged: per-agent MoA options (CLI + dashboard)

Merged feat/agent-moa-options branch into this PR. Adds:

CLI

• amelia profile update --agent developer --moa-enabled --moa-proposer-count 3 --moa-proposer-models a,b
• Per-agent options['moa'] update via a new profile update CLI subcommand

Server

• Validates moa sub-config on agent settings routes via the shared MoAConfig

Dashboard

• MoA options panel in the Agents section of the profile form
• Toggle, proposer count, model list, isolation switch
• Tests for form dirty state tracking

Conflict resolution

• Removed duplicate MoAConfig (agent-options branch had a separate definition with isolation: bool)
• Unified on the pipeline MoAConfig (isolation: MoAIsolation, proposer_models: tuple)
• CLI and routes convert boolean isolation to \"worktree\" string for the pipeline model

Gate: 2743 passed, ruff clean, mypy clean, dashboard builds.

[anderskev]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.