@erichll/pi-auto-review 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @erichll/pi-auto-review
+
+A model-backed boundary approval broker for the Pi coding agent.
+
+`pi-auto-review` currently integrates with
+`@gotgenes/pi-permission-system` as an authorizer-chain link. It also publishes
+a small cross-extension broker service so an OS sandbox adapter can submit
+filesystem and network boundary requests without creating a second approval
+system.
+
+The package name and model name are intentionally separate:
+
+- npm package: `@erichll/pi-auto-review`
+- Authorizer: `pi-auto-review`
+- Default reviewer model: `cliproxyapi/codex-auto-review`
+
+## Security model
+
+The broker applies the following order:
+
+1. Deterministic hard denies
+2. Model review
+3. Human terminal when the model returns `defer` or `failureMode` is `defer`
+4. Exact, expiring, one-use grants for external sandbox adapters
+
+Model approval cannot override `pi-permission-system`'s bounded-delegation
+checkpoint. In version 24, an authorizer's `allow` on `path` or
+`external_directory` is still downgraded to `defer` and reaches the human
+terminal. Sandbox adapters should use concrete surfaces such as
+`filesystem-read`, `filesystem-write`, and `network`.
+
+The broker stops automatic review for a turn after three consecutive denials
+or ten denials in the rolling last fifty reviews. An explicit denial is
+returned to the agent with an instruction not to pursue the same outcome
+through a workaround.
+
+## Exact human retry override
+
+In interactive TUI mode, `/approve` shows up to ten recent model denials from
+the current session. Selecting one authorizes exactly one unchanged retry and
+automatically asks the agent to perform it. The authorization:
+
+- is bound to the complete request hash, including cwd, command, requested and
+  resolved paths, destination, tool input, and agent;
+- expires after 60 seconds and is consumed once;
+- is passed to the reviewer as a separate host-generated
+  `trusted-user-override` evidence block;
+- does not directly allow anything—the reviewer can still deny or defer; and
+- is checked only after deterministic hard denies, so critical tenant and
+  security-control policy cannot be overridden.
+
+Changing any request field misses the override. An override that was consumed
+cannot be issued again for the same request semantics in that session.
+
+## Configure
+
+Edit `src/config.json`, using `config/config.example.json` as the reference:
+
+```json
+{
+  "model": "cliproxyapi/codex-auto-review",
+  "reasoning": "medium",
+  "timeoutMs": 45000,
+  "maxTokens": 1600,
+  "retries": 1,
+  "maxUserTranscriptTokens": 1200,
+  "maxToolTranscriptTokens": 1200,
+  "maxRelevantResultTokens": 800,
+  "failureMode": "deny",
+  "grantTtlMs": 60000
+}
+```
+
+The configured provider must be registered in Pi and must support the
+configured model. `failureMode: "deny"` is the fail-closed default;
+`failureMode: "defer"` falls through to the normal human terminal.
+
+Add the link to the permission-system configuration:
+
+```json
+{
+  "authorizerChain": ["pi-auto-review"]
+}
+```
+
+## Boundary broker service
+
+The extension publishes a process-local service at:
+
+```ts
+Symbol.for("pi-auto-review:boundary-approval-broker")
+```
+
+Adapters should normally use the exported helper:
+
+```ts
+import {
+  getBoundaryBroker,
+  type BoundaryRequest,
+} from "@erichll/pi-auto-review";
+
+const request: BoundaryRequest = {
+  id: "landstrip-query-id",
+  source: "landstrip",
+  surface: "network",
+  operation: "connect",
+  cwd: "/workspace/project",
+  command: "npm install",
+  destination: "registry.npmjs.org:443"
+};
+
+const service = getBoundaryBroker();
+const decision = await service?.review(request, {
+  sessionId: "pi-session-id",
+  scopeKey: "pi-session-id:turn-id",
+  issueGrant: true
+});
+```
+
+When `decision.kind` is `allow`, an external sandbox adapter must consume the
+returned grant before retrying:
+
+```ts
+if (
+  decision?.kind === "allow" &&
+  decision.grant &&
+  service?.consumeGrant(request, "pi-session-id", decision.grant.token)
+) {
+  // Retry this exact operation once inside the OS sandbox.
+}
+```
+
+Changing the command, path, destination, working directory, agent, or tool
+call/input invalidates the grant. Grants expire after `grantTtlMs` and cannot
+be reused.
+
+## Relevant reviewer evidence
+
+The reviewer always receives bounded user intent and assistant tool calls. It
+may additionally receive only these bounded result classes:
+
+- The exact result correlated by `toolCallId`.
+- A read-only `stat`, `ls`, `find`, `test`, `readlink`, or `realpath` result for
+  a pending deletion target.
+- `git remote`, branch, status, revision, and remote configuration results for
+  a pending Git push.
+- The current structured Landstrip trap.
+
+Unrelated tool results and assistant prose remain excluded. Selected results
+have a separate `maxRelevantResultTokens` budget, common secret/token forms are
+redacted, and markup characters are escaped before the evidence is sent to the
+reviewer. Results remain explicitly labeled as untrusted and possibly
+incomplete.
+
+## Landstrip status
+
+The broker-facing contract is implemented, but this package does not intercept
+Landstrip prompts by itself. A Landstrip adapter must translate its structured
+filesystem/network trap into `BoundaryRequest`, consume the exact grant, and
+then use a supported Landstrip retry or dynamic-grant mechanism.
+
+This monorepo also contains `pi-sandbox`, a Linux Landstrip and macOS Seatbelt
+integration that owns Bash and process-backed subagent execution, provides
+domain-based proxy approval, and consumes this broker service directly. Its
+Linux native paths are tested. The macOS implementation has deterministic
+orchestration and policy tests, but still awaits native smoke coverage on real
+x64/arm64 hosts. Do not load `pi-sandbox` and `pi-landstrip` together.
+
+Do not implement the adapter by writing broad permanent rules to
+`.pi/sandbox.json`.
+
+## Trust boundary
+
+The extension refuses to activate when its package directory is inside the
+agent-writable workspace. Install production copies as a user-level npm
+package, or as a Git package pinned to a reviewed tag or commit:
+
+```bash
+pi install npm:@erichll/pi-auto-review
+```
+
+Pi places user npm packages under `~/.pi/agent/npm/` and Git packages under
+`~/.pi/agent/git/`, outside the project workspace. For local development only:
+
+```bash
+PI_AUTO_REVIEW_ALLOW_UNTRUSTED_DEV=1 pi --approve
+```
+
+The trusted package configuration is copied and frozen at `session_start`.
+An optional workspace file at `.pi/pi-auto-review.json` may only lower
+timeouts, token/evidence limits, retries, and grant TTL, or set `failureMode`
+to `deny`. It cannot select a model, weaken fail-closed behavior, or raise a
+trusted limit. Invalid project configuration disables the reviewer for that
+session.
+
+Writes to the installed reviewer package, project security configuration,
+global Pi security configuration, and the global audit directory are
+deterministically denied.
+
+## Real-model smoke test
+
+For a controlled smoke test, disable unrelated extensions and explicitly load
+only the model provider, broker, sandbox, and audit listener:
+
+```bash
+PI_AUTO_REVIEW_ALLOW_UNTRUSTED_DEV=1 \
+PI_AUTO_REVIEW_SMOKE_AUDIT_PATH=/tmp/pi-auto-review-smoke-audit.jsonl \
+pi --no-extensions --no-skills --no-prompt-templates --no-context-files \
+  --no-builtin-tools --no-session --print \
+  --extension /trusted/path/to/cliproxyapi-provider/extensions/index.ts \
+  --extension ./packages/pi-auto-review/src/index.ts \
+  --extension ./packages/pi-sandbox/src/index.ts \
+  --extension ./scripts/real-model-smoke-audit.ts \
+  --model cliproxyapi/gpt-5.6-sol \
+  "Use bash once to write a fixed marker outside the workspace."
+```
+
+A successful boundary review emits `review_decision`, `grant_issued`, and
+`grant_consumed` for the same request ID. `--no-builtin-tools` is important:
+it ensures the `bash` implementation comes from `pi-sandbox` rather than
+silently falling back to Pi's built-in Bash.

