pi-moa

pi-moa is a Pi 0.80.6+ package that adds a local Mixture of Agents provider.

The default presets run tool-free advisors before the actor: once for an ordered plan, then once after each changed Pi tool-result batch for a PASS or REVISE checkpoint.

Model	Display name	Advisors	Acting model	Advisor output cap	Initial uncached requests
Fusion	Pi MoA Fusion	opencode-go:glm-5.2, opencode-go:kimi-k2.6	opencode-go:deepseek-v4-flash	8000	3
Fusion Fast	Pi MoA Fusion Fast	opencode-go:glm-5.2	opencode-go:mimo-v2.5	8000	2

Use it when coding or debugging benefits from an independent plan and evidence-based checkpoints. Each changed tool-result context adds one parallel advisor batch before the next actor request; identical contexts reuse cached guidance.

See CHANGELOG.md for release history and compatibility notes.

What's new in 0.4.3

• /pi-moa now opens a TUI menu for status and authenticated Fusion/Fusion Fast model-slot changes.
• Uncached advisor plan/checkpoint requests appear in Pi's transient working row.
• Fusion now uses opencode-go:glm-5.2 and opencode-go:kimi-k2.6 as advisors; Fusion Fast now acts with opencode-go:mimo-v2.5.
• The provider, not the actor, obtains an ordered plan before work and runs a PASS/REVISE checkpoint after every changed Pi tool-result batch.
• Identical plan/checkpoint contexts are cached; only newly executed advisor usage is charged. Diagnostics expose safe stage, cache, degradation, and failure-category data instead of raw advisor errors.
• Node 22.19.0+ is required, and retired or unknown configuration keys now fail with value-free migration guidance.

Install

pi install npm:@duyviet1804/pi-moa

Pinned version:

pi install npm:@duyviet1804/pi-moa@0.4.3

From git or a local checkout:

pi install git:github.com/duyviet1804/pi-moa
pi install ./path/to/pi-moa

Authentication

Fusion requires:

• opencode-go:glm-5.2;
• opencode-go:kimi-k2.6;
• opencode-go:deepseek-v4-flash.

Fusion Fast keeps the OpenCode Go-only default:

• opencode-go:glm-5.2;
• opencode-go:mimo-v2.5.

Run /login in Pi and authenticate OpenCode Go, or use its supported environment variable:

export OPENCODE_API_KEY="..."

Authenticate every provider referenced by the selected preset or a custom config. Never put credentials in MoA JSON or committed files.

Usage

pi --provider pi-moa --model Fusion
pi --provider pi-moa --model "Fusion Fast" --thinking high

Use Fusion Fast:high for daily work and Fusion for harder tasks. Advisors are capped at high for xhigh/max; MiMo V2.5 also clamps max to high.

After a successful iteration, Pi's footer shows MoA <n> tok/s: acting-model output divided by the complete advisor-plus-actor elapsed time for that iteration.

In TUI mode, /pi-moa opens an action menu for status or changing any Fusion/Fusion Fast advisor or actor slot. RPC, JSON, and print modes continue to show status immediately without opening a dialog.

Configuration

Each model reads its own optional file:

Model	File
Fusion	~/.pi/agent/moa.json
Fusion Fast	~/.pi/agent/moa-fast.json

PI_CODING_AGENT_DIR replaces ~/.pi/agent when set. Missing files use built-in defaults; invalid files fail loudly and are never overwritten by the menu.

The model picker lists only currently available/authenticated opencode-go and openai-codex models. A selection writes the corresponding file above; cancelling either menu writes nothing. Run /reload after changing an actor so model-picker metadata follows the new actor.

Start from the shipped examples instead of copying defaults from this README:

• pi-moa.example.json
• pi-moa-fast.example.json

mkdir -p ~/.pi/agent
cp pi-moa.example.json ~/.pi/agent/moa.json
cp pi-moa-fast.example.json ~/.pi/agent/moa-fast.json

