# πŸ“¦ @goodandready/dsh-moa

Mixture of Agents (MoA) Multi-Model Collaboration & Synthesis Engine for DeepSeek Harness

npm version license DSH Plugin Node version

GoodAndReady Showcase

πŸ‡¬πŸ‡§ English β€’ πŸ‡·πŸ‡Ί Русский β€’ πŸ‡¨πŸ‡³ δΈ­ζ–‡θ―΄ζ˜Ž

⭐ If you like this plugin, please star it on GitHub β€” it shows me that the plugin is useful to you and motivates me to keep developing it.

πŸ› If you find a bug or would like to request a feature, open a GitHub issue in any language β€” I will review your proposal and implement useful suggestions in a future plugin version.
--- ## ⚑ 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/`). 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. 11. **Interactive Workbench (File Scoring 1–10, User Pick & Mix, Top-Model Glue & Judge Re-Check)**: Judge scores each candidate file (1–10) with pros and cons. Users can mix and match files across proposals in the WebUI. The turn's top-performing reference model harmonizes cross-file imports and contracts, followed by a final judge re-audit before promotion. Companion integration with [`dsh-time-machine`](https://github.com/goodandready/dsh-time-machine) for safe pre-promotion rollback checkpoints. --- ## πŸ—οΈ Architecture ```mermaid graph TD subgraph Input ["User Interaction (Chat Composer)"] Cmd["Slash Command: /moa [preset] <prompt>"] Gate{"Ambiguity Check & Questionnaire"} QModal["Interactive Clarifying Questions
(Options & Write-in responses)"] end subgraph Proposers ["Parallel Proposer Layer (Advisors)"] P1["Proposer Model 1
(Creative Approach)"] P2["Proposer Model 2
(Alternative Design)"] P3["Proposer Model 3
(Performant Strategy)"] WS1[".moa/candidate-1/
(Isolated Files)"] WS2[".moa/candidate-2/
(Isolated Files)"] WS3[".moa/candidate-3/
(Isolated Files)"] end subgraph Judge ["Synthesis & Promotion Layer"] Aggregator["Frontier Judge Model
(Cross-Evaluation & Code Critique)"] WinnerMarker{"WINNER_CANDIDATE_INDEX"} Promote["Promote Winner Files
(Move to project root & cleanup sandboxes)"] Summary["Token-Saving Summary
(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: ```text /moa build a real-time reactive dashboard with charts and websocket updates ``` Or target a specific named preset: ```text /moa code-review audit the auth middleware and security boundaries ``` The flag form is equivalent: ```text /moa --preset=deep-reasoning solve this math problem step by step ``` Or promote a candidate solution directly (by candidate index or runId + candidate index): ```text /moa promote 2 /moa promote 2 ``` ### 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 is blocked (fail-closed) to protect uncheckpointed workspace files against unintended overwrites (override with `force: true` only when automated checkpoints are explicitly unneeded). ### 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 under Node.js native permission model (`--permission`) and an ephemeral runtime fence (`lib/moa-sandbox.js`). Without OS-level container isolation (bubblewrap), child process execution is strictly prohibited (`--allow-child-process` is omitted) to prevent candidate scripts from stripping `NODE_OPTIONS` and escaping sandbox restrictions (#260). Package manager commands (`npm test`, `pnpm test`) are resolved directly to underlying `package.json` test scripts, while any evasion patterns (`env -u NODE_OPTIONS`, `unset NODE_OPTIONS`, computed shell evasion) are detected and fail-closed prior to execution. 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. Upfront and runtime phase guards account for candidate generation, multi-judge panel voting, and downstream synthesis prompt overhead including custom evaluation criteria (`judge_criteria`). Mode `trim` automatically reduces the candidate pool to fit the budget, while `abort` cancels execution before token consumption. In abort payloads, all panel and candidate token metrics are fully preserved. ### 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, timeouts, or rate limits (429/500) automatically recover using configured local models (Ollama / MiniPC). Each fallback model operates with an independent execution budget and an isolated controller linked to the parent turn signal, preventing cloud timeouts from starving fallback models. Additionally, terminal errors and aborted streams are strictly classified, ensuring reliable error propagation and failover. ### 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/`) 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: ```bash 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 | `:` | Optional | Off | | `code-review` | Thorough peer review & vulnerability detection | `:` | On | On | | `fast-audit` | Ultra-fast single-model audit (Fast Mode) | `:` | Off | Off | | `deep-architect` | Distributed systems & complex architectures | `:` | On | Off | | `bug-hunter` | Root cause discovery & adversarial edge cases | `:` | On | Off | | `refactor-cleanup` | Dead-code pruning & standard-library simplicity | `:` | Off | Off | | `frontend-ui` | High-fidelity responsive web interfaces | `:` | Off | Off | | `security-audit` | Zero-trust threat analysis & sanitization | `:` | On | On | | `math-logic` | Deterministic algorithmic proofs & math logic | `:` | On | Off | | `creative-brainstorm`| Divergent lateral thinking & ideation | `:` | 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 ` 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): ```yaml # 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 ` without an explicit preset | | `presets` | `array` | `[...]` | Named presets; selected via `/moa ` or `/moa --preset= ` | | `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 > [!IMPORTANT] > **Authentication & Access Control**: All HTTP endpoints enforce fail-closed authentication via the DeepSeek Harness Connection Service (`ctx.connection.requestRejection`). Unauthenticated remote callers over LAN/WAN receive HTTP 401 (`Authentication required`) or 403 (`Forbidden`), strictly preventing disclosure of prompts, workspace structures, and candidate files. Mutation endpoints additionally require loopback origin and CSRF validation (`sec-fetch-site`). | 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/` | `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: ```bash npm test ``` --- ## πŸ› οΈ Internal Tooling & Development For local verification and package integrity validation: - `npm test`: runs the full test suite (294 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](https://github.com/GooDAnDReaDY)