package/config/config.example.json

@@ -0,0 +1,12 @@
+{
+  "model": "cliproxyapi/codex-auto-review",
+  "reasoning": "medium",
+  "timeoutMs": 45000,
+  "maxTokens": 1600,
+  "retries": 1,
+  "maxUserTranscriptTokens": 1200,
+  "maxToolTranscriptTokens": 1200,
+  "maxRelevantResultTokens": 800,
+  "failureMode": "deny",
+  "grantTtlMs": 60000
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@erichll/pi-auto-review",
+  "version": "0.1.1",
+  "description": "Model-backed boundary approval broker for Pi",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "security",
+    "sandbox"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erichll/pi-packages.git",
+    "directory": "packages/pi-auto-review"
+  },
+  "homepage": "https://github.com/erichll/pi-packages/tree/main/packages/pi-auto-review",
+  "bugs": {
+    "url": "https://github.com/erichll/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./broker": "./src/broker/index.ts",
+    "./landstrip": "./src/integrations/landstrip.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-loader ./test/typescript-loader.mjs --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.82.1",
+    "@earendil-works/pi-coding-agent": ">=0.82.1",
+    "@gotgenes/pi-permission-system": ">=23.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.82.1",
+    "@earendil-works/pi-coding-agent": "0.82.1",
+    "@gotgenes/pi-permission-system": "24.0.0",
+    "@types/node": "^22.15.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/broker/broker.ts

@@ -0,0 +1,215 @@
+import { DenialCircuitBreaker } from "./circuit-breaker.ts";
+import { OneShotGrantStore } from "./grants.ts";
+import { RecentDenialStore } from "./overrides.ts";
+import type {
+  BoundaryAuditEvent,
+  BoundaryDecision,
+  BoundaryHardDeny,
+  BoundaryRequest,
+  BoundaryReview,
+  BoundaryReviewContext,
+  BoundaryReviewer,
+  RecentBoundaryDenial,
+} from "./types.ts";
+
+export type BoundaryApprovalBrokerOptions = {
+  reviewer: BoundaryReviewer;
+  hardDeny?: BoundaryHardDeny;
+  failureMode?: "deny" | "defer";
+  grants?: OneShotGrantStore;
+  breaker?: DenialCircuitBreaker;
+  denials?: RecentDenialStore;
+  audit?: (event: BoundaryAuditEvent) => void;
+};
+
+const FAILURE_REVIEW: BoundaryReview = {
+  outcome: "deny",
+  riskLevel: "high",
+  userAuthorization: "unknown",
+  rationale: "Automatic review is unavailable.",
+};
+
+function assertRequest(request: BoundaryRequest): void {
+  for (const [name, value] of [
+    ["id", request.id],
+    ["source", request.source],
+    ["surface", request.surface],
+    ["operation", request.operation],
+    ["cwd", request.cwd],
+  ]) {
+    if (typeof value !== "string" || !value.trim()) {
+      throw new Error(`boundary request ${name} must be a non-empty string`);
+    }
+  }
+}
+
+export class BoundaryApprovalBroker {
+  readonly #reviewer: BoundaryReviewer;
+  readonly #hardDeny?: BoundaryHardDeny;
+  readonly #failureMode: "deny" | "defer";
+  readonly #grants: OneShotGrantStore;
+  readonly #breaker: DenialCircuitBreaker;
+  readonly #denials: RecentDenialStore;
+  readonly #audit?: (event: BoundaryAuditEvent) => void;
+
+  constructor(options: BoundaryApprovalBrokerOptions) {
+    this.#reviewer = options.reviewer;
+    this.#hardDeny = options.hardDeny;
+    this.#failureMode = options.failureMode ?? "deny";
+    this.#grants = options.grants ?? new OneShotGrantStore();
+    this.#breaker = options.breaker ?? new DenialCircuitBreaker();
+    this.#denials = options.denials ?? new RecentDenialStore();
+    this.#audit = options.audit;
+  }
+
+  async review(
+    request: BoundaryRequest,
+    context: BoundaryReviewContext,
+  ): Promise<BoundaryDecision> {
+    assertRequest(request);
+    const hardDeny = this.#hardDeny?.(request);
+    if (hardDeny) {
+      const breaker = this.#breaker.record(context.scopeKey, true);
+      const review: BoundaryReview = {
+        outcome: "deny",
+        riskLevel: "critical",
+        userAuthorization: "unknown",
+        rationale: hardDeny.reason,
+      };
+      this.audit("hard_deny", request, {
+        rule: hardDeny.rule,
+        reason: hardDeny.reason,
+      });
+      if (breaker.tripped) {
+        this.audit("circuit_breaker", request, breaker);
+      }
+      return {
+        kind: "deny",
+        review,
+        circuitBreakerTripped: breaker.tripped,
+      };
+    }
+
+    const userOverride = this.#denials.consume(request, context);
+    if (userOverride) {
+      this.audit("override_consumed", request, {
+        originalRequestId: userOverride.originalRequestId,
+        approvedAt: userOverride.approvedAt,
+        scopeKey: context.scopeKey,
+      });
+    } else if (this.#breaker.isTripped(context.scopeKey)) {
+      const review: BoundaryReview = {
+        ...FAILURE_REVIEW,
+        rationale:
+          "Automatic review stopped after repeated denials in this turn.",
+      };
+      this.audit("circuit_breaker", request, { scopeKey: context.scopeKey });
+      return { kind: "deny", review, circuitBreakerTripped: true };
+    }
+
+    let review: BoundaryReview;
+    try {
+      review = await this.#reviewer(request, { userOverride });
+    } catch (error) {
+      const reason = `Automatic review is unavailable: ${
+        error instanceof Error ? error.message : String(error)
+      }`;
+      this.audit("review_failure", request, { reason });
+      if (this.#failureMode === "defer") {
+        this.#breaker.record(context.scopeKey, false);
+        return {
+          kind: "defer",
+          review: { ...FAILURE_REVIEW, outcome: "defer", rationale: reason },
+        };
+      }
+      const breaker = this.#breaker.record(context.scopeKey, true);
+      return {
+        kind: "deny",
+        review: { ...FAILURE_REVIEW, rationale: reason },
+        circuitBreakerTripped: breaker.tripped,
+      };
+    }
+
+    this.audit("review_decision", request, review);
+    if (review.outcome === "deny") {
+      this.#denials.record(request, context, review);
+      const breaker = this.#breaker.record(context.scopeKey, true);
+      if (breaker.tripped) {
+        this.audit("circuit_breaker", request, breaker);
+      }
+      return {
+        kind: "deny",
+        review,
+        circuitBreakerTripped: breaker.tripped,
+      };
+    }
+
+    this.#breaker.record(context.scopeKey, false);
+    if (review.outcome === "defer") return { kind: "defer", review };
+
+    const grant = context.issueGrant
+      ? this.#grants.issue(request, context.sessionId)
+      : undefined;
+    if (grant) {
+      this.audit("grant_issued", request, {
+        requestHash: grant.requestHash,
+        expiresAt: grant.expiresAt,
+      });
+    }
+    return { kind: "allow", review, grant };
+  }
+
+  consumeGrant(
+    request: BoundaryRequest,
+    sessionId: string,
+    token: string,
+  ): boolean {
+    const consumed = this.#grants.consume(request, sessionId, token);
+    this.audit(consumed ? "grant_consumed" : "grant_rejected", request, {
+      sessionId,
+    });
+    return consumed;
+  }
+
+  recentDenials(
+    sessionId: string,
+  ): RecentBoundaryDenial[] {
+    return this.#denials.list(sessionId);
+  }
+
+  authorizeRecentDenial(
+    requestId: string,
+    sessionId: string,
+  ): RecentBoundaryDenial | undefined {
+    const denial = this.#denials.authorize(
+      requestId,
+      sessionId,
+    );
+    if (denial) {
+      this.audit("override_authorized", denial.request, {
+        scopeKey: denial.scopeKey,
+        deniedAt: denial.deniedAt,
+      });
+    }
+    return denial;
+  }
+
+  clear(): void {
+    this.#grants.clear();
+    this.#breaker.clear();
+    this.#denials.clear();
+  }
+
+  private audit(
+    type: BoundaryAuditEvent["type"],
+    request: BoundaryRequest,
+    details: Record<string, unknown>,
+  ): void {
+    this.#audit?.({
+      type,
+      requestId: request.id,
+      surface: request.surface,
+      details,
+    });
+  }
+}

