GooDAnDReaDY/dsh-moa

---

⚡ Overview & The Problem

Single-model AI generation often suffers from blind spots, single-perspective biases, hallucinated architectural choices, and inconsistent code quality on challenging engineering tasks. When prompted with ambiguous or complex specifications, a single model may make premature assumptions and produce monolithic, unvetted implementations.

@goodandready/dsh-moa brings the Mixture of Agents (MoA) architecture natively to DeepSeek Harness via the /moa slash command:

1. Adaptive Clarification Questionnaire: For broad or underspecified prompts, advisor models formulate clarifying options and the judge synthesizes a structured 2–4 question questionnaire before generating code.
2. Parallel Proposers Fan-Out & Workspace Isolation: Multiple independent models evaluate the prompt concurrently. Each candidate's proposed files are written to isolated disk sandboxes (.moa/candidate-N/), avoiding cross-pollution.
3. Frontier Judge Evaluation & File Promotion: A flagship reasoning model critically benchmarks all proposals, selects the winning candidate via machine markers (WINNER_CANDIDATE_INDEX: N), and promotes the winner's files directly into the project root directory.
4. Token-Saving Chat Summarization: Replaces massive code dumps in chat bubbles with compact file listings and clean architectural summaries.
5. One-Shot Session Model Restoration: Executes cleanly as a one-shot turn modifier, automatically reverting back to the user's primary session model immediately after completion.
6. Dynamic Model Pricing Catalog & Token Estimation: Real-time rate resolution for 300+ models fetched automatically in the background from OpenRouter's public catalog (cached locally in ~/.dsh/storages/dsh-moa-catalog.json for 24h), plus support for direct vendor rates and custom prices overrides in settings.yaml.
7. Refinement Mode (Incremental Edits): Automatically detects existing codebase context to generate precise delta modifications instead of destructive full-file rewrites.
8. Fast Mode & Custom Judge Criteria: Ultra-fast single-model preset for quick tasks and customizable evaluation guidelines for the judge.
9. Run History & Win-Rate Leaderboard: Persistent logging of every run kind (synthesis, fast mode, questionnaire) with built-in REST endpoints (/dsh-moa/history, /dsh-moa/leaderboard, /dsh-moa/runs/<id>).
10. Live Canvas 1-Click Preview (optional): when the @goodandready/dsh-live-canvas plugin is installed in the same profile, the promoted HTML is pushed to its sandbox and the MoA answer carries a one-click preview link; without it the step is skipped silently.

---

🏗️ Architecture

graph TD
    subgraph Input ["User Interaction (Chat Composer)"]
        Cmd["Slash Command: /moa [preset] <prompt>"]
        Gate{"Ambiguity Check & Questionnaire"}
        QModal["Interactive Clarifying Questions<br/>(Options & Write-in responses)"]
    end

    subgraph Proposers ["Parallel Proposer Layer (Advisors)"]
        P1["Proposer Model 1<br/>(Creative Approach)"]
        P2["Proposer Model 2<br/>(Alternative Design)"]
        P3["Proposer Model 3<br/>(Performant Strategy)"]
        WS1[".moa/candidate-1/<br/>(Isolated Files)"]
        WS2[".moa/candidate-2/<br/>(Isolated Files)"]
        WS3[".moa/candidate-3/<br/>(Isolated Files)"]
    end

    subgraph Judge ["Synthesis & Promotion Layer"]
        Aggregator["Frontier Judge Model<br/>(Cross-Evaluation & Code Critique)"]
        WinnerMarker{"WINNER_CANDIDATE_INDEX"}
        Promote["Promote Winner Files<br/>(Move to project root & cleanup sandboxes)"]
        Summary["Token-Saving Summary<br/>(File overview & architecture highlights)"]
    end

    Cmd --> Gate
    Gate -->|Broad/Underspecified| QModal
    QModal -->|User Answers| P1 & P2 & P3
    Gate -->|Explicit/Detailed| P1 & P2 & P3
    P1 --> WS1
    P2 --> WS2
    P3 --> WS3
    WS1 & WS2 & WS3 --> Aggregator
    Aggregator --> WinnerMarker
    WinnerMarker --> Promote
    Promote --> Summary

