# Pi Decision Router

[![CI](https://github.com/eiei114/pi-decision-router/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-decision-router/actions/workflows/ci.yml)
[![Publish](https://github.com/eiei114/pi-decision-router/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-decision-router/actions/workflows/publish.yml)
[![npm version](https://img.shields.io/npm/v/pi-decision-router.svg)](https://www.npmjs.com/package/pi-decision-router)
[![npm downloads](https://img.shields.io/npm/dm/pi-decision-router.svg)](https://www.npmjs.com/package/pi-decision-router)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)

> 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

```bash
pi install npm:pi-decision-router
```

For local development:

```bash
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:

```text
/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`](docs/usage.md) for the decision contract and failure modes.

## Development

```bash
npm install
npm run ci
```

Run the local extension in Pi:

```bash
pi -e .
```

## Release

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

```bash
npm version patch
git push
```

See [`docs/release.md`](docs/release.md).

## Links

- npm: https://www.npmjs.com/package/pi-decision-router
- GitHub: https://github.com/eiei114/pi-decision-router
- Issues: https://github.com/eiei114/pi-decision-router/issues

## License

MIT