@zhcsyncer/pi-consult

简体中文

A second-opinion primitive for the Pi coding agent. The main model calls consult({ why }); an advisor model with no tools answers recommend / confirm / revise / stop. A watchdog can force that call after repeated failures. Optional dual-path panel. Local behavior log.

This package is also included in @zhcsyncer/pi-extensions.

Source

New package. Side-call, inventory prefix, and active-tool reconcile are adapted from MIT-licensed @juicesharp/rpiv-advisor 2.8.0. The tool is consult (required why), configuration is a panel array, and this package adds a watchdog, budgets, and a local jsonl log. It is not a fork.

Features

• consult({ why }) forwards the current session to the configured advisor. The advisor has no tools and no user-visible output.
• Proactive Consult is limited to explicit advisor requests, consequential unresolved structural choices, or genuinely stuck approaches. Decided, reversible, mechanical, and direct-assessment work proceeds without Consult; rejecting advice with evidence is valid.
• Unconfigured panel unloads the tool. Off costs nothing.
• Watchdog: after N identical tool calls or N consecutive errors, steer the model to consult first. The default threshold is 5; completing Consult clears the prior evidence.
• /consult picks panel models and effort and toggles the watchdog. /consult status opens a temporary dashboard for budget and recent activity without adding anything to the transcript.
• Advisor summaries follow the language of the user's latest substantive request while preserving technical syntax. Expanded results render Markdown; collapsed rows remain clean one-line previews.
• Waiting rows stream connecting / thinking / writing and an approximate ~out count. Completed expanded rows and the status dashboard show exact input, output, and total tokens only.
• Full advisor usage still includes retries, fanout, cache reads/writes, and cost and is attached to the Consult tool result for Pi/pi-meter accounting; cache and cost stay out of the Consult UI.

Install

Standalone:

pi install npm:@zhcsyncer/pi-consult

Or install the whole extension bundle:

pi install npm:@zhcsyncer/pi-extensions

Try without installing:

pi -e npm:@zhcsyncer/pi-consult

Requires Pi 0.86 or later. Then restart Pi or run /reload. Use /consult to choose an advisor model. Until a panel is set, consult is not in the active tools.

Commands

After each consult result, the next visible reply should add:

CONSULT-LOG: adopt | changed: <reason>
CONSULT-LOG: adopt | confirmed: <reason>
CONSULT-LOG: reject | <reason>

The line remains normal assistant output and its decision is also mirrored under the matching Consult row. The TUI distinguishes streamed connecting / thinking / writing, advisor verdicts, policy blocked, request failed, and user cancelled states.

Configuration

Global file: $PI_CODING_AGENT_DIR/extension-data/pi-consult/config.json (normally ~/.pi/agent/extension-data/pi-consult/config.json).

{
  "panel": [{ "model": "anthropic/claude-fable-5", "effort": "high" }],
  "fanout": false,
  "gates": { "watchdog": 5 },
  "budget": { "perRun": 3, "perSession": 8 },
  "disabledForModels": []
}

Empty panel keeps the tool unloaded. fanout: true asks the whole panel on an on-demand consult(); the watchdog always uses the first advisor only. perRun spans one real user input through all following model/tool rounds; the next user input resets it. Budgets count started advisor requests, including attempts that later fail or are cancelled. Legacy perTurn is accepted as an alias. Behavior log: $PI_CODING_AGENT_DIR/extension-data/pi-consult/events.jsonl. Each call records session + toolCallId, outcome, trigger, verdict, usage, and the later changed / confirmed / rejected effect for transcript-linked retrospective analysis.

License

MIT

Side-call helpers are adapted from MIT-licensed @juicesharp/rpiv-advisor 2.8.0.