---

✨ Features & Capabilities

1. Slash Command (/moa) & Autocompletion

Integrated directly into the DeepSeek Harness composer via client input triggers. Typing /moa shows presets and instant autocompletion:

/moa build a real-time reactive dashboard with charts and websocket updates

Or target a specific named preset:

/moa code-review audit the auth middleware and security boundaries

The flag form is equivalent:

/moa --preset=deep-reasoning solve this math problem step by step

2. Adaptive Questionnaire Gate

When prompts are open-ended or lack architectural specifications (e.g. "build a calculator app"), advisor models detect ambiguities and formulate focused clarifying questions (e.g., UI style, persistence backend, framework choice) before generating code.

3. Parallel Fan-Out with Live Heartbeats

• Proposers query concurrently with live heartbeat progress badges (⏳ [3s] Processing..., per-model completion status).
• Bulky system prompts and tool schemas are cleanly stripped from advisor contexts, eliminating "missing tools" refusals and token bloat.

4. Disk-Level Candidate Isolation & Promotion

Unlike standard chat-only MoA, dsh-moa isolates file generation onto the filesystem:

• Each proposer generates files into .moa/candidate-1/, .moa/candidate-2/, etc.
• The Judge compares implementations and selects the optimal solution with WINNER_CANDIDATE_INDEX: N.
• The winner's files are promoted to the workspace root, and temporary candidate directories are pruned automatically.

5. Native Settings Card & Presets

Configure your models in Settings → Plugins → Mixture of Agents:

• Set custom Proposer models (e.g., fast generative models for diverse ideas).
• Set the Aggregator / Judge model (e.g., deep reasoning models for rigorous critique).
• Configure named presets (default, fast, deep-reasoning), judge criteria and temperatures.
• Enable or disable MoA and see the real host status chip; the telemetry grid shows total runs and average run cost.

7. Candidate Diff Viewer

Inspect line-by-line differences between candidate proposals and the curator's synthesized deliverable directly in the UI. Features file selection, delta line highlights (added, removed, same), and unified diff rendering via a zero-dependency in-memory LCS algorithm.

8. Pre-Promotion Git Checkpoints (dsh-time-machine)

Before promoting any winning candidate files over the workspace root, dsh-moa invokes the local dsh-time-machine service to create a shadow Git checkpoint (moa-pre-promotion: candidate-N). If dsh-time-machine is absent or unreachable, file promotion proceeds seamlessly via best-effort fallback.

9. Automated Test Execution Gate

When test_gate_enabled: true and test_command (e.g. npm test or pytest) are configured, candidate code is executed in an ephemeral sandbox overlay. The judge receives concrete test outcomes, durations, and output logs to ground decisions in objective verification.

10. Multi-Judge Panel & Consensus Voting

When multi_judge_enabled: true, candidate solutions are independently evaluated by a panel of judge models. Winner selection supports majority, highest_score, or unanimous consensus strategies.

11. Composite Hybrid Synthesis (AST / Block Merge)

When composite_merge_enabled: true, the aggregator assembles a modular hybrid: combining the strongest core logic from one model, robust error handling from another, and complete types/tests from a third.

12. Smart Dynamic Preset Router & LLM Classifier

When invoking /moa without explicit preset flags, the router classifies prompt intent using keyword heuristics or a zero-shot router model (smart_routing_model) to automatically select the optimal preset.

13. Real-Time Live Cost Counter & Streaming Ticker

As each candidate completes, live token counts and USD costs are streamed directly into the chat based on catalog pricing and vendor rates.

14. Cost Budget Guardrails (Trim & Abort Modes)

budget_guard_enabled and max_budget_usd guard against accidental spend. Mode trim automatically reduces the candidate pool to fit the budget, while abort cancels execution before token consumption.

15. Temperature Gradient Exploration & Per-Candidate Temperature

Supports individual candidate temperatures (slot.temperature) and temperature_gradient_enabled to distribute temperatures (0.2 → 0.9) across candidates for maximum architectural diversity.

16. Multi-Turn Conversation Memory & Context Pruning

