@mzwing/pi-permission-auto-review 0.1.4 → 0.3.0

package/README.md

@@ -10,6 +10,24 @@ A [Pi](https://github.com/earendil-works/pi) extension that adds Codex-style aut
 
 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.
+
+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.
+
+### Updating the bundled policy
+
+`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:
+
+```bash
+pnpm sync:policy                # report only; exits non-zero when upstream moved
+pnpm sync:policy --ref v1.2.3   # resolve against a tag, branch, or commit
+pnpm sync:policy --pin          # record the new revision, once you have ported it
+```
+
+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.
+
+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.
+
 ## Install
 
 ```bash
@@ -17,7 +35,9 @@ pi install npm:@gotgenes/pi-permission-system # dependency
 pi install npm:@mzwing/pi-permission-auto-review
 ```
 
-Pi 0.80.10 and Pi 0.81.x are supported. The extension uses `@mzwing/pi-polyfill` transitively for provider lookup on Pi 0.80.10; do not install the polyfill as a separate Pi extension.
+Pi 0.84.2+ (0.84.x and 0.85.x) and `@gotgenes/pi-permission-system` 27.x are required.
+
+The authorizer registers itself against the service keyed by its own session id, so a subagent's reviewer lands in the node whose gates actually read it.
 
 ## Enable
 
@@ -78,10 +98,42 @@ Custom providers and models must be defined in Pi's `~/.pi/agent/models.json`, t
 
 ## 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 prevents authorizers from auto-approving `path` and `external_directory` requests.
+- 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
 

package/dist/index.d.ts

@@ -8,6 +8,7 @@ declare const DEFAULT_PROVIDER = "openai-codex";
 declare const DEFAULT_MODEL = "codex-auto-review";
 declare const DEFAULT_TIMEOUT_MS = 9e4;
 declare const CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/mzwing/pi-packages/main/packages/pi-permission-auto-review/schemas/config.schema.json";
+declare const REASONING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 type AutoReviewConfigSchema = z.ZodObject<{
   $schema: z.ZodOptional<z.ZodString>;
   additionalPolicy: z.ZodOptional<z.ZodString>;
@@ -27,6 +28,15 @@ type AutoReviewConfigSchema = z.ZodObject<{
 }, z.core.$strict>;
 declare const autoReviewConfigSchema: AutoReviewConfigSchema;
 type AutoReviewConfig = z.infer<typeof autoReviewConfigSchema>;
+interface AutoReviewConfigFile {
+  $schema?: string | undefined;
+  provider?: string | undefined;
+  model?: string | undefined;
+  reasoning?: (typeof REASONING_LEVELS)[number] | undefined;
+  timeoutMs?: number | undefined;
+  includeBaselinePolicy?: boolean | undefined;
+  additionalPolicy?: string | undefined;
+}
 interface ConfigIssue {
   sourcePath: string;
   message: string;
@@ -42,6 +52,10 @@ interface LoadConfigOptions {
   agentDir?: string;
   readFile?: (path: string) => string | undefined;
 }
+interface AutoReviewConfigPaths {
+  globalPath: string;
+  projectPath: string;
+}
 declare function loadAutoReviewConfig(options: LoadConfigOptions): LoadConfigResult;
 declare function buildAutoReviewJsonSchema(): Record<string, unknown>;
 //#endregion
@@ -56,17 +70,68 @@ declare class DenialCircuitBreaker {
   private recordRecent;
 }
 //#endregion
+//#region src/config-store.d.ts
+type AutoReviewConfigScope = "global" | "project";
+interface ScopeSnapshotBase {
+  scope: AutoReviewConfigScope;
+  cwd: string;
+  path: string;
+  source: string | undefined;
+}
+type AutoReviewScopeSnapshot = (ScopeSnapshotBase & {
+  valid: true;
+  config: AutoReviewConfigFile;
+}) | (ScopeSnapshotBase & {
+  valid: false;
+  issue: ConfigIssue;
+});
+type ConfigMutationResult = {
+  ok: true;
+  loadResult: LoadConfigResult;
+  snapshot: AutoReviewScopeSnapshot;
+} | {
+  ok: false;
+  message: string;
+};
+interface AutoReviewConfigFileSystem {
+  readFile: (path: string) => string | undefined;
+  writeFile: (path: string, source: string) => void;
+  rename: (sourcePath: string, destinationPath: string) => void;
+  mkdir: (path: string) => void;
+  unlink: (path: string) => void;
+}
+interface AutoReviewConfigStoreOptions {
+  agentDir?: string;
+  fileSystem?: AutoReviewConfigFileSystem;
+}
+declare class AutoReviewConfigStore {
+  readonly agentDir: string;
+  private readonly fileSystem;
+  constructor(options?: AutoReviewConfigStoreOptions);
+  getPaths(cwd: string): AutoReviewConfigPaths;
+  load(cwd: string): LoadConfigResult;
+  readScope(cwd: string, scope: AutoReviewConfigScope): AutoReviewScopeSnapshot;
+  save(snapshot: AutoReviewScopeSnapshot, draft: AutoReviewConfigFile): ConfigMutationResult;
+  reset(snapshot: AutoReviewScopeSnapshot): ConfigMutationResult;
+  private loadWithOverride;
+  private serialize;
+  private checkForConflict;
+  private cleanupTempFile;
+}
+//#endregion
 //#region src/extension.d.ts
-interface ReviewerFactoryOptions {
-  config: AutoReviewConfig;
+interface SessionRuntime {
   registry: ModelRegistry;
-  sessionManager: Pick<SessionManager, "buildContextEntries">;
+  sessionManager: Pick<SessionManager, "getBranch">;
+}
+interface ReviewerFactoryOptions extends SessionRuntime {
+  config: AutoReviewConfig;
   circuitBreaker: DenialCircuitBreaker;
   sessionSignal: AbortSignal;
 }
 interface AutoReviewExtensionDependencies {
-  loadConfig?: (cwd: string) => LoadConfigResult;
-  getPermissionsService?: () => PermissionsService | undefined;
+  configStore?: AutoReviewConfigStore;
+  getPermissionsService?: (sessionId: string) => PermissionsService | undefined;
   createReviewer?: (options: ReviewerFactoryOptions) => Authorizer["authorize"];
 }
 declare function createAutoReviewExtension(pi: ExtensionAPI, dependencies?: AutoReviewExtensionDependencies): void;
@@ -74,5 +139,5 @@ declare function createAutoReviewExtension(pi: ExtensionAPI, dependencies?: Auto
 //#region src/index.d.ts
 declare function permissionAutoReviewExtension(pi: ExtensionAPI): void;
 //#endregion
-export { AUTHORIZER_NAME, type AutoReviewConfig, type AutoReviewExtensionDependencies, CONFIG_SCHEMA_URL, type ConfigIssue, DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_TIMEOUT_MS, EXTENSION_ID, type LoadConfigOptions, type LoadConfigResult, autoReviewConfigSchema, buildAutoReviewJsonSchema, createAutoReviewExtension, permissionAutoReviewExtension as default, loadAutoReviewConfig };
+export { AUTHORIZER_NAME, type AutoReviewConfig, CONFIG_SCHEMA_URL, type ConfigIssue, DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_TIMEOUT_MS, EXTENSION_ID, type LoadConfigOptions, type LoadConfigResult, autoReviewConfigSchema, buildAutoReviewJsonSchema, createAutoReviewExtension, permissionAutoReviewExtension as default, loadAutoReviewConfig };
 //# sourceMappingURL=index.d.ts.map