Jev Eye

Ultra-lean supervisor. Three-layer guardrails. Semantic gate for Pi.

Overview

pi-jev-eye is an ultra-lean, zero-dependency supervisor for pi. It protects your workspace from destructive commands, prevents credential leaks, enforces testing verification, routes models per-turn, and runs a semantic gate through TypeSafe Jev, OpenRouter, or Cloudflare Workers AI (Clef) to catch code slop before disk writes.

• Instant Regex Gate: 0 ms, 0 token barrier blocking wipes (rm -rf /, DROP DATABASE), protected branch force-pushes, and hardcoded secrets (sk-..., ghp_..., SSH keys).
• Done-Check Verification: Warns when the agent claims done after editing files without running verification suites (npm test, cargo test, pytest).
• Targeted Jev Semantic Gate: Evaluates diffs ≥ 10 lines via TypeSafe Jev (has_slop) to reject placeholder stubs and unfulfilled TODOs.
• Three Decision Backends: TypeSafe Jev, OpenRouter, or Cloudflare Workers AI (Clef / clef-flash) — same gated pipeline, with the active one chosen in /jev-eye models. Clef runs inside Cloudflare's free daily allowance of 10,000 neurons, so the gate costs nothing for most sessions.
• Jev + Clef Usage Panel (/jev-eye usage): One compact table shows Jev and Clef side by side (requests, input tokens, cost for the month), three period totals, and the Cloudflare free-neuron budget with its reset time and overage cost. Periods that predate the split are reported as an explicit Earlier row rather than silently dropping out of the table.
• Reviewed Turns (jev / @jev / /eye): Calibrated review contract with machine facts, Jev scoring tables, and single-flight prompt alignment (answers_request). The flat /eye <task> form opens it without a prose token; so does writing /eye inside a sentence, because the marker is read from the prompt text and not only from the command.
• Fail-Open Reliability: Network timeouts or offline provider APIs gracefully degrade so coding sessions never stall or freeze.
• Account Management in Place: One Accounts screen lists every backend with its stored state — [Enter] stores a key, [Ctrl+d] removes one after a second confirming press, so switching backends never requires a separate logout menu.
• Rounded Arnative Screens: Every /jev-eye screen — menu, accounts, models, status, usage, routing, the key prompt, and the confirm dialog — draws inside one rounded frame with a soft-accent border derived from the live theme, a bold soft-accent chosen row, a padded · column, and a footer that advertises only the keys it handles.

Install

pi install npm:@bismawy/pi-jev-eye

Supply your Jev API key via /jev-eye accounts (TypeSafe, OpenRouter, or Cloudflare Workers AI), or export TYPESAFE_API_KEY / OPENROUTER_API_KEY. For Cloudflare Clef, export CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN — a token alone cannot build the account-scoped route.

Credentials you store live side by side: ~/.pi/agent/pi-jev-eye/auth.json (mode 0600) holds one entry per provider, so logging in with Clef no longer discards a stored TypeSafe key. /jev-eye accounts opens the Accounts screen, where [Ctrl+d] removes the highlighted backend. A credential that comes from the environment is reported but never deleted — a process cannot unset a variable it does not own.

Which backend answers is a separate choice from which keys exist: /jev-eye models writes ~/.pi/agent/pi-jev-eye/backends.json ({ "primary": "cloudflare:clef-flash", "fallback": "typesafe:jev-latest" }). Either slot may be empty, in which case the credential precedence above applies. The fallback is called only after the active backend fails outright — a non-OK response, a rejected envelope, a timeout, or a network error — and /jev-eye status counts how often that happened.

To test locally without installing:

pi -e ./extensions/index.ts

Shortcuts & Commands

Providers

Which one is active is a choice, not a login side effect: the store keeps every key you have, and /jev-eye models decides which one answers — with a fallback behind it for the turns where the active backend cannot reply at all. The Clef model list is read from Cloudflare's model-discovery route once per session, so a model published upstream (e.g. clef-omni) is selectable without a package release.

Why Clef

Clef is Cloudflare's decision model (@cf/cloudflare/clef). It answers the same typed System One questions the gate already asks (noul / choice / score), so switching the backend changes no gate logic — only the route and the credential. Two properties make it the cheapest way to run the gate per write:

• Free for normal sessions. Every account gets 10,000 neurons per day, reset at 00:00 UTC. clef-flash bills 3,455 neurons per million input tokens, so a typical session stays inside the allowance; /jev-eye usage shows the exact figure and the overage cost ($0.011/1,000 neurons) once it does not.
• No output-token billing. Clef charges input tokens only, so its cost is a function of the diff you send, not of the model's reasoning length.

The credential is the account id plus a Workers AI token (Workers AI: Read) — a token alone cannot build the account-scoped route. The account id is checked as 32 hex characters and the credential is probed against the real run route before anything is saved.

The Cloudflare route is …/accounts/{ACCOUNT_ID}/ai/run/@cf/cloudflare/clef-flash; the account id is validated (32 hex chars) and the credential is probed against that exact route before it is saved. Clef interprets the same typed questions (noul / choice / score), so no gate logic changes per provider.

Notes:

