pi-decision-router

Route Pi questions and confirmations to a child Pi agent with deterministic fallback and JSONL audit logging.

Packages

Package details

extensionskill

Install pi-decision-router from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-decision-router
Package
pi-decision-router
Version
0.3.0
Published
Aug 23, 2026
Downloads
463/mo · 326/wk
Author
eiei114
License
MIT
Types
extension, skill
Size
68.5 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.ts"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Pi Decision Router

CI Publish npm version npm downloads License: MIT Pi package Trusted Publishing

Route Pi questions and confirmations to a child Pi agent, then keep an audit trail.

What this is

pi-decision-router removes routine human-choice UI from unattended Pi runs. It registers one conflict-free canonical decision tool, adapts common question-tool shapes through Pi UI/event hooks, asks a tool-disabled child Pi for the decision, and falls back to the recommended option when the child is unavailable.

This is intentionally generic. It does not depend on gstack and does not modify gstack itself.

Features

  • Adapts question, questionnaire, ask_question, ask_user_question, and AskUserQuestion when their host exposes supported Pi UI/event hooks.
  • Auto-answers ctx.ui.select(), ctx.ui.confirm(), and ctx.ui.input() when the active Pi context can be patched.
  • Uses a child pi --print --no-tools process with strict JSON output.
  • Persists JSONL decisions outside the vault for auditability.
  • Never gives the child agent tools, extensions, skills, project context, or a session.
  • Uses recommended/default/positive options first, then the first option as a deterministic fallback.
  • Shows an ON/OFF status-bar toggle; run /decision-router-toggle and press Enter to switch it.
  • After a turn ends, warns and forces compaction at 95% context usage; 100% is treated as an emergency threshold.
  • Resumes an interrupted tool-driven task with a hidden follow-up after compaction, then lets Pi produce the final response.

Install

pi install npm:pi-decision-router

For local development:

pi -e C:/path/to/pi-decision-router/extensions/index.ts

Configuration

The package is enabled by default for unattended operation.

Variable Default Purpose
PI_DECISION_ROUTER_ENABLED 1 Set 0 to disable routing.
PI_DECISION_ROUTER_CHILD 1 Set 0 to skip the child and use fallback decisions.
PI_DECISION_ROUTER_AUTO_COMPACTION 1 Set 0 to disable the router's post-turn compaction trigger.
PI_DECISION_ROUTER_COMPACTION_THRESHOLD_PERCENT 95 Context percentage that triggers compaction after a turn.
PI_DECISION_ROUTER_COMPACTION_EMERGENCY_PERCENT 100 Emergency percentage; bypasses the one-compaction-per-cycle guard.
PI_DECISION_ROUTER_TIMEOUT_MS 45000 Child decision timeout.
PI_DECISION_ROUTER_MODEL current model Child Pi model pattern or ID.
PI_DECISION_ROUTER_PROVIDER current provider Child Pi provider.
PI_DECISION_ROUTER_PI_BIN auto Explicit Pi executable path.
PI_DECISION_ROUTER_AUDIT_LOG ~/.pi/agent/pi-decision-router/audit.jsonl JSONL audit path.

Useful commands:

/decision-router-status
/decision-router-log
/decision-router-toggle

The toggle switches Router Mode — routing and auto compaction together — and remembers the choice per project directory in ~/.pi/agent/pi-decision-router/state.json, so new sessions in the same directory restore it. An explicit PI_DECISION_ROUTER_ENABLED=0 (or PI_DECISION_ROUTER_AUTO_COMPACTION) still wins over the persisted state when Pi should start with a deterministic configuration.

Automatic compaction

Automatic compaction is enabled by default. At the end of a Pi turn, when ctx.getContextUsage() reports at least 95%, the extension shows a warning, starts compaction, and shows completion. At 100% it uses the emergency path, so the next completed turn is always eligible even if the previous high-context turn already armed a compaction cycle.

When the compacted turn contained tool calls or tool results, the extension queues a hidden followUp message after compaction. Pi then continues the interrupted work and produces the final response. A normal final assistant turn does not receive a duplicate response. Pi's native threshold compaction remains active too; the router adds an explicit post-turn 95%/100% trigger and does not change Pi's global compaction settings.

Runtime boundary

Pi's public extension API can intercept registered tool calls and patch the ctx.ui object supplied to active extension contexts. Multiple packages may already own the same question-tool name, so this package deliberately does not register duplicate aliases; it uses UI/event adapters instead. It cannot reliably replace an arbitrary third-party process, a browser dialog, or a UI call made before this extension is loaded. Unsupported question tools are left untouched instead of being silently blocked. When the toggle is OFF, supported UI adapters delegate back to Pi's native UI and the canonical decision tool is removed from Pi's active tool list.

Security

This package intentionally auto-approves routine decisions, including destructive confirmation dialogs, when configured for unattended use. The child agent runs without tools, but it still receives the question and a bounded recent-conversation excerpt. Review the package before installing it and protect the audit log.

See docs/usage.md for the decision contract and failure modes.

Development

npm install
npm run ci

Run the local extension in Pi:

pi -e .

Release

The package uses npm Trusted Publishing through GitHub Actions. No NPM_TOKEN is required.

npm version patch
git push

See docs/release.md.

Links

License

MIT