diff --git a/docs/superpowers/specs/2026-07-04-dual-mode-gate-evaluation.md b/docs/superpowers/specs/2026-07-04-dual-mode-gate-evaluation.md index 3411bf38..7c224fb8 100644 --- a/docs/superpowers/specs/2026-07-04-dual-mode-gate-evaluation.md +++ b/docs/superpowers/specs/2026-07-04-dual-mode-gate-evaluation.md @@ -4,8 +4,9 @@ Date: 2026-07-04 Status: valutazione (nessuna implementazione — solo analisi di fattibilità) Pi runtime di riferimento: `@earendil-works/pi-coding-agent` **0.80.3** — versione live sul PATH dal 2026-07-04 (migrazione dal vecchio scope `@mariozechner`, congelato a 0.73.1; -validata via `model-matrix` con GLM 5.2, scenari `new`+`resume` entrambi CHAINED). Tutte le -citazioni `types.d.ts` sotto sono relative a **questa** versione. +validata via `model-matrix` con GLM 5.2, scenari `new`+`resume` entrambi CHAINED, e uno smoke +full-stack con gate F1 risposto). Tutte le citazioni `types.d.ts` sotto sono relative a +**questa** versione. ## Context @@ -19,8 +20,10 @@ In RPC il backend fa da bridge (`extension_ui_request` method `input` → SSE) e frontend React rende i descrittori come widget veri. In interattivo, invece, `ctx.ui.input` mostra il **JSON grezzo** come prompt e pretende una risposta `UiResponse` in JSON digitata a mano → non usabile. Il design ha volutamente -sostituito i widget TUI nativi con l'emissione descriptor -(commento in testa a [tht-gate.js:227](../../../harness/.pi/extensions/tht-gate.js)). +sostituito i widget TUI nativi con l'emissione descriptor — banner REWRITE punto (2), +[tht-gate.js:8-10](../../../harness/.pi/extensions/tht-gate.js): *"the reviewer interaction is +emitted as a widget-descriptor JSON … instead of rendered by blocking native TUI primitives +(ctx.ui.select/custom)"*. ## Verdetto: SÌ, è pensabile ed è architetturalmente supportato @@ -29,12 +32,14 @@ sfruttata: - **`ctx.mode: ExtensionMode`** (types.d.ts:207,212) — `"tui" | "rpc" | "json" | "print"`, con commento dei tipi: *"Use 'tui' to guard terminal-only UI such as custom components"*. - È **il** discriminatore corretto per il ramo interattivo: guardare `ctx.mode === "tui"`, - perché con 4 modi `!ctx.hasUI` confonderebbe `rpc`/`json`/`print` in un solo ramo. -- **`ctx.hasUI: boolean`** (types.d.ts:214) — "Whether UI is available (false in print/RPC - mode)"; resta disponibile e **il gate lo usa già** - ([tht-gate.js:319,397](../../../harness/.pi/extensions/tht-gate.js)). Valido come fallback, - ma `ctx.mode === "tui"` è più preciso ora che i modi sono quattro. + È **il** discriminatore corretto per il ramo interattivo: guardare `ctx.mode === "tui"`. +- **`ctx.hasUI: boolean`** (types.d.ts:213) — commento reale: *"Whether dialog-capable UI is + available (**true in TUI and RPC modes**)"*. ⚠️ È `true` **sia** in TUI **sia** in RPC: + quindi **non** distingue interattivo da RPC e **non** è un fallback valido per il ramo TUI — + solo `ctx.mode === "tui"` lo fa. (Nota migrazione: il gate usa oggi `if (ctx.hasUI)` a + [tht-gate.js:319,397](../../../harness/.pi/extensions/tht-gate.js) con la vecchia semantica + 0.73.1, dove `hasUI` era `false` in RPC. Su 0.80.3 quelle due guardie scattano **anche** in + RPC → vedi *Note implementative*.) - **`ExtensionUIContext`** (types.d.ts:63-67) — "Each mode (interactive, RPC, print) provides its own implementation". Espone nativamente: `select(title, options: string[], opts?) → Promise` (69), @@ -42,7 +47,7 @@ sfruttata: `input(title, placeholder?, opts?) → Promise` (73), `notify(message, type?)` (75), `editor(title, prefill?) → Promise` (134), e `custom(factory) → Promise` (116, componente TUI a pieno controllo). - `info`/`notify` funzionano già in entrambe le modalità. + `notify` funziona già in entrambe le modalità. ## `UiResponse` è un tipo INTERNO ThothII (non un export di Pi) @@ -67,7 +72,7 @@ descriptor. Va documentato esplicitamente (JSDoc typedef nel modulo del gate): L'eleganza sta nel fatto che a valle tutto consuma un `UiResponse`, classificato da `resolveSelectOutcome` / `resolveConfirmOutcome` / `selectedChoice`, con l'invariante id-match in `emitAndWait` ([tht-gate.js:312](../../../harness/.pi/extensions/tht-gate.js): -`resp.id === descriptor.id && resp.control !== "cancel"`). Quindi: +`if (resp && resp.control !== "cancel" && resp.id === descriptor.id)`). Quindi: - **Invariati**: `gate/builders.js` (costruzione descrittori) e i classificatori di esito. Sono il contratto condiviso tra le due modalità. @@ -80,17 +85,25 @@ id-match in `emitAndWait` ([tht-gate.js:312](../../../harness/.pi/extensions/tht primitive native e **sintetizza** un `UiResponse` con lo stesso `id` e la stessa forma, così i classificatori a valle non cambiano di una riga. -I 3 gate bloccanti + freetext + info sono una superficie limitata. La colonna -**no-limbo** dice cosa sintetizzare quando la primitiva nativa ritorna `undefined` -(Esc / cancel / timeout / `signal`), perché senza risposta il turno resterebbe appeso: +I **3 gate bloccanti** che passano da `emitAndWait` sono l'intera superficie da rendere: +`select` ([tht-gate.js:492](../../../harness/.pi/extensions/tht-gate.js)), `multiselect` (576), +`artifact-gate` (639). La colonna **no-limbo** dice cosa sintetizzare quando la primitiva +nativa ritorna `undefined` (Esc / cancel / timeout / `signal`): | widget | render interattivo | no-limbo (nativo → `undefined`) | UiResponse sintetizzato | |---|---|---|---| | `select` | `ctx.ui.select(title, [...labels, "Go back", "Exit", "Other — specify"])`; "Other"→`ctx.ui.input` | re-present una volta; se ancora `undefined` → `{control:"exit"}` | `{id, choices:[optId]}` o `{control:"back"/"exit"/"freetext", text}` | | `multiselect` | `ctx.ui.custom` (checkbox list); fallback low-cost: `input` con indici separati da virgola | re-present una volta; poi `{control:"exit"}` | `{id, choices:[TUTTI gli id scelti]}` — vedi nota reviewer_decide sotto | | `artifact-gate` | artefatto via `ctx.ui.editor(title, testo)` (multi-linea, meglio di `notify`) + `ctx.ui.confirm`/`select` approve/reject/other | re-present (advance solo su approve/reject **esplicito**, mai implicito) | `{id, choices:["approve"/"reject"]}` o control | -| `freetext` | `ctx.ui.input(title)` | re-present una volta; poi `{control:"exit"}` | `{id, text}` | -| `info` | già `ctx.ui.notify` — **verificato usato** (builders.js:127 → [tht-gate.js:569](../../../harness/.pi/extensions/tht-gate.js), avviso F2 memoria vuota) | n/a (fire-and-forget, nessun `id`) | — | + +**Non sono widget-descriptor** (nessuna riga `present()` dedicata): +- **`freetext`** non è un widget a sé: è il `control:"freetext"` restituito dall'opzione + «Altro/Other» di `select`/`artifact-gate` → nel ramo TUI si raccoglie con `ctx.ui.input` + dentro il render di quei due. +- **`info`** non passa da `present()`: sono `ctx.ui.notify(..., "info")` scritti a mano + (es. [tht-gate.js:567](../../../harness/.pi/extensions/tht-gate.js), avviso F2 memoria vuota), + già mode-agnostic. `buildInfoRequest` **esiste** in `builders.js` ma **non è cablato** nel + gate (l'import a tht-gate.js:29-31 porta solo select/multiselect/artifact-gate) — builder morto. ## Vincoli del runtime Pi verificati (0.80.3) @@ -137,6 +150,23 @@ gli si dà un renderer, invece di derivare silenziosamente dal percorso RPC. L1-testabile in isolamento come `builders.js`. - Nessun cambiamento a `builders.js`, ai classificatori, al backend o al frontend. +## Note implementative (checklist prima di scrivere present()) + +- **Il commento a [tht-gate.js:227](../../../harness/.pi/extensions/tht-gate.js)** dice + *"usa l'API UI NATIVA di Pi (ctx.ui.input)"*. Quando `emitAndWait` viene incapsulato in + `present()` con un ramo che usa i **widget TUI nativi** (non `ctx.ui.input`), quel commento + diventa fuorviante → va riscritto insieme al codice. +- **`ctx.ui.notify` da razionalizzare.** 6 notify nel gate; solo 319 e 397 sono guardate da + `ctx.hasUI`, le altre 4 sono **non guardate** (567, 651, 824, 831). Oggi in RPC sono + fire-and-forget verso il frontend; in TUI diventerebbero warning a terminale. Decidere + per-notify se appartiene a entrambe le modalità — in particolare la **651** è dentro il loop + di re-present del confirm gate. +- **Guardie `ctx.hasUI` da rivedere (regresso di migrazione).** 319/397 erano "solo TUI" con + la semantica 0.73.1 (`hasUI=false` in RPC). Su 0.80.3 `hasUI=true` anche in RPC, quindi ora + scattano in RPC (es. riga 321 *"Esc non chiude il gate…"*, priva di senso nel browser). + L'intento va espresso con `ctx.mode === "tui"`. **Indipendente dal dual-mode**, ma da + sistemare comunque. + ## Test (il vero guardrail contro la deriva) - **Property test round-trip** (non solo "descriptor→UiResponse"): per **ogni** @@ -172,6 +202,7 @@ gli si dà un renderer, invece di derivare silenziosamente dal percorso RPC. Fattibile e pulito: la doppia gestione si ottiene con **una sola cucitura mode-aware** (`present`) attorno a `emitAndWait`, sfruttando che Pi è già mode-aware via `ctx.mode` -(`=== "tui"` per il ramo interattivo) e che a valle tutto consuma un `UiResponse` -interno. Il costo dipende dal livello di fedeltà interattiva voluto (C minimo, A -curato); il guardrail è il property test round-trip. Nessun impatto su RPC/frontend. +(`=== "tui"` per il ramo interattivo; **non** `hasUI`, che su 0.80.3 è `true` anche in RPC) +e che a valle tutto consuma un `UiResponse` interno. Il costo dipende dal livello di fedeltà +interattiva voluto (C minimo, A curato); il guardrail è il property test round-trip. Nessun +impatto su RPC/frontend.