@gonrocca/zero-pi 0.1.29 → 0.1.31

package/README.md

@@ -59,7 +59,7 @@ into `/forge` for you.
 
 | Feature | What it does |
 | ------- | ------------ |
-| **`/zero-models`** | Pick the model + provider for each SDD phase — interactive or direct. |
+| **`/zero-models`** | Pick the model + provider for each SDD phase — a boxed-window picker, or set one directly. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
 | **`/zero-sync`** | Folds each run's spec delta into a canonical, project-wide spec store. |
 | **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |

package/extensions/zero-models-picker.ts

@@ -0,0 +1,488 @@
+// zero-pi — the /zero-models interactive picker, pure-state module.
+//
+// The no-arg path of /zero-models is a single boxed-window TUI. This file holds
+// every *decision* of that picker — menu-entry construction, highlighted-index
+// movement, screen transitions, and the staged-edit accumulator — as pure,
+// dependency-free TypeScript so it is unit-testable with `node --test`. The
+// pi-TUI render+input shell lives in `zero-models.ts` and owns no navigation
+// logic; it holds one `PickerState`, forwards keystrokes here, and re-renders.
+//
+// This file has NO `node:fs` and NO pi imports. It takes injected data
+// (registry groups, current models/providers, pending suggestions) and returns
+// new state. Type-only imports are `import type` so `--experimental-strip-types`
+// erases them with no runtime resolution. Mirrors the `autotune.ts` precedent.
+
+import type { Phase, PhaseModels, PhaseProviders } from "./zero-models.ts";
+import type { AutotuneMode } from "./autotune.ts";
+import type { AutotunePending } from "./autotune-extension.ts";
+
+/** The SDD phases, in pipeline order — re-stated locally so the pure module
+ *  carries no value import. Must stay in lockstep with `PHASES` in
+ *  `zero-models.ts`. */
+const PHASES = ["explore", "plan", "build", "veredicto"] as const;
+
+/** The three autotune modes offered on the autotune screen. */
+const AUTOTUNE_MODES = ["auto", "ask", "off"] as const;
+
+// ---------------------------------------------------------------------------
+// Screen model
+// ---------------------------------------------------------------------------
+
+/** Which sub-screen the picker is currently showing. */
+export type Screen = "main" | "provider" | "model" | "autotune";
+
+/** One selectable row in the current screen. */
+export interface MenuEntry {
+  /** Stable kind discriminator for the transition functions. */
+  kind:
+    | "apply-pending" // ★ aplicar sugerencia      (main, conditional)
+    | "phase" // explore/plan/build/veredicto (main)
+    | "autotune" // autotune → <mode>          (main)
+    | "save" // — guardar y salir —        (main)
+    | "provider" // a concrete provider id     (provider screen)
+    | "custom-provider" // — otro provider (escribir) —
+    | "model" // a concrete model id        (model screen)
+    | "custom-model" // — otro modelo (escribir) —
+    | "autotune-mode"; // auto | ask | off           (autotune screen)
+  /** The text shown for the row (Spanish, voseo). */
+  label: string;
+  /** Payload: phase name, provider id, model id, or autotune mode. */
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Staged edits (the accumulator)
+// ---------------------------------------------------------------------------
+
+/** Edits staged in memory; only written to zero.json on save. */
+export interface StagedEdits {
+  /** From `readModels` — a mutated copy, never the caller's object. */
+  models: PhaseModels;
+  /** From `readProviders` — a mutated copy, parallel to {@link models}. */
+  providers: PhaseProviders;
+  /** The autotune mode, possibly changed from disk. */
+  autotuneMode: AutotuneMode;
+  /** Any phase model/provider changed. */
+  changed: boolean;
+  /** `autotuneMode` differs from disk. */
+  autotuneChanged: boolean;
+  /** A pending suggestion was applied. */
+  pendingApplied: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Picker state (the single value the component holds)
+// ---------------------------------------------------------------------------
+
+/** The full picker state — one mutable value the component holds for its
+ *  lifetime; the transition functions mutate-and-return it. */
+export interface PickerState {
+  /** The sub-screen currently shown. */
+  screen: Screen;
+  /** Highlighted row index, always within `[0, entries.length)`. */
+  cursor: number;
+  /** Menu rows for the current screen — derived, never hand-mutated. */
+  entries: MenuEntry[];
+  /** Staged, unsaved edits. */
+  edits: StagedEdits;
+  /** Pending autotune suggestions still un-applied (drives the apply entry). */
+  pending: AutotunePending[];
+  /** Provider→models registry groups, captured once at open. */
+  groups: Map<string, string[]>;
+  /** Fallback model list when the registry is empty. */
+  fallbackModels: readonly string[];
+  /** Drill-down context: the phase being edited (provider/model screens). */
+  drillPhase: Phase | null;
+  /** Drill-down context: provider chosen so far (model screen). */
+  drillProvider: string | null;
+  /** When non-null, the component shows an inline text input for this. */
+  textPrompt: { for: "provider" | "model"; label: string } | null;
+}
+
+// ---------------------------------------------------------------------------
+// Transition results
+// ---------------------------------------------------------------------------
+
+/** Discriminated outcome of `enter()`/`back()` — lets the component act. */
+export type EnterResult =
+  | { type: "state"; state: PickerState } // stay open, re-render
+  | { type: "save"; state: PickerState } // close, persist edits
+  | { type: "quit" }; // close, write nothing
+
+// ---------------------------------------------------------------------------
+// Initial state
+// ---------------------------------------------------------------------------
+
+/** The escape-row label for typing a custom provider id. */
+const CUSTOM_PROVIDER_LABEL = "— otro provider (escribir) —";
+/** The escape-row label for typing a custom model id. */
+const CUSTOM_MODEL_LABEL = "— otro modelo (escribir) —";
+/** The save-and-exit row label. */
+const SAVE_LABEL = "— guardar y salir —";
+
+/** Render a phase's current `provider/model` (provider omitted when empty). */
+function phaseLabel(
+  phase: Phase,
+  models: PhaseModels,
+  providers: PhaseProviders,
+): string {
+  const provider = providers[phase];
+  const model = provider ? `${provider}/${models[phase]}` : models[phase];
+  return `${phase}   →   ${model}`;
+}
+
+/** Render the `★ aplicar sugerencia` label from the pending adjustments. */
+function applyLabel(pending: readonly AutotunePending[]): string {
+  return `★ aplicar sugerencia: ${pending
+    .map((p) => `${p.phase} → ${p.to}`)
+    .join(", ")}`;
+}
+
+/**
+ * Build the initial main-screen picker state from disk-read inputs.
+ *
+ * The `models`/`providers` maps are copied so staged edits never mutate the
+ * caller's objects. `edits.autotuneMode` snapshots the disk value; the three
+ * change flags start `false`. The result is on `screen: "main"` with `cursor`
+ * at `0` and `entries` already built via `rebuildEntries`.
+ */
+export function createPickerState(input: {
+  models: PhaseModels;
+  providers: PhaseProviders;
+  autotuneMode: AutotuneMode;
+  pending: AutotunePending[];
+  groups: Map<string, string[]>;
+  fallbackModels: readonly string[];
+}): PickerState {
+  const state: PickerState = {
+    screen: "main",
+    cursor: 0,
+    entries: [],
+    edits: {
+      models: { ...input.models },
+      providers: { ...input.providers },
+      autotuneMode: input.autotuneMode,
+      changed: false,
+      autotuneChanged: false,
+      pendingApplied: false,
+    },
+    pending: [...input.pending],
+    groups: input.groups,
+    fallbackModels: input.fallbackModels,
+    drillPhase: null,
+    drillProvider: null,
+    textPrompt: null,
+  };
+  return rebuildEntries(state);
+}
+
+// ---------------------------------------------------------------------------
+// rebuildEntries
+// ---------------------------------------------------------------------------
+
+/** Build the rows for the `main` screen. */
+function mainEntries(state: PickerState): MenuEntry[] {
+  const entries: MenuEntry[] = [];
+
+  // Conditional apply-pending row, prepended when a suggestion is staged.
+  if (state.pending.length > 0) {
+    entries.push({
+      kind: "apply-pending",
+      label: applyLabel(state.pending),
+      value: "apply",
+    });
+  }
+
+  // One row per SDD phase, in pipeline order.
+  for (const phase of PHASES) {
+    entries.push({
+      kind: "phase",
+      label: phaseLabel(phase, state.edits.models, state.edits.providers),
+      value: phase,
+    });
+  }
+
+  // The autotune row, then the save row.
+  entries.push({
+    kind: "autotune",
+    label: `autotune   →   ${state.edits.autotuneMode}`,
+    value: "autotune",
+  });
+  entries.push({ kind: "save", label: SAVE_LABEL, value: "save" });
+
+  return entries;
+}
+
+/** Build the rows for the `provider` screen — sorted provider ids + escape. */
+function providerEntries(state: PickerState): MenuEntry[] {
+  const entries: MenuEntry[] = [];
+  for (const provider of [...state.groups.keys()].sort()) {
+    entries.push({ kind: "provider", label: provider, value: provider });
+  }
+  entries.push({
+    kind: "custom-provider",
+    label: CUSTOM_PROVIDER_LABEL,
+    value: "",
+  });
+  return entries;
+}
+
+/** Build the rows for the `model` screen — models for the drilled provider
+ *  (or `fallbackModels` when the registry is empty) + custom-model escape. */
+function modelEntries(state: PickerState): MenuEntry[] {
+  const models =
+    state.drillProvider !== null
+      ? (state.groups.get(state.drillProvider) ?? state.fallbackModels)
+      : state.fallbackModels;
+  const entries: MenuEntry[] = [];
+  for (const model of models) {
+    entries.push({ kind: "model", label: model, value: model });
+  }
+  entries.push({ kind: "custom-model", label: CUSTOM_MODEL_LABEL, value: "" });
+  return entries;
+}
+
+/** Build the rows for the `autotune` screen — the three modes. */
+function autotuneEntries(): MenuEntry[] {
+  return AUTOTUNE_MODES.map((mode) => ({
+    kind: "autotune-mode" as const,
+    label: mode,
+    value: mode,
+  }));
+}
+
+/**
+ * Recompute `state.entries` for the current screen + drill context.
+ *
+ * Idempotent: calling it twice in a row produces the same rows. After
+ * rebuilding, `cursor` is clamped into `[0, entries.length)` so a transition
+ * that shrinks the row list never leaves the highlight out of bounds. Mutates
+ * and returns the same `PickerState`.
+ */
+export function rebuildEntries(state: PickerState): PickerState {
+  switch (state.screen) {
+    case "main":
+      state.entries = mainEntries(state);
+      break;
+    case "provider":
+      state.entries = providerEntries(state);
+      break;
+    case "model":
+      state.entries = modelEntries(state);
+      break;
+    case "autotune":
+      state.entries = autotuneEntries();
+      break;
+  }
+
+  // Clamp the cursor — a shrunk list must never leave it past the last row.
+  const n = state.entries.length;
+  if (n === 0) {
+    state.cursor = 0;
+  } else if (state.cursor < 0) {
+    state.cursor = 0;
+  } else if (state.cursor >= n) {
+    state.cursor = n - 1;
+  }
+
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// navigate
+// ---------------------------------------------------------------------------
+
+/**
+ * Move the highlighted-row index by `dir` (`-1` up, `+1` down), wrapping
+ * cyclically at both ends: Up at index 0 lands on the last row, Down at the
+ * last row lands on row 0 (resolves Open Question 1). A single-entry list is
+ * a fixed point — any move stays on row 0. An empty list keeps `cursor` at 0.
+ *
+ * Mutates and returns the same `PickerState`; the filesystem is never touched.
+ */
+export function navigate(state: PickerState, dir: -1 | 1): PickerState {
+  const n = state.entries.length;
+  if (n === 0) {
+    state.cursor = 0;
+  } else {
+    state.cursor = (state.cursor + dir + n) % n;
+  }
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// enter / back — Enter/Esc dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Dispatch Enter on the highlighted entry. Returns an {@link EnterResult}:
+ *
+ * - `phase` → drills into provider selection (`screen: "provider"`), or
+ *   straight to `model` with `fallbackModels` when the registry is empty.
+ * - `provider` → records `drillProvider`, drills into model selection.
+ * - `custom-provider` / `custom-model` → opens `textPrompt`, stays on screen.
+ * - `model` → commits the model/provider into `edits` for `drillPhase`,
+ *   marks `edits.changed`, returns to `main`.
+ * - `autotune` → drills into the autotune-mode screen.
+ * - `autotune-mode` → records the mode, marks `autotuneChanged` when it
+ *   differs from the staged value, returns to `main`.
+ * - `apply-pending` → applies every pending `to` into `edits.models`,
+ *   marks `changed` + `pendingApplied`, clears `state.pending`.
+ * - `save` → `{ type: "save" }`.
+ *
+ * Every staying-open path rebuilds `entries`. Filesystem is never touched.
+ */
+export function enter(state: PickerState): EnterResult {
+  const entry = state.entries[state.cursor];
+  if (!entry) return { type: "state", state };
+
+  switch (entry.kind) {
+    case "phase": {
+      state.drillPhase = entry.value as Phase;
+      state.drillProvider = null;
+      // Skip the provider screen entirely when the registry is empty —
+      // jump straight to model selection over `fallbackModels`.
+      state.screen = state.groups.size === 0 ? "model" : "provider";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "provider": {
+      state.drillProvider = entry.value;
+      state.screen = "model";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "custom-provider": {
+      state.textPrompt = { for: "provider", label: entry.label };
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "custom-model": {
+      state.textPrompt = { for: "model", label: entry.label };
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "model": {
+      if (state.drillPhase !== null) {
+        const phase = state.drillPhase;
+        state.edits.models[phase] = entry.value;
+        // `drillProvider` is the provider picked/typed on the provider screen,
+        // or `null` when the empty-registry skip jumped straight here — in
+        // which case there is no provider, so `""`. (The design's middle
+        // `resolveProvider` term is unreachable in the pure module: a null
+        // `drillProvider` only ever co-occurs with an empty `groups`.)
+        state.edits.providers[phase] = state.drillProvider ?? "";
+        state.edits.changed = true;
+      }
+      state.screen = "main";
+      state.drillPhase = null;
+      state.drillProvider = null;
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "autotune": {
+      state.screen = "autotune";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "autotune-mode": {
+      const mode = entry.value as AutotuneMode;
+      if (mode !== state.edits.autotuneMode) {
+        state.edits.autotuneMode = mode;
+        state.edits.autotuneChanged = true;
+      }
+      state.screen = "main";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "apply-pending": {
+      for (const adj of state.pending) {
+        state.edits.models[adj.phase] = adj.to;
+      }
+      state.edits.changed = true;
+      state.edits.pendingApplied = true;
+      state.pending = [];
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "save":
+      return { type: "save", state };
+  }
+}
+
+/**
+ * Dispatch Esc. From a drill screen (`provider`/`model`/`autotune`) it
+ * returns to `main` with the drill context cleared and **no** edit
+ * committed. From `main` it returns `{ type: "quit" }` so the handler
+ * closes the picker without writing `zero.json`.
+ */
+export function back(state: PickerState): EnterResult {
+  if (state.screen === "main") {
+    return { type: "quit" };
+  }
+  state.screen = "main";
+  state.drillPhase = null;
+  state.drillProvider = null;
+  state.textPrompt = null;
+  state.cursor = 0;
+  return { type: "state", state: rebuildEntries(state) };
+}
+
+// ---------------------------------------------------------------------------
+// submitText — commit a typed custom value
+// ---------------------------------------------------------------------------
+
+/**
+ * Commit a typed custom value from the inline text input opened by a
+ * `custom-provider` / `custom-model` escape row.
+ *
+ * - `textPrompt.for === "provider"` → records the trimmed `typed` string as
+ *   `drillProvider` and advances to the `model` screen so a model can be
+ *   picked under the just-typed provider.
+ * - `textPrompt.for === "model"` → commits the trimmed `typed` string as the
+ *   drilled phase's model into `edits.models`, records the provider
+ *   (`drillProvider ?? ""`, matching the model-commit semantics of `enter`)
+ *   into `edits.providers`, sets `edits.changed`, and returns to `main`.
+ * - empty / whitespace `typed` → a no-op: nothing is committed, the screen is
+ *   left unchanged, only `textPrompt` is cleared so the list shows again.
+ *
+ * `textPrompt` is cleared on every path and `rebuildEntries` is always called.
+ * Mutates and returns the same `PickerState`; the filesystem is never touched.
+ */
+export function submitText(state: PickerState, typed: string): PickerState {
+  const prompt = state.textPrompt;
+  const value = typed.trim();
+
+  // Empty / whitespace input, or no prompt open: a no-op. Drop the prompt and
+  // re-show the current list screen unchanged — no edit is committed.
+  if (prompt === null || value === "") {
+    state.textPrompt = null;
+    return rebuildEntries(state);
+  }
+
+  if (prompt.for === "provider") {
+    state.drillProvider = value;
+    state.screen = "model";
+    state.cursor = 0;
+  } else {
+    // prompt.for === "model": commit the typed model into the drilled phase.
+    if (state.drillPhase !== null) {
+      const phase = state.drillPhase;
+      state.edits.models[phase] = value;
+      state.edits.providers[phase] = state.drillProvider ?? "";
+      state.edits.changed = true;
+    }
+    state.screen = "main";
+    state.drillPhase = null;
+    state.drillProvider = null;
+    state.cursor = 0;
+  }
+
+  state.textPrompt = null;
+  return rebuildEntries(state);
+}

package/extensions/zero-models.ts

@@ -19,8 +19,28 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+// `@earendil-works/pi-tui` is provided by the pi runtime as an ambient bare
+// specifier — it is NOT a `package.json` dependency. It is loaded lazily, via
+// a dynamic `import()` inside the no-arg handler branch, NOT a top-level value
+// import: a static `import { Box } from "@earendil-works/pi-tui"` would be
+// evaluated whenever any consumer imports this module — including
+// `zero-models.test.ts`, which imports the deterministic helpers — and would
+// crash `node --test` with `ERR_MODULE_NOT_FOUND`. `import type` below is
+// fully erased by `--experimental-strip-types`, so it never triggers
+// resolution. The runtime classes are reached only from inside pi.
+import type { Component } from "@earendil-works/pi-tui";
+
 import { readAutotuneMode, type AutotuneMode } from "./autotune.ts";
 import type { AutotunePending } from "./autotune-extension.ts";
+import {
+  back,
+  createPickerState,
+  enter,
+  navigate,
+  submitText,
+  type EnterResult,
+  type PickerState,
+} from "./zero-models-picker.ts";
 
 /** The SDD phases, in pipeline order. */
 export const PHASES = ["explore", "plan", "build", "veredicto"] as const;
@@ -181,11 +201,41 @@ export function groupByProvider(models: readonly PiModel[]): Map<string, string[
   return map;
 }
 
+/** The pi-TUI host handed to a `ctx.ui.custom()` factory — only the one
+ *  method the picker shell uses. */
+interface PiTui {
+  requestRender(): void;
+}
+/** A pi-TUI component that groups children vertically and renders a frame. */
+interface PiBox extends Component {
+  addChild(child: Component): void;
+}
+/** The slice of `@earendil-works/pi-tui` the boxed picker constructs at
+ *  runtime — `Box`/`Text`/`Spacer` constructors, captured from the lazy
+ *  dynamic `import()` so this module never statically resolves the specifier. */
+interface PiTuiModule {
+  Box: new (paddingX?: number, paddingY?: number) => PiBox;
+  Text: new (content: string, paddingX?: number, paddingY?: number) => Component;
+  Spacer: new (lines: number) => Component;
+}
+/** A pi theme — only the foreground-color helper the picker uses. */
+interface PiTheme {
+  fg(color: string, text: string): string;
+}
+/** The factory `ctx.ui.custom()` invokes to build the boxed component. */
+type PiCustomFactory<T> = (
+  tui: PiTui,
+  theme: PiTheme,
+  keybindings: unknown,
+  done: (result: T) => void,
+) => Component;
+
 /** The slice of pi's extension API this command uses. */
 interface PiUI {
   select(prompt: string, options: string[]): Promise<string | undefined>;
   input(prompt: string, placeholder?: string): Promise<string | undefined>;
   notify(message: string, type?: "info" | "warning" | "error"): void;
+  custom<T>(factory: PiCustomFactory<T>): Promise<T>;
 }
 /** pi's model registry — the source of every provider's model list. */
 interface PiModelRegistry {
@@ -206,10 +256,6 @@ interface PiExtensionAPI {
   ): void;
 }
 
-const SAVE_AND_EXIT = "— guardar y salir —";
-const CUSTOM_MODEL = "— otro modelo (escribir) —";
-const CUSTOM_PROVIDER = "— otro provider (escribir) —";
-
 /**
  * Group models by provider for the picker.
  *
@@ -249,6 +295,192 @@ function resolveProvider(
   return undefined;
 }
 
+/** The boxed-panel title row. */
+const PICKER_TITLE = "zero · modelos SDD";
+/** The dim help line shown at the foot of the boxed panel. */
+const PICKER_HELP = "↑↓ navegar · enter elegir · esc volver";
+
+/** ANSI arrow-key escape sequences. */
+const KEY_UP = "\x1b[A";
+const KEY_DOWN = "\x1b[B";
+const KEY_ESC = "\x1b";
+/** Enter — CR or LF, depending on the terminal. */
+const KEY_ENTER = new Set(["\r", "\n", "\r\n"]);
+/** Backspace — DEL or BS. */
+const KEY_BACKSPACE = new Set(["\x7f", "\x08"]);
+
+/**
+ * Clamp a rendered line to `width` columns so it never overflows the box
+ * frame (tui.md "Line Width" is a hard rule). A plain slice is enough here —
+ * the picker emits no ANSI inside its row strings except whole-line theming,
+ * and `theme.fg` is applied *after* truncation by the caller where it matters.
+ */
+function clampLine(line: string, width: number): string {
+  if (width <= 0) return "";
+  return line.length > width ? line.slice(0, width) : line;
+}
+
+/**
+ * Build the inline pi-TUI component for the no-arg picker.
+ *
+ * The component owns no navigation logic — it holds one mutable `PickerState`,
+ * forwards keystrokes to the pure transition functions of
+ * `zero-models-picker.ts`, and re-renders. A `save`/`quit` `EnterResult` ends
+ * the component via `done(result)`.
+ *
+ * Custom typed provider/model values use an inline character buffer handled
+ * directly in `handleInput` (the design's documented fallback for the embedded
+ * `Input`): pi-tui's `Input` is not shipped with type definitions in this pi
+ * build and an embedded-input + `Focusable` wiring is the design's named
+ * highest-risk path — the inline buffer is self-contained, needs no ambient
+ * class beyond `Box`/`Text`/`Spacer`, and keeps the pure module's `submitText`
+ * contract untouched.
+ *
+ * The whole `handleInput` body is wrapped in a `try/catch` that closes the
+ * component cleanly via `done({ type: "quit" })` on any error (Req 9).
+ */
+function createPickerComponent(
+  initial: PickerState,
+  pitui: PiTuiModule,
+  theme: PiTheme,
+  tui: PiTui,
+  done: (result: EnterResult) => void,
+): Component {
+  const { Box, Text, Spacer } = pitui;
+  // The single mutable state reference; reassigned from the pure functions.
+  let state = initial;
+  // Inline text buffer — non-null only while `state.textPrompt` is open.
+  let buffer: string | null = null;
+
+  /** Render the boxed panel for the current state. */
+  function render(width: number): string[] {
+    const box = new Box(1, 1);
+    const inner = Math.max(1, width - 4); // account for the box's paddingX
+
+    box.addChild(new Text(clampLine(PICKER_TITLE, inner), 0, 0));
+    box.addChild(new Spacer(1));
+
+    if (state.textPrompt) {
+      // Inline text-entry mode: show the prompt label and the typed buffer.
+      box.addChild(
+        new Text(clampLine(state.textPrompt.label, inner), 0, 0),
+      );
+      const typed = `> ${buffer ?? ""}`;
+      box.addChild(
+        new Text(theme.fg("accent", clampLine(typed, inner)), 0, 0),
+      );
+      box.addChild(new Spacer(1));
+      box.addChild(
+        new Text(
+          theme.fg("dim", clampLine("enter confirmar · esc volver", inner)),
+          0,
+          0,
+        ),
+      );
+      return box.render(width);
+    }
+
+    state.entries.forEach((entry, index) => {
+      if (index === state.cursor) {
+        const row = clampLine(`> ${entry.label}`, inner);
+        box.addChild(new Text(theme.fg("accent", row), 0, 0));
+      } else {
+        const row = clampLine(`  ${entry.label}`, inner);
+        box.addChild(new Text(theme.fg("dim", row), 0, 0));
+      }
+    });
+
+    box.addChild(new Spacer(1));
+    box.addChild(
+      new Text(theme.fg("dim", clampLine(PICKER_HELP, inner)), 0, 0),
+    );
+    return box.render(width);
+  }
+
+  /** Apply an `EnterResult` — re-render on `state`, close on `save`/`quit`. */
+  function applyResult(result: EnterResult): void {
+    if (result.type === "state") {
+      state = result.state;
+      tui.requestRender();
+    } else {
+      done(result);
+    }
+  }
+
+  /** Route a keystroke while the inline text buffer is open. */
+  function handleTextInput(data: string): void {
+    if (data === KEY_ESC) {
+      // Esc abandons the typed value and returns to the current list screen
+      // unchanged. `submitText` with an empty string is exactly that no-op:
+      // it clears `textPrompt` and rebuilds the list without committing.
+      state = submitText(state, "");
+      buffer = null;
+      tui.requestRender();
+      return;
+    }
+    if (KEY_ENTER.has(data)) {
+      state = submitText(state, buffer ?? "");
+      buffer = null;
+      tui.requestRender();
+      return;
+    }
+    if (KEY_BACKSPACE.has(data)) {
+      buffer = (buffer ?? "").slice(0, -1);
+      tui.requestRender();
+      return;
+    }
+    // Append printable characters only (skip control sequences).
+    if (data.length >= 1 && data.charCodeAt(0) >= 32 && !data.startsWith("\x1b")) {
+      buffer = (buffer ?? "") + data;
+      tui.requestRender();
+    }
+  }
+
+  /** Receive a keystroke; never throws out — a failure closes the picker. */
+  function handleInput(data: string): void {
+    try {
+      // Inline text-entry mode takes input until it submits or escapes.
+      if (state.textPrompt) {
+        handleTextInput(data);
+        return;
+      }
+
+      if (data === KEY_UP) {
+        state = navigate(state, -1);
+        tui.requestRender();
+        return;
+      }
+      if (data === KEY_DOWN) {
+        state = navigate(state, 1);
+        tui.requestRender();
+        return;
+      }
+      if (KEY_ENTER.has(data)) {
+        const result = enter(state);
+        // `enter` on a custom-* row opens `textPrompt`; arm the buffer.
+        if (result.type === "state" && result.state.textPrompt) buffer = "";
+        applyResult(result);
+        return;
+      }
+      if (data === KEY_ESC) {
+        applyResult(back(state));
+        return;
+      }
+    } catch {
+      // A render/transition bug must never wedge the pi session — close.
+      done({ type: "quit" });
+    }
+  }
+
+  return {
+    render,
+    invalidate(): void {
+      /* stateless render — nothing cached to clear */
+    },
+    handleInput,
+  };
+}
+
 /**
  * The pi extension entry point — registers the `/zero-models` command.
  */
@@ -315,115 +547,68 @@ export default function register(pi?: PiExtensionAPI): void {
           return;
         }
 
-        // Interactive form: pick a phase, a provider, a model — until saved.
-        let changed = false;
-        let autotuneMode = readAutotuneMode(data);
-        let autotuneChanged = false;
-        let pending = readAutotunePending(data);
-        let pendingApplied = false;
-        for (;;) {
-          const applyEntry =
-            pending.length > 0
-              ? `★ aplicar sugerencia: ${pending
-                  .map((p) => `${p.phase} → ${p.to}`)
-                  .join(", ")}`
-              : null;
-          const autotuneEntry = `autotune   →   ${autotuneMode}`;
-
-          const phasePick = await ctx.ui.select("zero · modelos SDD — elegí una fase", [
-            ...(applyEntry ? [applyEntry] : []),
-            ...PHASES.map(
-              (p) => `${p}   →   ${providers[p] ? `${providers[p]}/` : ""}${models[p]}`,
-            ),
-            autotuneEntry,
-            SAVE_AND_EXIT,
-          ]);
-          if (!phasePick || phasePick === SAVE_AND_EXIT) break;
-
-          // Apply the pending autotune suggestion.
-          if (applyEntry && phasePick === applyEntry) {
-            for (const adj of pending) models[adj.phase] = adj.to;
-            changed = true;
-            pendingApplied = true;
-            pending = [];
-            continue;
-          }
-
-          // Change the autotune mode.
-          if (phasePick === autotuneEntry) {
-            const modePick = await ctx.ui.select(
-              "Modo de autotune",
-              AUTOTUNE_MODES.map((m) => formatAutotune(m)),
-            );
-            if (!modePick) continue;
-            const picked = parseAutotuneArg(modePick.split(/\s/)[0]);
-            if (picked && picked !== autotuneMode) {
-              autotuneMode = picked;
-              autotuneChanged = true;
-            }
-            continue;
-          }
-
-          const phase = phasePick.split(/\s/)[0];
-          if (!isPhase(phase)) break;
-
-          // Pick a provider — from the registry, or typed when unknown.
-          let provider = providers[phase];
-          let modelChoices = FALLBACK_MODELS;
-          if (groups.size > 0) {
-            const providerPick = await ctx.ui.select(`Provider para «${phase}»`, [
-              ...[...groups.keys()].sort(),
-              CUSTOM_PROVIDER,
-            ]);
-            if (!providerPick) continue;
-            if (providerPick === CUSTOM_PROVIDER) {
-              const typed = await ctx.ui.input(
-                `Provider para «${phase}»`,
-                providers[phase] || "",
-              );
-              if (!typed || typed.trim() === "") continue;
-              provider = typed.trim();
-              modelChoices = groups.get(provider) ?? [];
-            } else {
-              provider = providerPick;
-              modelChoices = groups.get(providerPick) ?? [];
-            }
-          }
-
-          // Pick a model within that provider — or type one.
-          const label = provider ? `Modelo para «${phase}» (${provider})` : `Modelo para «${phase}»`;
-          const modelPick = await ctx.ui.select(label, [...modelChoices, CUSTOM_MODEL]);
-          if (!modelPick) continue;
+        // Interactive form: open the boxed picker, then persist on save.
+        const autotuneMode = readAutotuneMode(data);
+        const pending = readAutotunePending(data);
+
+        const initialState = createPickerState({
+          models,
+          providers,
+          autotuneMode,
+          pending,
+          groups,
+          fallbackModels: FALLBACK_MODELS,
+        });
+
+        // Load pi-tui lazily — the bare specifier resolves only inside pi.
+        // This `import()` lives in the handler (already inside the swallowing
+        // `try/catch`), so a resolution failure becomes an error notification
+        // and never escapes (Req 9).
+        const pitui = (await import(
+          "@earendil-works/pi-tui"
+        )) as unknown as PiTuiModule;
+
+        const result = await ctx.ui.custom<EnterResult>((tui, theme, _kb, done) =>
+          createPickerComponent(initialState, pitui, theme, tui, done),
+        );
 
-          let model = modelPick;
-          if (modelPick === CUSTOM_MODEL) {
-            const typed = await ctx.ui.input(label, models[phase]);
-            if (!typed || typed.trim() === "") continue;
-            model = typed.trim();
-          }
-          models[phase] = model;
-          providers[phase] = provider || resolveProvider(ctx.modelRegistry, model) || "";
-          changed = true;
+        if (result.type !== "save") {
+          // Esc / quit (or a contained UI failure): write nothing, leaving
+          // `zero.json` byte-for-byte unchanged, and report the leave-as-is
+          // state — the existing "sin cambios" notification text.
+          ctx.ui.notify(
+            `zero · modelos SDD (sin cambios):\n${formatPhases(models, providers)}\n` +
+              `  autotune   ${autotuneMode}`,
+            "info",
+          );
+          return;
         }
 
-        if (changed || autotuneChanged) {
+        // Save: pull the accumulated edits off the final picker state.
+        const edits = result.state.edits;
+        if (edits.changed || edits.autotuneChanged) {
           // Build the patch, preserving every other key via the spread. When
           // the pending suggestion was applied, clear the `autotunePending` key.
-          const patch: Record<string, unknown> = { models, providers };
-          if (autotuneChanged) patch.autotune = autotuneMode;
+          const patch: Record<string, unknown> = {
+            models: edits.models,
+            providers: edits.providers,
+          };
+          if (edits.autotuneChanged) patch.autotune = edits.autotuneMode;
 
           const merged = { ...data, ...patch };
-          if (pendingApplied) delete merged.autotunePending;
+          if (edits.pendingApplied) delete merged.autotunePending;
           writeFileSync(zeroJsonPath(), `${JSON.stringify(merged, null, 2)}\n`, "utf8");
 
-          const summary = [`zero · modelos SDD guardados:\n${formatPhases(models, providers)}`];
-          summary.push(`  autotune   ${autotuneMode}`);
-          if (pendingApplied) summary.push("sugerencia aplicada");
+          const summary = [
+            `zero · modelos SDD guardados:\n${formatPhases(edits.models, edits.providers)}`,
+          ];
+          summary.push(`  autotune   ${edits.autotuneMode}`);
+          if (edits.pendingApplied) summary.push("sugerencia aplicada");
           ctx.ui.notify(summary.join("\n"), "info");
         } else {
           ctx.ui.notify(
-            `zero · modelos SDD (sin cambios):\n${formatPhases(models, providers)}\n` +
-              `  autotune   ${autotuneMode}`,
+            `zero · modelos SDD (sin cambios):\n${formatPhases(edits.models, edits.providers)}\n` +
+              `  autotune   ${edits.autotuneMode}`,
             "info",
           );
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, per-phase model autotune, and skill auto-learning. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -44,6 +44,7 @@
     "extensions/sdd-agents.ts",
     "extensions/conversation-resume.ts",
     "extensions/zero-models.ts",
+    "extensions/zero-models-picker.ts",
     "extensions/autotune.ts",
     "extensions/autotune-extension.ts",
     "extensions/spec-merge.ts",