📦 @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

Or promote a candidate solution directly (by candidate index or runId + candidate index):

/moa promote 2
/moa promote <runId> 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. The test sandbox uses process containment fences and path validation to block unauthorized host file access and computed shell evasion (base64/eval/pipes), while allowing safe HTTP route literals. 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/<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:

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

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

🧪 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