pi-jev-guard 0.2.1 → 0.3.0

package/README.md

@@ -54,6 +54,29 @@ In chat, l'LLM può chiamare `jev_validate` per controlli mirati.
 /jev mode automatic                           # seleziona il primario + attiva enforcement
 ```
 
+### Backend e chiavi
+
+Due backend, stessa policy e stesse regole:
+
+| Backend | Endpoint | Variabile | Modello | Timeout |
+|---|---|---|---|---|
+| `openrouter` (default) | OpenRouter | `OPENROUTER_API_KEY` | `typesafe/jev-1.13` | 4000 ms |
+| `typesafe` | SDK ufficiale `@typesafe-ai/sdk` → `api.typesafe.ai` | `TYPESAFE_API_KEY` | `jev-1.13.0` | 1500 ms |
+| `auto` | sceglie il backend che ha una chiave (entrambe → OpenRouter) | — | — | — |
+
+```text
+/jev backend                    # stato: backend, modello, chiavi rilevate
+/jev backend typesafe           # cambia backend (salvato in jev-config.json)
+/jev save-key typesafe          # salva la chiave del backend (file 600)
+/jev save-key openrouter        # l'altra chiave resta dov'è
+/jev key-file                   # dove viene cercata la chiave
+```
+
+Le chiavi stanno in file separati (`jev-api-key.<backend>.txt` accanto alla
+config), quindi i due backend possono coesistere. Precedenza: variabile
+d'ambiente → file del backend → file generico `jev.apiKeyFile` → percorso
+canonico. Vedi `config/jev-config.example.json`.
+
 **Più twin insieme**: ogni `/jev upstream` *aggiunge* un modello guarded, senza
 rimuovere i precedenti. I twin vengono registrati anche all'avvio (i modelli
 dinamici come Codex sono letti dal models-store), quando gli originali sono disponibili.
@@ -76,8 +99,15 @@ ne rimuove uno solo, `/jev off` li rimuove tutti
 `/jev off` conserva il catalogo salvato: al reload gli alias tornano disponibili,
 ma il gate rimane disattivato.
 
-Se filtri i modelli con `enabledModels`, tieni le voci `__jev` dei twin che usi
-o restano nascosti.
+Se filtri i modelli con `enabledModels`, usa i glob invece delle voci esplicite,
+così i twin futuri non restano nascosti:
+
+```json
+"enabledModels": ["openai-codex/*__jev", "deepseek/*__jev", "...altri pattern..."]
+```
+
+Dopo aver aggiunto un twin serve `/reload` (lo scope è risolto all'avvio della sessione).
+`/jev upstream` avvisa subito quando il twin appena creato è fuori dal picker.
 L'installazione punta alla cartella: dopo un aggiornamento del codice basta `/reload`.
 
 Headless/CI: `JEV_MODE=automatic JEV_AUTO_UPSTREAM=provider/model` crea e attiva
@@ -85,6 +115,11 @@ il guarded nelle sessioni senza uno stato Jev salvato.
 
 Un hold `[JEV — OUTPUT NON PUBBLICATO]` interrompe intenzionalmente il turno:
 controlla `/jev last`. Non viene aggirato con un proseguimento automatico.
+
+Verdetto **incerto** (`review`): il gate tenta prima una riga riparazione privata
+(`automatic.repairOnReview`, default `true`), poi applica la policy configurata:
+`policy.onUncertain` e `policy.onUnavailable` (`"hold"` default, oppure `"pass"`).
+Con `"pass"` il testo viene pubblicato con una nota di trasparenza sul verdetto.
 Le conferme per comandi di rete sospetti attendono invece una decisione esplicita;
 la normale sequenza tool → risposta successiva continua senza un nuovo prompt.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jev-guard",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Jev validation guard for pi: on-demand tool + automatic provider gate. Dual backend: TypeSafe direct + OpenRouter.",
   "keywords": [

package/skills/jev-review/SKILL.md

@@ -23,3 +23,7 @@ Run the appropriate compiler, static checks, or targeted tests separately.
 For ad-hoc typed judgements (classification, relevance, rubric scores) use
 `jev_ask` with model-defined questions instead; read p >= 0.90 as yes,
 p <= 0.20 as no, and choice/score below 0.60 confidence as uncertain.
+
+Questa skill riguarda i tool di verifica di pi-jev-guard. Per progettare
+integrazioni con TypeSafe (System One, SDK, cookbook) usa la skill ufficiale
+`typesafe-ai` se installata.

package/src/automatic/guardian.ts

@@ -130,6 +130,26 @@ export async function consumePrivate(
   return final;
 }
 
+/** Aggiunge una riga di trasparenza sul verdetto non conclusivo. */
+function uncertainNotice(verdict: ReviewResult): string {
+  const top = [...verdict.checks].sort((a, b) => b.pFlaw - a.pFlaw)[0];
+  const detail = top ? ` (${top.ruleId} p=${top.pFlaw.toFixed(3)})` : "";
+  const reason = verdict.errorCode ? ` errore=${verdict.errorCode}` : "";
+  return `\n\n> [jev] verdetto non conclusivo: ${verdict.status}${detail}${reason} — pubblicato per policy onUncertain/onUnavailable=pass.`;
+}
+
+/** Copia del candidato con la nota accodata all'ultimo blocco di testo. */
+function withNotice(message: AssistantMessage, notice: string): AssistantMessage {
+  const content = message.content.map((block) => ({ ...block }));
+  const last = [...content].reverse().find((block) => block.type === "text");
+  if (last && last.type === "text") {
+    last.text = `${last.text}${notice}`;
+  } else {
+    content.push({ type: "text", text: notice.trimStart() });
+  }
+  return { ...message, content };
+}
+
 function assertCompleteCandidate(message: AssistantMessage): void {
   // Rifiuta terminali non supportati per pubblicazione.
   if (
@@ -177,6 +197,10 @@ export function runGuardedStream(
     const usages: Usage[] = [];
     let attemptContext = originalContext;
     const maxRegenerations = deps.config.automatic.maxRegenerations;
+    // Un verdetto incerto non è un difetto accertato: un solo tentativo di
+    // riparazione mirata evita l'hold immediato su prosa borderline.
+    const maxReviewRepairs = deps.config.automatic.repairOnReview === false ? 0 : 1;
+    let reviewRepairs = 0;
 
     try {
       for (let attempt = 0; attempt <= maxRegenerations; attempt++) {
@@ -224,10 +248,11 @@ export function runGuardedStream(
         }
         signal?.throwIfAborted();
 
-        if (verdict.status === "pass") {
+        const publishCandidate = async (notice?: string): Promise<void> => {
           deps.onVerdict?.({ verdict, attempts: attempt + 1, outcome: "published" });
+          const approved = notice ? withNotice(candidate, notice) : candidate;
           const aggregated = aggregateUsage(usages);
-          const replayed = replayApproved(candidate, {
+          const replayed = replayApproved(approved, {
             provider: deps.publishedProvider,
             model: deps.publishedModel,
             usage: aggregated,
@@ -239,10 +264,19 @@ export function runGuardedStream(
           }
           const final = await replayed.result();
           out.end(final);
+        };
+
+        if (verdict.status === "pass") {
+          await publishCandidate();
           return;
         }
 
-        if (verdict.status === "block" && attempt < maxRegenerations) {
+        const canRepair =
+          verdict.status === "block"
+            ? attempt < maxRegenerations
+            : verdict.status === "review" && reviewRepairs < maxReviewRepairs;
+        if (canRepair) {
+          if (verdict.status === "review") reviewRepairs++;
           attemptContext = buildRepairContext({
             originalContext,
             rejectedText: rawCandidate,
@@ -252,6 +286,15 @@ export function runGuardedStream(
           continue;
         }
 
+        // Policy esplicita per i verdetti non conclusivi (config, non silenziosa).
+        const uncertainPass = verdict.status === "review" && deps.config.policy.onUncertain === "pass";
+        const unavailablePass =
+          verdict.status === "unavailable" && deps.config.policy.onUnavailable === "pass";
+        if (uncertainPass || unavailablePass) {
+          await publishCandidate(uncertainNotice(verdict));
+          return;
+        }
+
         // Hold: pubblica failure sicura, mai il candidato bocciato.
         const attempts = attempt + 1;
         deps.onVerdict?.({ verdict, attempts, outcome: "held" });

package/src/commands.ts

@@ -6,7 +6,9 @@ import { isTwinId, untwinId } from "./automatic/overlay.ts";
 import type { JevConfig, TwinRef } from "./config.ts";
 import {
   defaultConfigPath,
+  defaultKeyFileFor,
   expandHome,
+  keyFileCandidates,
   parseUpstreamRef,
   resolveBackend,
   saveConfig,
@@ -86,6 +88,7 @@ export const JEV_SUBCOMMANDS = [
   "reload",
   "output",
   "last",
+  "backend",
   "save-key",
   "help",
 ] as const;
@@ -108,7 +111,12 @@ export const JEV_HELP_TEXT = [
   "  /jev stats               Conteggi pass/block/review/unavailable + latenze",
   "  /jev output              Ultimo output giudicato: leak + classe errore",
   "  /jev last                Ultimo verdetto del gate (twin): esito e controlli",
-  "  /jev save-key            Salva la chiave Jev su file (permessi 600)",
+  "  /jev backend             Mostra backend attivo e chiavi rilevate",
+  "  /jev backend auto|openrouter|typesafe",
+  "                           Cambia backend (salvato in jev-config.json)",
+  "  /jev save-key [backend]  Salva la chiave del backend (default: attivo), 600",
+  "                           auto e typesafe tengono file separati",
+  "  /jev key-file [backend]  Mostra dove viene cercata la chiave",
   "  /jev reload              Ricarica jev-config.json da disco",
   "  /jev help                Questo aiuto",
   "",
@@ -133,6 +141,20 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
       const parts = args.trim().split(/\s+/).filter(Boolean);
       const sub = parts[0] ?? "status";
 
+      // Terza domanda del picker: registrato, visibile, selezionato. Il twin
+      // appena creato non è mai nello scope risolto a inizio sessione.
+      function twinInScope(provider: string, modelId: string): boolean {
+        try {
+          const scoped = ctx.scopedModels ?? [];
+          if (scoped.length === 0) return true;
+          return scoped.some(
+            (s) => s.model.provider === provider && s.model.id === `${modelId}__jev`,
+          );
+        } catch {
+          return true;
+        }
+      }
+
       // Never unregister the route while a synthetic model is still selected.
       // The caller must disable automatic enforcement before switching away.
       async function leaveSelectedTwin(): Promise<boolean> {
@@ -310,10 +332,15 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
           return;
         }
         const total = deps.twinStatus().active.length;
+        const visible = twinInScope(parsed.provider, parsed.model);
         ctx.ui.notify(
           `Twin aggiunto: ${res.twin} (totale attivi: ${total}, stessa auth del provider). ` +
-            `Selezionalo con /model per enforcement in automatic.`,
-          "info",
+            (visible
+              ? "Selezionalo con /model per enforcement in automatic."
+              : `ATTENZIONE: non compare in /model — enabledModels non lo copre. ` +
+                `Aggiungi "${parsed.provider}/*__jev" a enabledModels e fai /reload, ` +
+                `oppure attivalo direttamente con /jev mode automatic.`),
+          visible ? "info" : "warning",
         );
         return;
       }
@@ -336,7 +363,8 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
           const key = `${ref.provider}/${ref.model}`;
           const mark = activeKeys.has(key) ? "● " : "○ ";
           const star = key === primaryKey ? "★" : " ";
-          lines.push(`${mark}${star} ${key}${activeKeys.has(key) ? "" : "  (non attivo)"}`);
+          const hidden = twinInScope(ref.provider, ref.model) ? "" : "  (fuori dal picker)";
+          lines.push(`${mark}${star} ${key}${activeKeys.has(key) ? "" : "  (non attivo)"}${hidden}`);
         }
         ctx.ui.notify(
           [
@@ -458,11 +486,102 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
         return;
       }
 
+      if (sub === "backend") {
+        const cfg = deps.config();
+        const resolved = resolveBackend(cfg);
+        const requested = parts[1];
+        if (requested === undefined) {
+          const backendStatus = (["openrouter", "typesafe"] as const)
+            .map((b) => {
+              const key = resolveBackend({ ...cfg, jev: { ...cfg.jev, backend: b } });
+              const files = keyFileCandidates(cfg, b).map((f) => expandHome(f));
+              return `  ${b}: ${key.apiKeyPresent ? "chiave OK" : "chiave assente"} (${key.keySource})` +
+                (files.length > 0 ? `\n    file: ${files.join(", ")}` : "");
+            })
+            .join("\n");
+          ctx.ui.notify(
+            [
+              `Backend: ${cfg.jev.backend} → effettivo ${resolved.backend} (${resolved.reason})`,
+              `Modello: ${resolved.model}`,
+              backendStatus,
+              "",
+              `Cambia con: /jev backend auto|openrouter|typesafe. Salva la chiave con /jev save-key ${resolved.backend}.`,
+            ].join("\n"),
+            "info",
+          );
+          return;
+        }
+        if (requested !== "auto" && requested !== "openrouter" && requested !== "typesafe") {
+          ctx.ui.notify("Uso: /jev backend auto|openrouter|typesafe", "warning");
+          return;
+        }
+        const shared = deps.sharedConfig?.() ?? cfg;
+        const next: JevConfig = {
+          ...shared,
+          jev: { ...shared.jev, backend: requested },
+        };
+        let savedPath: string | undefined;
+        try {
+          savedPath = saveConfig(next);
+        } catch (error) {
+          ctx.ui.notify(
+            `Jev: backend non salvato: ${error instanceof Error ? error.message : String(error)}`,
+            "error",
+          );
+          return;
+        }
+        const reloaded = deps.reload();
+        const after = resolveBackend(reloaded);
+        ctx.ui.notify(
+          [
+            `Backend impostato: ${requested} → effettivo ${after.backend} (${after.reason}).`,
+            `Modello: ${after.model}`,
+            after.apiKeyPresent
+              ? `Chiave: ${after.keySource}`
+              : `ATTENZIONE: nessuna chiave per ${requested}. Salvala con /jev save-key${requested === "auto" ? "" : ` ${requested}`}.`,
+            savedPath ? `Config: ${savedPath}` : "",
+          ]
+            .filter((l) => l !== "")
+            .join("\n"),
+          after.apiKeyPresent ? "info" : "warning",
+        );
+        return;
+      }
+
+      if (sub === "key-file") {
+        const cfg = deps.config();
+        const which = parts[1];
+        const backends = (["openrouter", "typesafe"] as const).filter(
+          (b) => which === undefined || which === b,
+        );
+        if (backends.length === 0) {
+          ctx.ui.notify("Uso: /jev key-file [openrouter|typesafe]", "warning");
+          return;
+        }
+        const lines = backends.map((b) => {
+          const files = keyFileCandidates(cfg, b);
+          return `${b}: ` + (files.length > 0
+            ? files.map((f) => expandHome(f)).join(" → ")
+            : `(nessun file; default /jev save-key ${b} → ${defaultKeyFileFor(b)})`);
+        });
+        ctx.ui.notify(
+          [...lines, "", "Precedenza: variabile d'ambiente, poi file specifico del backend, poi il file generico."].join("\n"),
+          "info",
+        );
+        return;
+      }
+
       if (sub === "save-key") {
         const cfg = deps.config();
-        let target = cfg.jev.apiKeyFile?.trim()
-          ? expandHome(cfg.jev.apiKeyFile.trim())
-          : resolve(dirname(defaultConfigPath()), "jev-api-key.txt");
+        const which = parts[1];
+        const backend: "openrouter" | "typesafe" =
+          which === "openrouter" || which === "typesafe"
+            ? which
+            : resolveBackend(cfg).backend;
+        // Le chiavi sono per-backend: auto e typesafe possono coesistere.
+        let target = cfg.jev.apiKeyFiles?.[backend]?.trim()
+          ? expandHome(cfg.jev.apiKeyFiles[backend]!.trim())
+          : defaultKeyFileFor(backend);
         // Mai chiavi in tmp: dir effimera (pulizia automatica = chiave persa).
         // Può capitare con config stantie caricate in memoria prima di un fix.
         if (target === tmpdir() || target.startsWith(tmpdir() + "/")) {
@@ -470,12 +589,12 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
             `Jev: percorso chiave sotto tmp ignorato (${target}); uso quello canonico.`,
             "warning",
           );
-          target = resolve(dirname(defaultConfigPath()), "jev-api-key.txt");
+          target = defaultKeyFileFor(backend);
         }
         let key: string | undefined;
         try {
           key = await ctx.ui.input(
-            "Jev API key",
+            `Jev API key (${backend})`,
             "Incolla la chiave (potrebbe fare echo nel terminale)",
           );
         } catch {
@@ -494,20 +613,31 @@ export function registerJevCommand(pi: ExtensionAPI, deps: JevCommandDeps) {
           ctx.ui.notify(`Jev: salvataggio fallito: ${error instanceof Error ? error.message : String(error)}`, "error");
           return;
         }
-        // Punta la config al file e ricarica gli handle col nuovo stato.
-        cfg.jev.apiKeyFile = target;
+        // Punta la config al file del backend e ricarica gli handle.
+        const shared = deps.sharedConfig?.() ?? cfg;
+        const next: JevConfig = {
+          ...shared,
+          jev: {
+            ...shared.jev,
+            apiKeyFiles: { ...shared.jev.apiKeyFiles, [backend]: target },
+          },
+        };
         try {
-          saveConfig({ ...cfg, mode: deps.sharedConfig?.().mode ?? cfg.mode });
+          saveConfig(next);
         } catch {
           // Resta in memoria anche se il salvataggio fallisce.
         }
         const reloaded = deps.reload();
         const resolved = resolveBackend(reloaded);
+        const legacyNote =
+          shared.jev.apiKeyFile && shared.jev.apiKeyFile !== target
+            ? ` Nota: resta anche il file generico ${expandHome(shared.jev.apiKeyFile)} (usato come ripiego).`
+            : "";
         ctx.ui.notify(
-          resolved.apiKeyPresent
-            ? `Jev: chiave salvata in ${target} (600). Sorgente: ${resolved.keySource}.`
-            : `Jev: file scritto ma chiave non rilevata (${resolved.keySource}).`,
-          resolved.apiKeyPresent ? "info" : "warning",
+          resolved.backend === backend && resolved.apiKeyPresent
+            ? `Jev: chiave ${backend} salvata in ${target} (600). Sorgente: ${resolved.keySource}.${legacyNote}`
+            : `Jev: file scritto, ma il backend effettivo è ${resolved.backend} (${resolved.keySource}).${legacyNote}`,
+          resolved.backend === backend && resolved.apiKeyPresent ? "info" : "warning",
         );
         return;
       }

package/src/config.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import type { JevBackend } from "./reviewer.ts";
 
 export type JevMode = "on-demand" | "automatic";
@@ -20,6 +20,8 @@ export interface JevConfig {
     retryTransients: { enabled: boolean; maxRetries: number };
     /** Percorso file con la chiave per il backend attivo (alternativa all'env, `~/` espanso). */
     apiKeyFile?: string;
+    /** File chiave dedicati per backend: permettono di tenerle entrambe. */
+    apiKeyFiles?: { openrouter?: string; typesafe?: string };
   };
   policy: {
     revision: string;
@@ -31,6 +33,8 @@ export interface JevConfig {
   automatic: {
     transport: "provider-gate";
     maxRegenerations: number;
+    /** Tentativo privato extra quando il verdetto è incerto (review). */
+    repairOnReview: boolean;
     requireGuardedModel: boolean;
     /** Twin salvati: più modelli guarded insieme (uno o più per provider). */
     twins: TwinRef[];
@@ -121,6 +125,7 @@ export const DEFAULT_CONFIG: JevConfig = {
   automatic: {
     transport: "provider-gate",
     maxRegenerations: 2,
+    repairOnReview: true,
     requireGuardedModel: true,
     twins: [],
     // Vuoti di default: nessun twin "salvato" finché l'utente non ne aggiunge
@@ -274,28 +279,69 @@ interface BackendKey {
   source: string;
 }
 
+/**
+ * File chiave da provare, in ordine: specifico del backend, generico,
+ * poi il percorso canonico per-backend (chiave lasciata lì senza config).
+ */
+/** Solo i file dichiarati in config (errori di lettura da segnalare). */
+export function configuredKeyFiles(config: JevConfig, backend: JevBackend): string[] {
+  const paths: string[] = [];
+  const push = (path: string | undefined) => {
+    const trimmed = path?.trim();
+    if (trimmed && !paths.includes(trimmed)) paths.push(trimmed);
+  };
+  push(config.jev.apiKeyFiles?.[backend]);
+  push(config.jev.apiKeyFile);
+  return paths;
+}
+
+export function keyFileCandidates(config: JevConfig, backend: JevBackend): string[] {
+  const paths = configuredKeyFiles(config, backend);
+  const canonical = defaultKeyFileFor(backend);
+  if (!paths.includes(canonical)) paths.push(canonical);
+  return paths;
+}
+
 function resolveKeyFor(
   backend: JevBackend,
-  apiKeyFile: string | undefined,
+  files: { candidates: string[]; configured: string[] },
 ): BackendKey {
   const envVar = backend === "typesafe" ? "TYPESAFE_API_KEY" : "OPENROUTER_API_KEY";
   const fromEnv = process.env[envVar]?.trim();
   if (fromEnv) return { key: fromEnv, source: `env:${envVar}` };
-  const file = readKeyFile(apiKeyFile);
-  if (file.key) return { key: file.key, source: `file:${file.tried}` };
-  if (file.tried) {
-    return { key: undefined, source: `none (file ${file.tried}: ${file.error})` };
+
+  const problems: string[] = [];
+  for (const path of files.candidates) {
+    const file = readKeyFile(path);
+    if (file.key) return { key: file.key, source: `file:${file.tried}` };
+    // Il percorso canonico mancante è atteso: non è un problema da mostrare.
+    if (file.error && files.configured.includes(path)) {
+      problems.push(`file ${file.tried}: ${file.error}`);
+    }
   }
-  return { key: undefined, source: `none (set ${envVar} or jev.apiKeyFile)` };
+  if (problems.length > 0) {
+    return { key: undefined, source: `none (${problems.join("; ")})` };
+  }
+  return {
+    key: undefined,
+    source: `none (set ${envVar} or /jev save-key ${backend})`,
+  };
+}
+
+/** Percorso canonico del file chiave per un backend (accanto alla config). */
+export function defaultKeyFileFor(backend: JevBackend): string {
+  return resolve(dirname(defaultConfigPath()), `jev-api-key.${backend}.txt`);
 }
 
 export function resolveBackend(config: JevConfig): ResolvedBackend {
   const setting = config.jev.backend;
-  const keyFile = config.jev.apiKeyFile;
 
   if (setting === "typesafe" || setting === "openrouter") {
     const backend = setting;
-    const resolved = resolveKeyFor(backend, keyFile);
+    const resolved = resolveKeyFor(backend, {
+      candidates: keyFileCandidates(config, backend),
+      configured: configuredKeyFiles(config, backend),
+    });
     return {
       backend,
       model:
@@ -314,8 +360,14 @@ export function resolveBackend(config: JevConfig): ResolvedBackend {
   }
 
   // auto: preferisci backend con chiave disponibile, default openrouter.
-  const openRouterKey = resolveKeyFor("openrouter", keyFile);
-  const typesafeKey = resolveKeyFor("typesafe", keyFile);
+  const openRouterKey = resolveKeyFor("openrouter", {
+    candidates: keyFileCandidates(config, "openrouter"),
+    configured: configuredKeyFiles(config, "openrouter"),
+  });
+  const typesafeKey = resolveKeyFor("typesafe", {
+    candidates: keyFileCandidates(config, "typesafe"),
+    configured: configuredKeyFiles(config, "typesafe"),
+  });
   const hasOpenRouter = Boolean(openRouterKey.key);
   const hasTypesafe = Boolean(typesafeKey.key);