mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
129 lines
8.7 KiB
Markdown
129 lines
8.7 KiB
Markdown
# @mzwing/pi-permission-auto-review
|
|
|
|
[](https://www.npmjs.com/package/@mzwing/pi-permission-auto-review) [](https://github.com/mzwing/pi-packages/actions/workflows/release.yml) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://github.com/earendil-works/pi)
|
|
|
|
A [Pi](https://github.com/earendil-works/pi) extension that adds Codex-style automatic permission reviews to [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system).
|
|
|
|
> **my-pi maintenance note:** This directory was imported from the upstream source tag `@mzwing/pi-permission-auto-review@0.2.0` at commit `8d196e4ef0884cac8326c366191dad3f585d470a`. It is loaded from source and maintained directly by my-pi, like `pi-rtk-optimizer`; npm `dist` output is not used. The local compatibility baseline is Node.js 22.19+, Pi 0.84.x, and `@gotgenes/pi-permission-system` 26.2.x.
|
|
|
|
## Differences between `@gotgenes/pi-permission-model-judge`
|
|
|
|
[@gotgenes/pi-permission-model-judge](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge) is a general-purpose model-based authorizer that can be used to evaluate any permission request.
|
|
|
|
Ours is mostly specialized for OpenAI's `codex-auto-review` model, which is trained to evaluate permission requests in the context of a coding assistant. Our extension aims at providing Codex-style automatic permission reviews for Pi's coding agent.
|
|
|
|
The bundled baseline is a Pi-specific adaptation of OpenAI Codex Guardian's [`policy_template.md`](https://github.com/openai/codex/blob/c4f42d161ae44a8d696ee9fb595709661979d187/codex-rs/core/src/guardian/policy_template.md) and [`policy.md`](https://github.com/openai/codex/blob/c4f42d161ae44a8d696ee9fb595709661979d187/codex-rs/core/src/guardian/policy.md) at revision [`c4f42d161ae44a8d696ee9fb595709661979d187`](https://github.com/openai/codex/commit/c4f42d161ae44a8d696ee9fb595709661979d187). It is bundled at build time; the extension never fetches policy text while reviewing an action.
|
|
|
|
## Install
|
|
|
|
The my-pi root package loads `pi-permission-auto-review/index.ts` directly and installs its runtime dependencies. Do not install the upstream npm package separately, or the same authorizer may be registered twice.
|
|
|
|
For isolated source development, install this directory's development dependencies and run it through the local entry point:
|
|
|
|
```bash
|
|
npm install
|
|
pi -e ./index.ts
|
|
```
|
|
|
|
This maintained source variant uses Pi's current `ModelRegistry.getProvider()` API directly and does not depend on `@mzwing/pi-polyfill`.
|
|
|
|
## Enable
|
|
|
|
Add `"auto-review"` to pi-permission-system's config:
|
|
|
|
```json
|
|
{
|
|
"authorizerChain": ["auto-review"]
|
|
}
|
|
```
|
|
|
|
The config is normally located at `~/.pi/agent/extensions/pi-permission-system/config.json`.
|
|
|
|
Extension config can be omitted. The defaults are:
|
|
|
|
```json
|
|
{
|
|
"provider": "openai-codex",
|
|
"model": "codex-auto-review",
|
|
"reasoning": "low",
|
|
"timeoutMs": 90000,
|
|
"includeBaselinePolicy": true
|
|
}
|
|
```
|
|
|
|
`codex-auto-review` is an official hidden model. The extension derives it from Pi's `openai-codex` provider and reuses the existing Codex login.
|
|
|
|
## Configuration
|
|
|
|
| Scope | Path |
|
|
| ------- | -------------------------------------------------------------- |
|
|
| Global | `~/.pi/agent/extensions/pi-permission-auto-review/config.json` |
|
|
| Project | `<cwd>/.pi/extensions/pi-permission-auto-review/config.json` |
|
|
|
|
Project fields override global fields. `PI_CODING_AGENT_DIR` replaces `~/.pi/agent` when set.
|
|
|
|
| Field | Default | Description |
|
|
| ----------------------- | ------------------- | -------------------------------------------- |
|
|
| `provider` | `openai-codex` | Pi model-registry provider id |
|
|
| `model` | `codex-auto-review` | Model id within the selected provider |
|
|
| `reasoning` | `low` | Reasoning level for reviewer calls |
|
|
| `timeoutMs` | `90000` | Total budget across all retry attempts |
|
|
| `includeBaselinePolicy` | `true` | Include the built-in Codex-style risk policy |
|
|
| `additionalPolicy` | omitted | Trusted operator policy appended to it |
|
|
|
|
See the [example config](config/config.example.json) and bundled [JSON Schema](schemas/config.schema.json). Unknown or invalid fields disable automatic decisions and fall through to the normal prompt.
|
|
|
|
Use `/permission-auto-review` in Pi's interactive TUI to edit and apply global or project config without reloading the session. Available subcommands:
|
|
|
|
```text
|
|
/permission-auto-review show
|
|
/permission-auto-review path
|
|
/permission-auto-review reset [global|project]
|
|
/permission-auto-review help
|
|
```
|
|
|
|
Custom providers and models must be defined in Pi's `~/.pi/agent/models.json`, then selected with this extension's `provider` and `model` fields. To replace the built-in risk policy completely, set `includeBaselinePolicy` to `false` and provide a non-empty `additionalPolicy`.
|
|
|
|
## Behavior and Limits
|
|
|
|
### Authorization evidence
|
|
|
|
The reviewer reads the current session's complete active branch with `SessionManager.getBranch()`, rather than only the post-compaction model context. This keeps original user authorization available after compaction without mixing in abandoned branches.
|
|
|
|
Only these transcript records can establish authorization:
|
|
|
|
- Pi session user-role messages (`source: "user"`);
|
|
- completed, non-cancelled responses to recognized `ask_user_question` and `plan_mode_question` calls (`source: "user_interaction"`).
|
|
|
|
Pi does not persist the original `input` event source on user-role messages, so `source: "user"` is a trust boundary provided by the Pi runtime rather than cryptographic proof of keyboard input. Trusted extensions can intentionally create such messages with `sendUserMessage()`; as with the rest of Pi's extension model, only trusted extension code should be installed.
|
|
|
|
Structured question responses are accepted only when the non-error result matches a preceding recognized tool call and are rebuilt from `details.answers` data. Free-form tool-result text is never promoted to user evidence. Assistant messages, ordinary tool calls/results, custom messages, and compaction/branch summaries remain untrusted even if their text claims to be user content.
|
|
|
|
Transcript rendering uses separate 10k-token message and tool budgets with per-entry truncation. The first and latest trusted records are retained first, then other trusted records from newest to oldest. The 40-entry recency cap applies only to assistant/tool evidence, so later tool activity cannot evict an already selected user authorization. Truncation indicates missing information; it does not itself raise intrinsic action risk.
|
|
|
|
### Permission boundaries
|
|
|
|
- Model, authentication, timeout, provider, or response-format failures defer to the normal human prompt.
|
|
- Unexpected internal review failures also defer to the human prompt instead of escaping into the permission gate.
|
|
- Three consecutive denials, or ten denials in the latest fifty reviews, open a circuit breaker until the next Pi turn.
|
|
- my-pi's maintained pi-permission-system keeps every `path` request inside the delegation envelope. For `external_directory`, only the built-in `read` tool may accept an auto-review `allow`; write, edit, bash, unknown tools, and undetermined surfaces are downgraded to the normal human prompt.
|
|
|
|
### Diagnostics
|
|
|
|
Each `auto_review.decision` emitted after transcript construction adds content-free context diagnostics (configuration failures that defer before a review do not have transcript diagnostics):
|
|
|
|
- `policyRevision`
|
|
- `contextSource` (`active-branch`)
|
|
- `transcriptEntriesRetained`
|
|
- `transcriptEntriesOmitted`
|
|
- `transcriptEntriesTruncated`
|
|
- `directUserEntriesRetained` / `directUserEntriesOmitted` / `directUserEntriesTruncated`
|
|
- `userInteractionEntriesRetained` / `userInteractionEntriesOmitted` / `userInteractionEntriesTruncated`
|
|
- `latestTrustedEntryRetained`
|
|
|
|
These fields distinguish missing or truncated authorization evidence from a model decision made after receiving trusted evidence. Transcript text and model rationale are not persisted. The records are written through pi-permission-system's existing permission-review log when that log is enabled.
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|