@mzwing/pi-permission-auto-review 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -114
- package/dist/index.d.ts +1 -1
- package/dist/index.js +538 -590
- package/dist/index.js.map +1 -1
- package/dist/review.d.ts +8 -5
- package/dist/review.js +2 -2
- package/dist/{verdict-BsA4bcua.js → verdict-VFGyevZ2.js} +206 -324
- package/dist/verdict-VFGyevZ2.js.map +1 -0
- package/package.json +9 -9
- package/dist/verdict-BsA4bcua.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,47 +1,27 @@
|
|
|
1
1
|
# @mzwing/pi-permission-auto-review
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@mzwing/pi-permission-auto-review)
|
|
4
4
|
|
|
5
|
-
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).
|
|
5
|
+
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). Each ask is judged by OpenAI's `codex-auto-review` model against a bundled adaptation of the [OpenAI Codex Guardian policy](https://github.com/openai/codex/tree/main/codex-rs/prompts/templates/guardian); whatever it cannot decide falls through to the normal prompt.
|
|
6
6
|
|
|
7
|
-
## Differences between
|
|
7
|
+
## Differences between @gotgenes/pi-permission-model-judge
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
`@gotgenes/pi-permission-model-judge` is a general-purpose model-based authorizer that can be used to evaluate any permission request.
|
|
10
10
|
|
|
11
|
-
Ours is mostly specialized for OpenAI's
|
|
12
|
-
|
|
13
|
-
The bundled baseline is a Pi-specific adaptation of OpenAI Codex Guardian's [`policy_template.md`](https://github.com/openai/codex/blob/26cb4d73e2ce25575644038d7af5beb2440d0ed0/codex-rs/prompts/templates/guardian/policy_template.md) and [`policy.md`](https://github.com/openai/codex/blob/26cb4d73e2ce25575644038d7af5beb2440d0ed0/codex-rs/prompts/templates/guardian/policy.md) at revision [`26cb4d73e2ce25575644038d7af5beb2440d0ed0`](https://github.com/openai/codex/commit/26cb4d73e2ce25575644038d7af5beb2440d0ed0). It is bundled at build time; the extension never fetches policy text while reviewing an action.
|
|
14
|
-
|
|
15
|
-
Upstream's `Execution Environment` section and its MCP `connected_account_email` rule are deliberately left out: both describe Codex's sandbox and tool surface, which Pi's tool-free reviewer does not have. Upstream's `node_repl_policy.md` is likewise out of scope — it governs `node_repl` / `cua_repl` computer-use tools that Pi does not expose.
|
|
16
|
-
|
|
17
|
-
### Updating the bundled policy
|
|
18
|
-
|
|
19
|
-
`src/upstream.ts` records which Codex files the adaptation tracks and the revision it was last reconciled against. `pnpm sync:policy` reports whether upstream has moved since:
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
pnpm sync:policy # report only; exits non-zero when upstream moved
|
|
23
|
-
pnpm sync:policy --ref v1.2.3 # resolve against a tag, branch, or commit
|
|
24
|
-
pnpm sync:policy --pin # record the new revision, once you have ported it
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
A run that finds movement lists every commit touching the tracked files since the pinned revision, with links. Port what applies into `src/policy.ts` by hand — the adapted text is a rewrite, not a copy, because Pi's reviewer has no tools and reads a different evidence-provenance model, so upstream wording cannot be dropped in mechanically.
|
|
28
|
-
|
|
29
|
-
Only re-run with `--pin` once that porting is done. `POLICY_REVISION` is written to the permission review log, so a pin that outruns the text would be a false audit record. Bump `PI_ADAPTATION_REVISION` as well when you reword anything Pi-specific. Set `GITHUB_TOKEN` to lift GitHub's anonymous rate limit.
|
|
11
|
+
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.
|
|
30
12
|
|
|
31
13
|
## Install
|
|
32
14
|
|
|
33
15
|
```bash
|
|
34
|
-
pi install npm:@gotgenes/pi-permission-system
|
|
16
|
+
pi install npm:@gotgenes/pi-permission-system
|
|
35
17
|
pi install npm:@mzwing/pi-permission-auto-review
|
|
36
18
|
```
|
|
37
19
|
|
|
38
|
-
Pi 0.
|
|
39
|
-
|
|
40
|
-
The authorizer registers itself against the service keyed by its own session id, so a subagent's reviewer lands in its own node. A node that relays its asks to a live parent session runs no chain of its own, and the parent session's reviewer decides for it.
|
|
20
|
+
Requires Pi 1.0.0 or later and `@gotgenes/pi-permission-system` 37.x – 39.x.
|
|
41
21
|
|
|
42
|
-
##
|
|
22
|
+
## Usage
|
|
43
23
|
|
|
44
|
-
Add
|
|
24
|
+
Add the authorizer to pi-permission-system's config, normally `~/.pi/agent/extensions/pi-permission-system/config.json`:
|
|
45
25
|
|
|
46
26
|
```json
|
|
47
27
|
{
|
|
@@ -49,112 +29,43 @@ Add `"auto-review"` to pi-permission-system's config:
|
|
|
49
29
|
}
|
|
50
30
|
```
|
|
51
31
|
|
|
52
|
-
The
|
|
32
|
+
The default model reuses Pi's `openai-codex` login, listed as "OpenAI Codex (legacy)" in `/login`.
|
|
53
33
|
|
|
54
|
-
|
|
34
|
+
`/permission-auto-review` edits the config interactively and applies it without reloading the session. Its subcommands are `show`, `path`, `reset [global|project]` and `help`.
|
|
55
35
|
|
|
56
|
-
|
|
57
|
-
{
|
|
58
|
-
"provider": "openai-codex",
|
|
59
|
-
"model": "codex-auto-review",
|
|
60
|
-
"reasoning": "low",
|
|
61
|
-
"timeoutMs": 90000,
|
|
62
|
-
"includeBaselinePolicy": true
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
`codex-auto-review` is an official hidden model. The extension derives it from Pi's `openai-codex` provider and reuses its login, listed as "OpenAI Codex (legacy)" in `/login`; signing in with ChatGPT on the `openai` provider does not cover it.
|
|
36
|
+
The footer shows whether the reviewer is registered and how many asks it has allowed, denied or deferred in the session.
|
|
67
37
|
|
|
68
38
|
## Configuration
|
|
69
39
|
|
|
70
|
-
|
|
71
|
-
| ------- | -------------------------------------------------------------- |
|
|
72
|
-
| Global | `~/.pi/agent/extensions/pi-permission-auto-review/config.json` |
|
|
73
|
-
| Project | `<cwd>/.pi/extensions/pi-permission-auto-review/config.json` |
|
|
40
|
+
Optional. `~/.pi/agent/extensions/pi-permission-auto-review/config.json` and `.pi/extensions/pi-permission-auto-review/config.json` are merged, the project over the global one; the project file is read only once Pi trusts the project. An invalid config disables automatic decisions.
|
|
74
41
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `includeBaselinePolicy` | `true` | Include the built-in Codex-style risk policy |
|
|
84
|
-
| `additionalPolicy` | omitted | Trusted operator policy appended to it |
|
|
85
|
-
|
|
86
|
-
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.
|
|
87
|
-
|
|
88
|
-
Use `/permission-auto-review` in Pi's interactive TUI to edit and apply global or project config without reloading the session. Available subcommands:
|
|
89
|
-
|
|
90
|
-
```text
|
|
91
|
-
/permission-auto-review show
|
|
92
|
-
/permission-auto-review path
|
|
93
|
-
/permission-auto-review reset [global|project]
|
|
94
|
-
/permission-auto-review help
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
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`.
|
|
98
|
-
|
|
99
|
-
## Behavior and Limits
|
|
100
|
-
|
|
101
|
-
### Authorization evidence
|
|
102
|
-
|
|
103
|
-
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.
|
|
104
|
-
|
|
105
|
-
Only these transcript records can establish authorization:
|
|
106
|
-
|
|
107
|
-
- Pi session user-role messages (`source: "user"`);
|
|
108
|
-
- completed, non-cancelled responses to recognized `ask_user_question` and `plan_mode_question` calls (`source: "user_interaction"`).
|
|
109
|
-
|
|
110
|
-
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.
|
|
111
|
-
|
|
112
|
-
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.
|
|
113
|
-
|
|
114
|
-
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.
|
|
115
|
-
|
|
116
|
-
### Permission boundaries
|
|
117
|
-
|
|
118
|
-
- Model, authentication, timeout, provider, or response-format failures defer to the normal human prompt.
|
|
119
|
-
- Unexpected internal review failures also defer to the human prompt instead of escaping into the permission gate.
|
|
120
|
-
- Three consecutive denials, or ten denials in the latest fifty reviews, open a circuit breaker until the next Pi turn.
|
|
121
|
-
- 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.
|
|
122
|
-
|
|
123
|
-
### Diagnostics
|
|
124
|
-
|
|
125
|
-
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):
|
|
126
|
-
|
|
127
|
-
- `policyRevision`
|
|
128
|
-
- `contextSource` (`active-branch`)
|
|
129
|
-
- `transcriptEntriesRetained`
|
|
130
|
-
- `transcriptEntriesOmitted`
|
|
131
|
-
- `transcriptEntriesTruncated`
|
|
132
|
-
- `directUserEntriesRetained` / `directUserEntriesOmitted` / `directUserEntriesTruncated`
|
|
133
|
-
- `userInteractionEntriesRetained` / `userInteractionEntriesOmitted` / `userInteractionEntriesTruncated`
|
|
134
|
-
- `latestTrustedEntryRetained`
|
|
135
|
-
|
|
136
|
-
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.
|
|
42
|
+
| Field | Default | Description |
|
|
43
|
+
| ----------------------- | ------------------- | ------------------------------------------------------- |
|
|
44
|
+
| `provider` | `openai-codex` | Pi provider id of the reviewer model |
|
|
45
|
+
| `model` | `codex-auto-review` | Reviewer model id |
|
|
46
|
+
| `reasoning` | `low` | Reasoning level for review calls |
|
|
47
|
+
| `timeoutMs` | `90000` | Total budget across retries |
|
|
48
|
+
| `includeBaselinePolicy` | `true` | Include the bundled Guardian policy |
|
|
49
|
+
| `additionalPolicy` | — | Operator policy, required when the baseline is disabled |
|
|
137
50
|
|
|
138
51
|
## Programmatic use
|
|
139
52
|
|
|
140
|
-
`@mzwing/pi-permission-auto-review/review`
|
|
53
|
+
`@mzwing/pi-permission-auto-review/review` exports the prompt and verdict pipeline without needing Pi at runtime:
|
|
141
54
|
|
|
142
55
|
```ts
|
|
143
56
|
import {
|
|
144
57
|
buildReviewPrompt,
|
|
145
58
|
DEFAULT_CONFIG,
|
|
59
|
+
findToolCallInput,
|
|
146
60
|
parseReviewAssessment,
|
|
147
61
|
renderTranscript,
|
|
148
62
|
} from '@mzwing/pi-permission-auto-review/review'
|
|
149
63
|
|
|
150
|
-
const
|
|
64
|
+
const toolInput = findToolCallInput(sessionEntries, details.toolCallId)
|
|
65
|
+
const prompt = buildReviewPrompt(DEFAULT_CONFIG, renderTranscript(sessionEntries), details, toolInput)
|
|
151
66
|
const assessment = parseReviewAssessment(modelReply)
|
|
152
67
|
```
|
|
153
68
|
|
|
154
|
-
`details` is a `PromptPermissionDetails` from `@gotgenes/pi-permission-system`. The subpath needs no Pi peer dependency at runtime.
|
|
155
|
-
|
|
156
|
-
`buildSystemPrompt`, `FIXED_REVIEW_PROTOCOL`, and `POLICY_REVISION` are exported alongside them. Prompt text tracks the bundled Guardian policy and changes with `POLICY_REVISION`; assert on that rather than on exact wording.
|
|
157
|
-
|
|
158
69
|
## License
|
|
159
70
|
|
|
160
71
|
[MIT](LICENSE)
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
//#region src/index.d.ts
|
|
3
|
-
export default function
|
|
3
|
+
export default function permissionAutoReview(pi: ExtensionAPI): void;
|
|
4
4
|
//#endregion
|
|
5
5
|
//# sourceMappingURL=index.d.ts.map
|