• pi-arnative status bar: Shows the real-time mode and the active backend: Eye: ● ON (Clef Flash) / Eye: ● REVIEW (Jev) / Eye: ○ OFF (Jev). The suffix follows /jev-eye models, so it changes without a reload.
• Why these chords: ctrl+alt+<letter> is the portable shape. Legacy terminals send it as an ESC-prefixed ctrl code, the kitty protocol as a CSI-u sequence, and pi's parser accepts both. Ghostty binds no ctrl+alt+<letter> (its chords are ctrl+alt+<arrow> and ctrl+alt+shift+j), foot binds none, and pi binds only ctrl+alt+]. ctrl+shift+<letter> is the shape this package left behind: Ghostty owns ctrl+shift+e (new_split:down) and ctrl+shift+t (new_tab), and macOS maps Cmd+Shift+letter to super+shift. A terminal without the kitty protocol also reports a shifted chord as the plain ctrl code — ctrl+shift+t then never matches at all, which is the bug it looks like it has.

Modes

Ctrl+Alt+E ──► ON ──► REVIEW ──► OFF ──┐
                 ▲                     │
                 └─────────────────────┘

Architecture

Agent Action (tool_call / message_end)
       │
       ▼
[Layer 1: Local Regex Gate]     ──► rm -rf / force-push / secret? ──► [BLOCKED INSTANTLY] (0 ms, 0 token)
       │ (Safe)
       ▼
[Layer 2: Done-Check Tracker]   ──► Files modified but claims done without test? ──► [WARNING NOTICE] (0 token)
       │ (Passed)
       ▼
[Layer 3: Jev Semantic Gate]    ──► New code diff ≥ 10 lines? ──► [JEV SLOP EVAL] (P ≥ 0.85 blocked)

• Layer 1 (extensions/layer1.ts): Pre-execution regex filter. Blocks destructive bash wipes (rm -rf /, rm -rf $HOME, git reset --hard, DROP DATABASE, mkfs), protected branch force-pushes (main/master, while safely permitting --force-with-lease), and secret leaks (sk-..., ghp_..., AIza..., private SSH keys).
• Layer 2: Turn monitor. Tracks file modifications during a turn and prompts the agent if it declares completion without invoking recognized test suites (npm test, pnpm test, bun test, cargo test, cargo check, pytest, mypy, ruff, go test, vitest).
• Layer 3: Post-generation gate. Submits code diffs ≥ 10 lines in opt-in folders to TypeSafe Jev as a single batch request (has_slop, has_unfinished_todo, and prompt alignment answers_request on reviewed turns). Blocks when p ≥ 0.85 with actionable diagnostics.

Run /jev-eye routing to open the interactive model selector:

• Light Model: Routine chores (status, commit, push, log, diff) route to the light model with zero Jev requests.
• Heavy Model: Substantive coding and review tasks route to the heavy model.
• Independent Thinking: Each slot walks its own range — light off → minimal → low → medium → high, heavy low → medium → high → xhigh → max — so a chore can be silenced while a review is pinned deep.
• Context Guard: Prevents overflow by staying on the heavy/current model if context exceeds 30k tokens or 50% window.
• Same backend chain as the gate: Routing classification and the write gate both call the active backend from /jev-eye models, then its fallback — so a stalled provider delays one turn instead of losing the classification.
• Theme-Adaptive TUI: Automatically matches active Pi theme tokens (accent, muted, dim, success).

Tracks detailed usage in ~/.pi/agent/pi-jev-eye/usage.json (plus legacy migration from ~/.pi/agent/pi-typesafe/usage.json):

• Each day keeps the overall counters and an optional per-provider map, so /jev-eye usage can split Jev (TypeSafe/OpenRouter) from Clef without reading a second file. Entries written before this field read as 0 and are never invented.

• Cloudflare is billed in neurons, not dollars only: the panel shows today's neuron count against the 10,000/day free allowance (reset 00:00 UTC) and the overage at $0.011/1,000 neurons. The rate is per model — clef 21,818 neurons/M input, clef-flash 3,455, clef-omni 13,636 — and output tokens are not billed.

• Daily & Monthly Telemetry: Request counts (success/fail), token counters (input/output), and estimated dollar cost.

• Provider Balance: Live credit lookup for OpenRouter accounts (/api/v1/key).

• Interception Stats: Cumulative counts of Layer 1 regex blocks, Layer 2 done-check reminders, Layer 3 slop rejections, and reviewed turns.

npm test             # Pure logic, frame maths, and the failover path (offline, no dependencies)
npm run render-check # Renders the real screens and asserts the frame width, colour and legends
npm run dev          # Test extension locally in active session

npm run render-check drives /jev-eye through a fake TUI and asserts what a screenshot would show: every line exactly on the terminal width, a coloured frame, a masked key, one divider column across every list, and no advertised key lost to truncation. The legend check reads KEY_SETS, so a key that drifts from the handler fails the command instead of lying in the footer. It needs the peer dependencies resolvable, so run it where pi provides them, or link a checkout that has them: ln -s ../pi-arnative/node_modules node_modules.

Modules

extensions/ is layered leaf-first; a file imports only the ones above it. npm test covers layer1.ts, review.ts (the trigger and the contract text, whose statements are pinned so they cannot drift from the gate they describe) and providers.ts (the failover path: authChain resolution and the chain walk, with a stubbed fetch); npm run render-check covers every screen and the /eye handler.

License

Distributed under the MIT license.

Author

Bisma