Field	Required	Meaning
referenceModels	yes	Non-empty advisor model list; each entry needs provider and model.
aggregator	yes	Acting model that receives the advisor plan/checkpoint and retains normal Pi tools.
referenceTemperature	yes	Advisor temperature when supported; omitted for openai-codex.
aggregatorTemperature	yes	Acting-aggregator temperature when supported; omitted for openai-codex.
referenceMaxTokens	yes	Positive output-token limit for each advisor.
maxToolResultChars	no	Per-tool-result truncation limit; default 6000.
maxAdvisorContextChars	no	Total advisor-context limit; default 20000.

After editing either file manually, run /reload so model-picker metadata follows the configured aggregator.

Upgrading

From 0.3.0

Valid 0.3.0-shaped configs need no field migration, but an override keeps the model slots it names. Remove it or start from the shipped examples to adopt the new defaults, then run /reload.

The new provider-enforced plan/checkpoint loop applies to custom configs too. Advisor latency and usage now grow with changed Pi tool-result batches; identical contexts are cached.

From 0.2.9 or older

Migrate an override to the current fields shown in the shipped examples, or back up and remove moa.json / moa-fast.json to use built-in defaults. Retired and unknown fields are rejected without printing their values.

How it works

1. Before the first actor request in a user turn, configured advisors run in parallel and return an ordered plan, acceptance criteria, and checks.
2. The actor receives that plan and works on the next unfinished item with normal Pi tools.
3. After each changed Pi tool-result batch, advisors review the original plan plus sanitized new evidence before the actor continues.
4. Any supported REVISE or malformed verdict keeps the actor on the current item. All successful advisors must return PASS to progress; COMPLETE allows finalization.
5. Repeated identical contexts reuse their advisor batch. Parallel sibling tool results form one checkpoint boundary.

While an uncached advisor batch runs, Pi's working row shows whether pi-moa is getting a plan or checkpoint; cache hits add no delay or notice.

Tasks that need no tools receive the initial plan but no checkpoint. If every advisor fails, the actor receives stable failure categories and an explicit self-check instruction instead of raw errors. Cancellation remains fail-closed before actor startup.

Only newly executed advisor usage is charged to the matching virtual-model assistant message. The pi-moa.advisor diagnostic contains only stage, cacheStatus, degradation state, and stable failure categories—never advisor output, raw provider errors, credentials, or tool arguments.

Task guidance

For coding work, advisors and the acting model use generic task-derived checks:

• derive acceptance criteria from the request and repository contract;
• inspect relevant source, tests, and tool evidence;
• prefer the smallest compatible existing or standard-library solution;
• preserve API and data invariants;
• consider failure, concurrency, mutation, and ordering only when relevant;
• run requested tests plus one focused risk check, then stop.

Runtime prompts intentionally contain no benchmark-specific expected fixes or hidden-test vocabulary.

Maintenance

pi update npm:@duyviet1804/pi-moa
pi remove npm:@duyviet1804/pi-moa

If configuration fails, fix the JSON or remove it to restore defaults:

rm ~/.pi/agent/moa.json ~/.pi/agent/moa-fast.json

If a configured model is missing, inspect Pi's catalog:

pi --list-models

Package contents

package.json
README.md
CHANGELOG.md
LICENSE
extensions/pi-moa.ts
src/moa-core.ts
pi-moa.example.json
pi-moa-fast.example.json

See test/README.md for the capability-v3 benchmark, isolation boundary, metrics, and no-live gate.

Security

• Inner-model credentials are resolved per request through Pi's model registry and never copied into prompts or diagnostics; advisor errors are reduced to stable categories before the actor sees them.
• Wrapper-provider API keys, headers, and environment values are discarded; only credentials resolved for the selected inner model are forwarded.
• Advisor contexts omit image bytes, hidden thinking, assistant draft text, and normal tool arguments.
• The npm allowlist excludes local config, authentication, sessions, and environment files.
• Pi extensions run with local user permissions; install only trusted packages.

License

MIT