Seamlessly retains synthesized baseline code from prior turns while pruning intermediate noise to keep token overhead low.

17. Automated Benchmark & Post-Mortem PR Reports

report_generation_enabled generates comprehensive Markdown & JSON reports detailing candidate metrics, agreement scores, test gate results, and cost breakdowns via GET /dsh-moa/runs/:id/report.

18. Graceful Degradation & Local Fallback Resilience

When local_fallback_enabled: true, candidates that fail due to network outages or rate limits (429/500) automatically recover using configured local models (Ollama / MiniPC).

6. Live Canvas 1-Click Preview (optional)

If @goodandready/dsh-live-canvas is installed in the same profile, dsh-moa pushes the promoted HTML file to the Live Canvas REST contract (POST /dsh-live-canvas/api/preview, served by the same harness webServer) and appends a one-click preview link (/dsh-live-canvas/sandbox/<id>) to the answer. Without the plugin the step is skipped silently — no errors in the log, no dead links.

---

📦 Installation

Install into your DeepSeek Harness web profile:

dsh plugin --profile web add @goodandready/dsh-moa

Restart your DeepSeek Harness instance and refresh the browser.

---

⚡ 10 Specialized Built-in Presets & Candidate Personas

v0.2.13 introduces 10 ready-to-use presets engineered for real-world software workflows:

Preset Name	Purpose	Default Aggregator	Peer Critique	Blind Eval
default	Balanced multi-model generation	<provider>:<model>	Optional	Off
code-review	Thorough peer review & vulnerability detection	<provider>:<model>	On	On
fast-audit	Ultra-fast single-model audit (Fast Mode)	<provider>:<model>	Off	Off
deep-architect	Distributed systems & complex architectures	<provider>:<model>	On	Off
bug-hunter	Root cause discovery & adversarial edge cases	<provider>:<model>	On	Off
refactor-cleanup	Dead-code pruning & standard-library simplicity	<provider>:<model>	Off	Off
frontend-ui	High-fidelity responsive web interfaces	<provider>:<model>	Off	Off
security-audit	Zero-trust threat analysis & sanitization	<provider>:<model>	On	On
math-logic	Deterministic algorithmic proofs & math logic	<provider>:<model>	On	Off
creative-brainstorm	Divergent lateral thinking & ideation	<provider>:<model>	Off	Off

Candidate Personas (role_persona)

Assign archetypal engineering mentalities to individual candidate slots to ensure genuine perspective divergence:

• minimalist (Ponytail Senior): standard library first, zero external dependencies, minimal moving parts.
• robustness: defensive coding, boundary validation, graceful fallback handling, idempotent operations.
• performance: algorithmic complexity minimization, memory efficiency, zero-copy operations.
• tester: test-driven methodology, high branch coverage, explicit assertion design.
• general: balanced standard engineering approach.

---

🤝 Consilium Round 2 (Peer Critique) & Syntax Auto-Fix Gate

• Consilium (Round 2): Enable peer_critique_enabled: true in preset settings. Each candidate receives peer proposals and submits an improved, hardened iteration before judge evaluation.
• Syntax Pre-Check Gate: In-memory JS/MJS and JSON syntax verification runs automatically on all candidate files. If a proposal contains syntax errors, it is flagged with [⚠️ Syntax Warning] and the judge receives a strict mandate: if this candidate has superior design, auto-correct the syntax in the synthesized deliverable and award them the win.
• User Candidate Override: Enable allow_candidate_override: true to preserve candidate sandboxes in .moa/candidate-N/. At any time, promote any candidate using /moa promote <runId> <candidateIndex> or the UI button.

---

⚙️ Configuration (settings.yaml)

Configure presets and model pipelines in settings.yaml or through the Web UI Settings panel (Settings → Plugins → Mixture of Agents):

