@sakiko233/pi-agent-fusion

Fixed-purpose multi-model Fusion workflows for Pi: fusion_reason, fusion_investigate, fusion_research, fusion_validate, and fusion_result, plus the /fusion and /fusion-models commands.

Each workflow runs three candidate models in parallel, anonymizes their answers, evaluates them blindly with a fourth model (with one bounded repair pass if the evaluator's JSON is invalid), and merges the result with a fifth. Every run is budget-admitted before a single child process exists, executes as one tracked background task, and commits durable, hash-verified artifacts you can audit after the fact.

Requirements

• Pi >= 0.84.2
• @sakiko233/pi-background-tasks v3 or newer, installed and enabled. pi-agent-fusion is an owner client of its external-task service: task identity, the footer dock, logs, cancellation, and the completion notification all belong to the background package. At session start this extension completes a versioned handshake with the one unique service; if the service is absent, duplicated, or incompatible, startup reports the dependency error and no Fusion tool or command is registered.
• Models reachable by child Pi processes. Routes are admitted only for the Anthropic and Codex subscription OAuth channels; metered API keys and other frontier channels are refused at launch.

Install

pi install npm:@sakiko233/pi-background-tasks
pi install npm:@sakiko233/pi-agent-fusion

Install order does not matter; enablement does. The handshake — not package presence — decides whether the Fusion surface exists in a session.

Tools

Tool	Purpose	Candidate context	Candidate tools
fusion_reason	Multi-model reasoning over the current conversation	Frozen projection of this session (visible text verbatim, tool activity as hash-accounted omission receipts)	none
fusion_investigate	Bounded read-only repository investigation	Clean task input you supply (objective, background, deliverable, optional scope/constraints)	read, grep, find, ls
fusion_research	Targeted public-URL research plus synthesis	Clean task input plus caller-declared sources	inspect tools + fusion_web_fetch
fusion_validate	Advisory read-only validation of completed work	Clean task input with structured verification	read, grep, find, ls
fusion_result	Retrieve a verified Fusion result	—	—

The evaluator, the repair pass, and the merger always run without tools. fusion_research fetches only the exact public http(s) URLs you declare — it is not web search, and there is no arbitrary browsing surface. Never put credentials, tokens, secrets, or private data into research URLs.

All four workflow tools return immediately after durable preflight (canonical input, omission ledger, and budget plan persisted; zero children launched yet) and appear once in the shared background dock. Wait for the terminal notification, then retrieve with fusion_result:

fusion_result({ taskId: "reason-<hex>" })

fusion_result never blocks. A running task returns a typed not-ready view. A completed task returns the merged answer only after manifest/result/merged identity, byte lengths, hashes, and UTF-8 are verified; usage attaches to the first successful retrieval exactly once. Failed or cancelled runs return a bounded, answer-free evidence view — never partial candidate, evaluator, merger, tool-result, or fetched-source bodies. Oversized answers are never truncated: they are delivered by artifact reference.

Commands

• /fusion <prompt> — start a Fusion reason run from the TUI or CLI. With no arguments in the TUI a multiline editor opens.
• /fusion-models — TUI-only five-slot model selector (three candidates, evaluator, merger). $current follows the session's current model. The configuration lives at ~/.pi/agent/fusion-models.json and is written atomically with a revision guard.

How a run works

1. Budget preflight — every stage prompt is forecast against per-route token accounting derived from real calibrated provider usage. A refusal here launches zero children and registers zero tasks.
2. Durable readiness barrier — artifacts and the budget plan are persisted and the background task is registered before the first candidate child exists.
3. Candidates — three children in parallel with fixed per-workflow tool policies, runtime guards, output caps, and same-session compression for oversized candidate output.
4. Blind evaluation — candidate order is shuffled with CSPRNG bytes; the evaluator sees anonymous answers only. One bounded repair pass runs only if the evaluator JSON is invalid.
5. Merge — a no-tool merger writes the final answer; for fusion_validate the merged report is rendered from the evaluator's deduplicated finding accounting.
6. Commit — merged answer, manifest, and usage are written durably; the background task settles and notifies.

Cancellation (from the dock or bg_kill) aborts the run, preserves terminal failure artifacts, and settles the task as killed. Session shutdown does the same.

Relationship to other packages

• @sakiko233/pi-background-tasks — required service: registry, dock, logs, cancellation, terminal notification.
• @sakiko233/pi-agent-runtime — shared audited primitives (canonical JSON, durable filesystem, child launch, context projection, token budgets, OAuth observation, Anthropic attribution). This package imports them; it never ships the attribution implementation itself.
• @sakiko233/pi-subagent — single-child delegation. It can run alongside this package; both share the one background task namespace while each interprets only its own result and artifact formats.

License

MIT, preserving upstream ISC notices for code extracted from pi-background-tasks. See THIRD_PARTY_NOTICES.md.