pi-jev-guard 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# pi-jev-guard
+
+Verifica le risposte con [TypeSafe Jev](https://docs.typesafe.ai) dentro [pi](https://pi.dev): un solo motore di validazione, due interfacce.
+
+- **A richiesta** (default): tool `jev_validate`, comando `/jev check`, skill `jev-review`. Zero verifiche implicite, zero costi se non lo usi.
+- **Domande tipate**: tool `jev_ask` per giudizi calibrati definiti dal modello (noul/choice/score) invece di prosa.
+- **Automatica**: gemello guarded `<modello>__jev` dentro lo stesso provider, che trattiene la risposta, la verifica con Jev e pubblica solo l'output approvato (con rigenerazione privata su `block`). Stessa auth del provider: nessun login extra, funziona anche con Codex/OAuth.
+- **Giudice output** (solo `automatic`, fail-open): dopo ogni `bash` cerca secret nel testo e classifica i fallimenti, allegando un consiglio al risultato.
+
+## Installazione
+
+```bash
+cd pi-jev-guard
+npm install
+mkdir -p ~/.pi/agent
+cp config/jev-config.example.json ~/.pi/agent/jev-config.json
+pi install "$PWD"
+```
+
+Chiavi (a seconda del backend Jev scelto):
+
+```bash
+export OPENROUTER_API_KEY="sk-or-v1-..."   # backend openrouter (default)
+export TYPESAFE_API_KEY="..."              # backend typesafe diretto
+```
+
+## Uso normale (invariato)
+
+Con l'estensione installata non cambia nulla finché non la usi: i modelli normali restano selezionabili e nessuna verifica parte da sola (`mode: on-demand`).
+
+```text
+/jev check ./src/example.ts        # verifica singola di un file
+/jev status                        # stato completo
+/jev help                          # tutti i sottocomandi
+```
+
+In chat, l'LLM può chiamare `jev_validate` per controlli mirati.
+
+## Uso protetto
+
+```text
+/jev upstream deepseek deepseek-flash   # crea deepseek/deepseek-flash__jev
+/jev mode automatic                    # seleziona il twin + attiva enforcement
+```
+
+Nessun login extra: il twin vive nello stesso provider e riusa la credenziale già configurata (env, stored, OAuth/SSO come Codex business plan). I modelli originali restano intatti e selezionabili.
+
+Torna normale con `/model` (modello normale) + `/jev mode on-demand`.
+In `automatic`, selezionare un modello non protetto lo fa ritornare
+subito al twin (enforcement a livello selezione).
+`/jev upstream` senza argomenti ripristina l'ultimo salvato, `/jev off` rimuove il twin
+(e torna a on-demand, provider originale ripristinato). In `automatic` il twin
+si ripristina da solo al riavvio.
+
+Se filtri i modelli con `enabledModels`, tieni la voce del twin (es.
+`deepseek/deepseek-flash__jev`) o resta nascosto.
+L'installazione punta alla cartella: dopo un aggiornamento del codice basta `/reload`.
+
+Headless/CI: `JEV_AUTO_UPSTREAM=provider/model` crea il guarded all'avvio
+(con `pi --print` solo `deepseek/deepseek-flash`).
+
+## Come decide
+
+Jev risponde a domande `noul` (probabilità 0–1 di "sì, c'è la falla"):
+
+| Regola | Gate automatic | On-demand |
+|---|---|---|
+| `sql_injection` | ✓ | ✓ |
+| `unsafe_destructive_action` | ✓ | ✓ |
+| `requirement_conflict` | — (requisiti chat troppo vaghi) | ✓ (requisiti espliciti) |
+
+Soglie preliminari calibrate live (`docs/calibration-2026-09-19.md`):
+`p ≤ 0.20` pass · `p ≥ 0.90` block · in mezzo review (trattenuto) ·
+errori/timeout → unavailable (trattenuto). Mai approvazione su input troncato:
+un pass parziale diventa review dichiarata. I candidati lunghi sono verificati
+a chunk (copertura completa); i requisiti oltre 16k trattengono con nota.
+
+In `automatic` è attiva anche una **tool policy deterministica** (costo zero):
+blocca comandi distruttivi (`rm -rf /`, fork bomb, `mkfs`, `dd` su device…)
+e scritture su path sensibili (`.env`, `.ssh/`, `*.pem`, `node_modules/`).
+In `on-demand` non blocca nulla. Sempre in `automatic`, i comandi con tool
+di rete (`curl`, `scp`, `ssh`…) passano un check semantico Jev
+(destructive/exfiltration/beyond_scope/impact): su flag chiede conferma
+in TUI, in headless solo avviso (fail-open).
+
+Sempre in `automatic`, il **giudice output** esamina i risultati `bash`
+(1 chiamata Jev per output nuovo, con cache 120s): se trova un secret
+avvisa e dice di riferirsi al valore per nome; se è un errore, allega il
+consiglio per la classe (`transient` → riprova, `code_bug` → fixa il codice…).
+Non blocca mai; `/jev output` mostra l'ultimo verdetto.
+
+## Configurazione
+
+`~/.pi/agent/jev-config.json` (o `$JEV_CONFIG`). Env: `JEV_MODE`, `JEV_BACKEND`
+(`openrouter`|`typesafe`|`auto`), `JEV_MODEL`, `JEV_AUTO_UPSTREAM`.
+Vedi `config/jev-config.example.json` per tutti i campi.
+
+Chiave Jev (ordine: env vince sul file): `OPENROUTER_API_KEY` o
+`TYPESAFE_API_KEY`, altrimenti `jev.apiKeyFile` (es.
+`"~/.pi/agent/jev-api-key.txt"`, `~/` espanso, solo prima riga, permessi
+`600` consigliati). `/jev status` mostra la sorgente (`env:VAR`,
+`file:<path>`, o il motivo se assente) — mai il valore.
+
+Per salvare la chiave stando dentro pi (senza passarla come argomento,
+che resterebbe in history e transcript):
+
+```text
+/jev save-key   # chiede la chiave via dialogo, la scrive a 600, ricarica
+```
+
+Nota: il dialogo TUI potrebbe fare echo nel terminale; per massima
+paranoia usa la shell: `umask 077 && cat > ~/.pi/agent/jev-api-key.txt`.
+
+I verdetti identici sono riusati per 120s (`reviewCache`, mai gli
+`unavailable`): retry e batch paralleli costano una sola chiamata.
+Gli input oltre i limiti sono marcati `…[N chars elided]` nel testo inviato
+a Jev, mai troncati in silenzio.
+
+Retry solo su transienti (`jev.retryTransients`, default 1 retry): 429/5xx
+ed errori di connessione ritentano con backoff, timeout e auth mai — un
+rate-limit non diventa più subito hold. `/jev last` mostra l'ultimo
+verdetto del gate (esito, tentativi, controllo con p, backend, tempo).
+
+## Sviluppo
+
+```bash
+npm run typecheck
+npm run test:unit            # mock, nessun costo
+npm run test:integration
+RUN_JEV_LIVE=1 npm run bench:jev   # corpus live (costa poco)
+echo '{"requirements":"...","candidate":"..."}' | npm run jev-check
+```
+
+## Limiti onesti
+
+- `pass` = "supera i controlli configurati", non "corretto". Compilazione e test restano necessari.
+- Il gate copre solo il twin `__jev` selezionato; in `automatic` la
+  selezione di altri modelli viene rifiutata con revert al twin.
+  (`/jev off` ripristina il provider originale intatto.)
+- Soglie calibrate su 20 casi (`docs/calibration-2026-09-19.md`): buone per
+  iniziare, da rivalutare con corpus più ampio.
+- Jev è un giudice probabilistico, non un verificatore formale.

package/config/jev-config.example.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "mode": "on-demand",
+  "jev": {
+    "backend": "openrouter",
+    "modelTypesafe": "jev-1.13.0",
+    "modelOpenRouter": "typesafe/jev-1.13",
+    "timeoutMs": 4000,
+    "timeoutMsTypesafe": 1500,
+    "timeoutMsOpenRouter": 4000,
+    "retryTransients": { "enabled": true, "maxRetries": 1 },
+    "apiKeyFile": "~/.pi/agent/jev-api-key.txt"
+  },
+  "policy": {
+    "revision": "2026-09-19-live1",
+    "passMaxFlawProbability": 0.2,
+    "blockMinFlawProbability": 0.9,
+    "onUncertain": "hold",
+    "onUnavailable": "hold"
+  },
+  "automatic": {
+    "transport": "provider-gate",
+    "maxRegenerations": 2,
+    "requireGuardedModel": true,
+    "upstreamProvider": "deepseek",
+    "upstreamModel": "deepseek-flash"
+  },
+  "limits": {
+    "maxPayloadBytes": 120000,
+    "maxBufferedBytes": 1048576,
+    "maxCodeBlocks": 24,
+    "maxRequirementsChars": 16000,
+    "maxCandidateChars": 100000
+  },
+  "privacy": {
+    "logContent": false
+  },
+  "reviewCache": {
+    "enabled": true,
+    "cacheSeconds": 120
+  },
+  "toolsPolicy": {
+    "enabled": true
+  },
+  "outputJudge": {
+    "enabled": true,
+    "tools": ["bash"],
+    "outputChars": 2000,
+    "leakThreshold": 0.9,
+    "minConfidence": 0.6,
+    "cacheSeconds": 120
+  },
+  "exfilCheck": {
+    "enabled": true,
+    "tools": ["bash", "powershell"],
+    "blockOn": { "destructive": 0.9, "exfiltration": 0.7, "beyondScope": 0.85, "impact": 2.5 },
+    "minConfidence": 0.5,
+    "cacheSeconds": 120,
+    "blockWithoutUI": false
+  }
+}