# settings.yaml
dsh-moa:
  enabled: true
  default_preset: "default"
  prices:
    "my-provider/my-model":
      input: 0.20
      output: 0.80
    "ollama/*":
      input: 0
      output: 0
  presets:
    - name: default
      ask_clarifying_questions: true
      reference_models:
        - provider: "your-fast-provider"
          model: "your-creative-model"
        - provider: "your-fast-provider"
          model: "your-balanced-model"
      aggregator:
        provider: "your-reasoning-provider"
        model: "your-judge-model"
      reference_temperature: 0.6
      aggregator_temperature: 0.4
      max_tokens: 4096
      judge_criteria: ""
    - name: fast
      ask_clarifying_questions: false
      reference_models:
        - provider: "your-fast-provider"
          model: "your-fast-model"
      aggregator:
        provider: "your-fast-provider"
        model: "your-fast-model"

Configuration Parameters

Parameter	Type	Default	Description
enabled	boolean	true	Master switch for the /moa command, turn routing and POST /dsh-moa/run (editable in the settings card)
default_preset	string	"default"	Preset invoked when typing /moa <prompt> without an explicit preset
presets	array	[...]	Named presets; selected via /moa <name> <prompt> or /moa --preset=<name> <prompt>
presets[].reference_models	array	[...]	Proposer models queried concurrently during the proposal phase
presets[].aggregator	object	{...}	Judge model responsible for synthesis, critique, and winner selection
presets[].ask_clarifying_questions	boolean	true	Synthesize a clarifying questionnaire for broad/underspecified prompts (per preset)
presets[].curator_synthesis	boolean	false	Curator mode: evaluates strongest parts across candidates using the antipatterns rubric and advises an assembler model
presets[].stream_aggregator	boolean	true	Stream judge/aggregator tokens live in real-time with zero TTFT wait
presets[].quorum_enabled	boolean	false	Straggler mitigation: proceed with synthesis once >= 60% candidates respond
presets[].grace_period_sec	number	10	Grace period in seconds to wait for stragglers after quorum is reached
presets[].aggregator_fallbacks	array	[]	Ordered fallback judge models tried if primary aggregator encounters transient errors
presets[].blind_evaluation	boolean	false	Anonymize candidate model names for the judge/curator to eliminate family/brand bias
presets[].reference_timeout_sec	number	60	Per-candidate execution timeout in seconds
presets[].aggregator_timeout_sec	number	180	Aggregator/judge synthesis timeout in seconds
presets[].reference_temperature / .aggregator_temperature	number	0.6 / 0.4	Sampling temperatures for proposers and judge
presets[].max_tokens	number	4096	Max output tokens per model call
presets[].judge_criteria	string	""	Optional extra evaluation criteria passed to the judge
prices	map	{}	Custom USD-per-1M-token rates ("provider/model", "provider/*", "*") applied to cost estimation

Privacy note: in refinement mode, readable project files (up to ~16k characters; dotfiles such as .env* are excluded) are included in the prompts sent to the configured candidate and judge providers. Avoid running /moa in projects whose non-dotfile files contain secrets.

---

📊 REST API & Endpoints

Endpoint	Method	Description
/dsh-moa/status	GET	Health/enablement snapshot used by the settings card status chip
/dsh-moa/presets	GET	Returns the configured MoA presets and default preset
/dsh-moa/presets	POST	Replaces presets/default preset/enabled after schema validation (400 on invalid payload)
/dsh-moa/models	GET	Lists models available for candidate/judge slots
/dsh-moa/history?limit=20&offset=0	GET	Returns recent MoA runs with candidates, winner, cost, and tokens
/dsh-moa/leaderboard	GET	Computes model win-rate leaderboard and average execution costs
/dsh-moa/runs/<id>	GET	Returns a single recorded run by id
/dsh-moa/run	POST	Runs the full MoA pipeline over HTTP (400 when enabled: false)
/dsh-moa/diff	GET	Computes line-by-line diff between candidate runs or curator synthesis
/dsh-moa/promote	POST	Manually promotes candidate workspace files to project root
/api/dsh-moa/update	POST	One-click plugin updater from npm with safe-write verification

---

🧪 Testing

Run the automated test suite:

npm test

---

🛠️ Internal Tooling & Development

For local verification and package integrity validation:

• npm test: runs the full test suite (95 tests)
• ./deploy.sh: local infrastructure validation script (verifies package size, identity parity in package.json/cordis.patch.yml/client.js, and tests). Excluded from the published npm package.

📄 License

MIT © GooDAnDReaDY