mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
feat: vendor permission auto-review source
This commit is contained in:
叶林立
@@ -0,0 +1,128 @@
|
||||
# @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.
|
||||
- pi-permission-system's delegation envelope prevents authorizers from auto-approving `path` and `external_directory` requests. An auto-review `allow` for those surfaces is deliberately downgraded to the normal human prompt; this extension does not bypass that boundary.
|
||||
|
||||
### 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)
|
||||
Reference in New Issue
Block a user