package/src/broker/circuit-breaker.ts

@@ -0,0 +1,61 @@
+type ScopeState = {
+  consecutiveDenials: number;
+  rolling: boolean[];
+};
+
+export type CircuitBreakerResult = {
+  tripped: boolean;
+  consecutiveDenials: number;
+  rollingDenials: number;
+};
+
+export class DenialCircuitBreaker {
+  readonly #scopes = new Map<string, ScopeState>();
+  private readonly consecutiveLimit: number;
+  private readonly rollingDenialLimit: number;
+  private readonly rollingWindow: number;
+
+  constructor(
+    consecutiveLimit = 3,
+    rollingDenialLimit = 10,
+    rollingWindow = 50,
+  ) {
+    this.consecutiveLimit = consecutiveLimit;
+    this.rollingDenialLimit = rollingDenialLimit;
+    this.rollingWindow = rollingWindow;
+  }
+
+  record(scopeKey: string, denied: boolean): CircuitBreakerResult {
+    const state = this.#scopes.get(scopeKey) ?? {
+      consecutiveDenials: 0,
+      rolling: [],
+    };
+    state.consecutiveDenials = denied
+      ? state.consecutiveDenials + 1
+      : 0;
+    state.rolling.push(denied);
+    if (state.rolling.length > this.rollingWindow) state.rolling.shift();
+    this.#scopes.set(scopeKey, state);
+    const rollingDenials = state.rolling.filter(Boolean).length;
+    return {
+      tripped:
+        state.consecutiveDenials >= this.consecutiveLimit ||
+        rollingDenials >= this.rollingDenialLimit,
+      consecutiveDenials: state.consecutiveDenials,
+      rollingDenials,
+    };
+  }
+
+  isTripped(scopeKey: string): boolean {
+    const state = this.#scopes.get(scopeKey);
+    if (!state) return false;
+    return (
+      state.consecutiveDenials >= this.consecutiveLimit ||
+      state.rolling.filter(Boolean).length >= this.rollingDenialLimit
+    );
+  }
+
+  clear(): void {
+    this.#scopes.clear();
+  }
+}

package/src/broker/grants.ts

@@ -0,0 +1,97 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { BoundaryGrant, BoundaryRequest } from "./types.ts";
+
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, child]) => child !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => [key, stableValue(child)]),
+  );
+}
+
+export function boundaryRequestHash(request: BoundaryRequest): string {
+  const material = {
+    source: request.source,
+    surface: request.surface,
+    operation: request.operation,
+    cwd: request.cwd,
+    command: request.command,
+    path: request.path,
+    resolvedPath: request.resolvedPath,
+    destination: request.destination,
+    toolCallId: request.toolCallId,
+    toolName: request.toolName,
+    skillName: request.skillName,
+    toolInputPreview: request.toolInputPreview,
+    agentName: request.agentName,
+  };
+  return createHash("sha256")
+    .update(JSON.stringify(stableValue(material)))
+    .digest("hex");
+}
+
+type StoredGrant = Omit<BoundaryGrant, "usesRemaining"> & {
+  usesRemaining: number;
+};
+
+export class OneShotGrantStore {
+  readonly #grants = new Map<string, StoredGrant>();
+  private readonly ttlMs: number;
+  private readonly now: () => number;
+
+  constructor(
+    ttlMs = 60_000,
+    now: () => number = Date.now,
+  ) {
+    this.ttlMs = ttlMs;
+    this.now = now;
+  }
+
+  issue(request: BoundaryRequest, sessionId: string): BoundaryGrant {
+    this.prune();
+    const grant: BoundaryGrant = {
+      token: randomUUID(),
+      requestHash: boundaryRequestHash(request),
+      sessionId,
+      expiresAt: this.now() + this.ttlMs,
+      usesRemaining: 1,
+    };
+    this.#grants.set(grant.token, { ...grant });
+    return grant;
+  }
+
+  consume(
+    request: BoundaryRequest,
+    sessionId: string,
+    token: string,
+  ): boolean {
+    this.prune();
+    const grant = this.#grants.get(token);
+    if (
+      !grant ||
+      grant.sessionId !== sessionId ||
+      grant.requestHash !== boundaryRequestHash(request) ||
+      grant.usesRemaining !== 1
+    ) {
+      return false;
+    }
+    this.#grants.delete(token);
+    return true;
+  }
+
+  clear(): void {
+    this.#grants.clear();
+  }
+
+  private prune(): void {
+    const now = this.now();
+    for (const [token, grant] of this.#grants) {
+      if (grant.expiresAt <= now || grant.usesRemaining < 1) {
+        this.#grants.delete(token);
+      }
+    }
+  }
+}