@gtrabanco/pi-agentic-workflow 0.9.1 → 0.9.2

package/README.es.md

@@ -164,7 +164,11 @@ byte a byte idéntico; el campo de modelo puede construir una cadena de respaldo
 ordenada (`a/m1 → b/m2`); y una sola pasada puede aplicar o limpiar una ruta en
 varios comandos, avisando por comando cuando una referencia falta del registro
 vivo. Fuera de una sesión TUI los selectores caen a un prompt simple, así que la
-consola nunca se queda sin salida.
+consola nunca se queda sin salida. Las listas de más de 24 opciones tampoco
+llegan nunca a un solo diálogo: por encima del tope el selector de modelo
+pregunta primero el proveedor, y una lista de proveedores o de modelos
+demasiado larga pagina (`More options…` / `◀ Previous page`) en vez de tumbar
+el diálogo de select del host.
 
 ## Diagnóstico
 

package/README.md

@@ -158,7 +158,11 @@ you are, and the value currently in force is pre-selected and labelled
 model field can build an ordered fallback chain (`a/m1 → b/m2`); and one pass
 can apply or clear a route across several commands, warning per command when a
 reference is missing from the live registry. Outside a TUI session the pickers
-fall back to a plain prompt, so the console never dead-ends.
+fall back to a plain prompt, so the console never dead-ends. Lists longer than
+24 options never reach a single dialog either: over the cap the model picker
+asks for the provider first, and an overlong provider or model list pages
+(`More options…` / `◀ Previous page`) instead of crashing the host's select
+dialog.
 
 ## Troubleshooting
 

package/dist/extension/index.d.ts

@@ -1,4 +1,13 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SettingsUi } from "../routing/types.js";
 import { SETTINGS_COMMAND } from "../routing/types.js";
+/**
+ * The interactive slice the settings console sees: Pi's own `ui` plus the rich
+ * picker (P4). The picker is terminal-only, so a non-TUI mode (headless/RPC)
+ * gets the plain `select` path — the console never dead-ends (OB-12, PE-004).
+ * Exported as a test seam: the fallback's bounded paging (AC8) is exercised
+ * directly, without standing up the whole extension.
+ */
+export declare function richUi(ctx: ExtensionContext): SettingsUi;
 export default function extension(pi: ExtensionAPI): void;
 export { SETTINGS_COMMAND };

package/dist/extension/index.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "../config/load.js";
 import { createExtension } from "./factory.js";
-import { createPickerComponent, PICKER_MAX_VISIBLE } from "../settings/picker.js";
+import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
 import { createHintStore, stateFilePath } from "../routing/state.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
@@ -25,8 +25,10 @@ const thinkingLevelsInSyncWithPi = true;
  * The interactive slice the settings console sees: Pi's own `ui` plus the rich
  * picker (P4). The picker is terminal-only, so a non-TUI mode (headless/RPC)
  * gets the plain `select` path — the console never dead-ends (OB-12, PE-004).
+ * Exported as a test seam: the fallback's bounded paging (AC8) is exercised
+ * directly, without standing up the whole extension.
  */
-function richUi(ctx) {
+export function richUi(ctx) {
     const base = ctx.ui;
     return {
         select: (title, options) => base.select(title, [...options]),
@@ -35,7 +37,10 @@ function richUi(ctx) {
         notify: (message, kind) => base.notify(message, kind),
         pick: async (title, options, opts = {}) => {
             if (ctx.mode !== "tui") {
-                const picked = await base.select(title, [...options]);
+                // Non-TUI: the host's `select` dialog carries the same 24-option cap, so
+                // an over-cap list pages instead of crashing `pick` (AC8, PE-002). A
+                // list within the cap is one call with the same options, in order.
+                const picked = await pagedSelect((selectTitle, selectOptions) => base.select(selectTitle, [...selectOptions]), title, [...options]);
                 if (opts.multiple)
                     return picked ? [picked] : undefined;
                 return picked;
@@ -53,6 +58,7 @@ function richUi(ctx) {
                     items,
                     maxVisible: PICKER_MAX_VISIBLE,
                     theme: selectListTheme,
+                    initial: opts.initial,
                     onSelect: (value) => done(value),
                     onCancel: () => done(undefined),
                 });

package/dist/settings/console.d.ts

@@ -55,6 +55,7 @@ export declare const prompts: {
     readonly cancel: "Cancel";
     readonly model: (target: string) => string;
     readonly modelPicked: (target: string) => string;
+    readonly modelProvider: (target: string) => string;
     readonly thinking: (target: string) => string;
     readonly fields: "Which fields should change?";
     readonly fieldsBoth: "model and thinking";

package/dist/settings/console.js

@@ -12,6 +12,7 @@ import { effectiveRoute } from "../config/merge.js";
 import { parseConfigFile, parseModelReference } from "../config/schema.js";
 import { MAX_MODEL_CHAIN, SETTLE_POLICIES, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "../config/types.js";
 import { renderMergedConfig, routePath, DEFAULT_ROUTE } from "./view.js";
+import { SELECT_OPTION_LIMIT, pagedSelect, providerOf } from "./picker.js";
 /** The console's questions. `test/settings-console.test.mjs` drives the flow
  * through these strings, so renaming one fails the tests that use it rather than
  * silently re-sequencing them. */
@@ -38,6 +39,7 @@ export const prompts = {
     cancel: "Cancel",
     model: (target) => `Model for ${target}?`,
     modelPicked: (target) => `Which model for ${target}?`,
+    modelProvider: (target) => `Provider for ${target}?`,
     thinking: (target) => `Thinking level for ${target}?`,
     fields: "Which fields should change?",
     fieldsBoth: "model and thinking",
@@ -225,18 +227,25 @@ async function askFields(deps) {
 }
 /** Ask for one model entry; `undefined` means cancelled/skipped, `"inherit"` means the whole-route setting. */
 async function pickModelEntry(deps, target, current) {
+    const models = deps.models ?? [];
     let answer;
-    if (typeof deps.ui.pick === "function" && deps.models && deps.models.length > 0) {
+    if (models.length > SELECT_OPTION_LIMIT - 1) {
+        // Over the cap: TYPED occupies one dialog slot, so 24 models + TYPED would
+        // still crash (Decision 1). The issue's provider-first two-step keeps every
+        // dialog bounded in every UI mode (Decision 3).
+        answer = await askModelOverCap(deps, target, models, current);
+    }
+    else if (typeof deps.ui.pick === "function" && models.length > 0) {
         // Rich seam: filterable, windowed, preselected to the value in force (OB-1).
-        const picked = await deps.ui.pick(prompts.modelPicked(target), [...deps.models, TYPED], {
+        const picked = await deps.ui.pick(prompts.modelPicked(target), [...models, TYPED], {
             initial: typeof current === "string" ? current : undefined,
         });
         answer = typeof picked === "string" ? picked : undefined;
         if (answer === TYPED || answer === undefined)
             answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
     }
-    else if (deps.models && deps.models.length > 0) {
-        answer = await deps.ui.select(prompts.modelPicked(target), [...deps.models, TYPED]);
+    else if (models.length > 0) {
+        answer = await deps.ui.select(prompts.modelPicked(target), [...models, TYPED]);
         if (answer === TYPED || answer === undefined)
             answer = await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
     }
@@ -257,6 +266,60 @@ async function pickModelEntry(deps, target, current) {
     }
     return `${parts.provider}/${parts.id}`;
 }
+/**
+ * The provider-first two-step the issue prescribes when the live registry exceeds
+ * the single-dialog cap (PE-003, PE-014). Unique providers (prefix before the
+ * first `/`, `localeCompare`-sorted) come first — through the rich picker while
+ * it fits, `pagedSelect` otherwise — then that provider's models in registry
+ * order. "Type another reference…" is the trailing entry of every dialog and
+ * still reaches the text input, so a pick-less UI completes the flow (OB-12).
+ */
+async function askModelOverCap(deps, target, models, current) {
+    const currentProvider = typeof current === "string" ? providerOf(current) : undefined;
+    const providers = [...new Set(models.map((model) => providerOf(model)))].sort((a, b) => a.localeCompare(b));
+    const provider = await askProvider(deps, target, providers, currentProvider);
+    if (provider === TYPED || provider === undefined) {
+        return await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
+    }
+    const providerModels = models.filter((model) => providerOf(model) === provider);
+    const picked = await askModelWithinProvider(deps, target, providerModels, provider, current);
+    if (picked === TYPED || picked === undefined) {
+        return await deps.ui.input(prompts.model(target), "provider/modelId or inherit");
+    }
+    return picked;
+}
+/**
+ * Ask which provider. The rich picker handles it while `providers + TYPED` fits
+ * the cap (preselected to the value in force's provider); over the cap — Pi
+ * imposes no provider ceiling, so a > 24-provider registry is real (PE-014) —
+ * the dialog pages instead of crashing.
+ */
+async function askProvider(deps, target, providers, currentProvider) {
+    const title = prompts.modelProvider(target);
+    if (typeof deps.ui.pick === "function" && providers.length + 1 <= SELECT_OPTION_LIMIT) {
+        const picked = await deps.ui.pick(title, [...providers, TYPED], {
+            ...(currentProvider !== undefined ? { initial: currentProvider } : {}),
+        });
+        return typeof picked === "string" ? picked : undefined;
+    }
+    return pagedSelect((selectTitle, options) => deps.ui.select(selectTitle, options), title, providers, { trailing: TYPED });
+}
+/**
+ * Ask the model within one provider. The rich picker handles it while `models +
+ * TYPED` fits the cap (preselected only when the value in force belongs to this
+ * provider); over the cap the dialog pages.
+ */
+async function askModelWithinProvider(deps, target, models, provider, current) {
+    const title = prompts.modelPicked(target);
+    if (typeof deps.ui.pick === "function" && models.length + 1 <= SELECT_OPTION_LIMIT) {
+        const initial = typeof current === "string" && providerOf(current) === provider ? current : undefined;
+        const picked = await deps.ui.pick(title, [...models, TYPED], {
+            ...(initial !== undefined ? { initial } : {}),
+        });
+        return typeof picked === "string" ? picked : undefined;
+    }
+    return pagedSelect((selectTitle, options) => deps.ui.select(selectTitle, options), title, models, { trailing: TYPED });
+}
 /** Ask for a model; a lone reference is returned as-is, several references are returned as an ordered chain. */
 async function askModel(deps, target, current) {
     // The value in force (OB-3). For a route whose model is already a chain, seed
@@ -334,7 +397,8 @@ async function pickCommand(deps, options) {
         deps.ui.notify("There is no command to pick here.", "warning");
         return undefined;
     }
-    return deps.ui.select(prompts.command, [...options].sort((a, b) => a.localeCompare(b)));
+    const sorted = [...options].sort((a, b) => a.localeCompare(b));
+    return pagedSelect((title, list) => deps.ui.select(title, list), prompts.command, sorted);
 }
 /** Multi-select command picker over the seam's `multiple` mode; a non-rich UI falls back to repeated single selects. */
 async function pickCommandsMulti(deps, options) {
@@ -355,7 +419,7 @@ async function pickCommandsMulti(deps, options) {
         const remaining = sorted.filter((option) => !chosen.includes(option));
         if (remaining.length === 0)
             break;
-        const picked = await deps.ui.select(prompts.command, remaining);
+        const picked = await pagedSelect((title, list) => deps.ui.select(title, list), prompts.command, remaining);
         if (picked === undefined)
             break;
         chosen.push(picked);

package/dist/settings/picker.d.ts

@@ -1,6 +1,51 @@
 import { type Component, type SelectItem, type SelectListTheme } from "@earendil-works/pi-tui";
 /** Default window height for the SelectList (the built-in position indicator scales to the list). */
 export declare const PICKER_MAX_VISIBLE = 10;
+/**
+ * The host dialog cap this package must never exceed (PE-001): pi-web rejects a
+ * `select` dialog offering more than 24 options with "A select dialog must not
+ * offer more than 24 options". It is the single knob if a future host enforces a
+ * different bound.
+ */
+export declare const SELECT_OPTION_LIMIT = 24;
+/** Pager entry offered on every page but the first. */
+export declare const PAGED_SELECT_PREV = "\u25C0 Previous page";
+/** Pager entry offered on every page but the last. */
+export declare const PAGED_SELECT_NEXT = "More options\u2026";
+/** The plain-dialog shape `pagedSelect` drives (Pi's `ctx.ui.select`). */
+export type SelectFn = (title: string, options: readonly string[]) => string | undefined | Promise<string | undefined>;
+/**
+ * Present `options` through `select` without ever offering more than
+ * `SELECT_OPTION_LIMIT` entries in one dialog (AC6, PE-001, PE-012).
+ *
+ * - A list that fits — data plus `trailing` — opens exactly one dialog, in the
+ *   caller's order with `trailing` last, so a ≤ cap flow is byte-identical to a
+ *   plain `select` call.
+ * - A longer list pages `PAGED_SELECT_PAGE_SIZE` data entries at a time —
+ *   `SELECT_OPTION_LIMIT - 3`, so the derived page never hardcodes the cap —
+ *   appending `PAGED_SELECT_PREV` and/or `PAGED_SELECT_NEXT` before `trailing`.
+ *   Pager entries navigate; `trailing` and data entries are returned to the
+ *   caller; `undefined` (cancel) passes straight through.
+ *
+ * The two pager labels are reserved: a data value (or a `trailing` value) that
+ * spells one is indistinguishable from the pager entry in the string `select`
+ * answers with, so a colliding pager label is decorated until it names nothing
+ * else on the dialog — the data value stays selectable and so does the pager.
+ */
+export declare function pagedSelect(select: SelectFn, title: string, options: readonly string[], { trailing }?: {
+    trailing?: string;
+}): Promise<string | undefined>;
+/**
+ * The provider prefix Pi resolves a reference by — everything before the first
+ * `/` (SPEC Decision 6).
+ *
+ * Lenient on purpose, and deliberately distinct from the strict
+ * `parseModelReference` in `../config/schema.js`, which validates and rejects:
+ * this split must answer for any registry string. Both the console's
+ * provider-first grouping and the slash-aware filter below take their provider
+ * from here, so the two settings-side consumers cannot drift apart.
+ */
+export declare function providerOf(reference: string): string;
 /**
  * Token/subsequence, slash-aware reference filter (OB-2).
  *
@@ -19,11 +64,16 @@ export declare function filterReferences(query: string, refs: readonly string[])
  * `filterReferences` as the operator types so the subsequence/slash-aware
  * filter (OB-2) — not `SelectList`'s own prefix `setFilter` — drives what the
  * window shows. Control keys (arrows, Enter, Escape) forward to the list.
+ *
+ * `initial` — the value in force — is selected in the window the picker opens
+ * with, through the SelectList's own `setSelectedIndex` (OB-3).
  */
 export declare function createPickerComponent(options: {
     items: readonly SelectItem[];
     maxVisible: number;
     theme: SelectListTheme;
+    /** The value in force, selected in the window the picker opens with (OB-3). */
+    initial?: string;
     onSelect: (value: string) => void;
     onCancel?: () => void;
 }): Component & {

package/dist/settings/picker.js

@@ -10,6 +10,10 @@
 //    to narrow the list, selection, and cancel. The Pi-free `SettingsUi.pick`
 //    seam stays separated so the filter and the component are exercisable
 //    without a live session.
+//  - `pagedSelect` is the plain-`select` counterpart: the host's dialog cap
+//    (pi-web rejects > 24 options, PE-001) is never a picker concern — a UI
+//    without the rich seam still gets a bounded dialog, and an over-cap list
+//    pages instead of crashing.
 //
 // The filter is implemented in this package (not imported from Pi): PE-004
 // confirmed pi-coding-agent's `fuzzyFilter` is internal, so the same
@@ -17,6 +21,99 @@
 import { SelectList } from "@earendil-works/pi-tui";
 /** Default window height for the SelectList (the built-in position indicator scales to the list). */
 export const PICKER_MAX_VISIBLE = 10;
+/**
+ * The host dialog cap this package must never exceed (PE-001): pi-web rejects a
+ * `select` dialog offering more than 24 options with "A select dialog must not
+ * offer more than 24 options". It is the single knob if a future host enforces a
+ * different bound.
+ */
+export const SELECT_OPTION_LIMIT = 24;
+/** Pager entry offered on every page but the first. */
+export const PAGED_SELECT_PREV = "◀ Previous page";
+/** Pager entry offered on every page but the last. */
+export const PAGED_SELECT_NEXT = "More options…";
+/**
+ * Data entries per page: `SELECT_OPTION_LIMIT - 3` — room inside one dialog for
+ * both pager entries and the caller's trailing option.
+ */
+const PAGED_SELECT_PAGE_SIZE = SELECT_OPTION_LIMIT - 3;
+/**
+ * The pager label actually offered: `base`, decorated with `marker` while some
+ * value in the dialog spells it, so a label-colliding data entry can never be
+ * swallowed by the navigation guard (see the contract above).
+ */
+function pagerLabel(base, marker, spoken) {
+    let label = base;
+    while (spoken.includes(label))
+        label += marker;
+    return label;
+}
+/**
+ * Present `options` through `select` without ever offering more than
+ * `SELECT_OPTION_LIMIT` entries in one dialog (AC6, PE-001, PE-012).
+ *
+ * - A list that fits — data plus `trailing` — opens exactly one dialog, in the
+ *   caller's order with `trailing` last, so a ≤ cap flow is byte-identical to a
+ *   plain `select` call.
+ * - A longer list pages `PAGED_SELECT_PAGE_SIZE` data entries at a time —
+ *   `SELECT_OPTION_LIMIT - 3`, so the derived page never hardcodes the cap —
+ *   appending `PAGED_SELECT_PREV` and/or `PAGED_SELECT_NEXT` before `trailing`.
+ *   Pager entries navigate; `trailing` and data entries are returned to the
+ *   caller; `undefined` (cancel) passes straight through.
+ *
+ * The two pager labels are reserved: a data value (or a `trailing` value) that
+ * spells one is indistinguishable from the pager entry in the string `select`
+ * answers with, so a colliding pager label is decorated until it names nothing
+ * else on the dialog — the data value stays selectable and so does the pager.
+ */
+export async function pagedSelect(select, title, options, { trailing } = {}) {
+    const items = [...options];
+    if (items.length + (trailing !== undefined ? 1 : 0) <= SELECT_OPTION_LIMIT) {
+        return await select(title, trailing !== undefined ? [...items, trailing] : items);
+    }
+    // A label-colliding data value must stay reachable, so compute the offered
+    // pager labels once against every string that can appear in a dialog.
+    const spoken = trailing !== undefined ? [...items, trailing] : items;
+    const prevLabel = pagerLabel(PAGED_SELECT_PREV, " ‹", spoken);
+    const nextLabel = pagerLabel(PAGED_SELECT_NEXT, " ›", spoken);
+    const pageCount = Math.ceil(items.length / PAGED_SELECT_PAGE_SIZE);
+    let page = 0;
+    for (;;) {
+        const start = page * PAGED_SELECT_PAGE_SIZE;
+        const entries = [
+            ...items.slice(start, start + PAGED_SELECT_PAGE_SIZE),
+            ...(page > 0 ? [prevLabel] : []),
+            ...(page < pageCount - 1 ? [nextLabel] : []),
+            ...(trailing !== undefined ? [trailing] : []),
+        ];
+        const answer = await select(title, entries);
+        if (answer === undefined)
+            return undefined;
+        if (answer === nextLabel && page < pageCount - 1) {
+            page += 1;
+            continue;
+        }
+        if (answer === prevLabel && page > 0) {
+            page -= 1;
+            continue;
+        }
+        return answer;
+    }
+}
+/**
+ * The provider prefix Pi resolves a reference by — everything before the first
+ * `/` (SPEC Decision 6).
+ *
+ * Lenient on purpose, and deliberately distinct from the strict
+ * `parseModelReference` in `../config/schema.js`, which validates and rejects:
+ * this split must answer for any registry string. Both the console's
+ * provider-first grouping and the slash-aware filter below take their provider
+ * from here, so the two settings-side consumers cannot drift apart.
+ */
+export function providerOf(reference) {
+    const slash = reference.indexOf("/");
+    return slash === -1 ? reference : reference.slice(0, slash);
+}
 /**
  * Token/subsequence, slash-aware reference filter (OB-2).
  *
@@ -41,7 +138,7 @@ function matchesToken(token, ref) {
         const provider = token.slice(0, -1);
         if (provider === "")
             return true;
-        const refProvider = ref.split("/")[0] ?? "";
+        const refProvider = providerOf(ref);
         return refProvider.startsWith(provider);
     }
     return isSubsequence(token, ref);
@@ -60,14 +157,27 @@ function isSubsequence(needle, haystack) {
  * `filterReferences` as the operator types so the subsequence/slash-aware
  * filter (OB-2) — not `SelectList`'s own prefix `setFilter` — drives what the
  * window shows. Control keys (arrows, Enter, Escape) forward to the list.
+ *
+ * `initial` — the value in force — is selected in the window the picker opens
+ * with, through the SelectList's own `setSelectedIndex` (OB-3).
  */
 export function createPickerComponent(options) {
-    const { items, maxVisible, theme, onSelect, onCancel } = options;
+    const { items, maxVisible, theme, initial, onSelect, onCancel } = options;
     let filterText = "";
+    let openSelectionApplied = false;
     const byValue = new Map(items.map((item) => [item.value, item]));
     const buildList = () => {
         const visible = filterReferences(filterText, items.map((item) => item.value)).map((value) => byValue.get(value) ?? { value, label: value });
         const list = new SelectList(visible, maxVisible, theme);
+        // Preselection is an open-time concern (OB-3): the value in force applies to
+        // the first window only, so narrowing afterwards keeps the narrowed window's
+        // own first match instead of yanking the selection to a filtered-out value.
+        if (!openSelectionApplied) {
+            openSelectionApplied = true;
+            const index = initial === undefined ? -1 : visible.findIndex((item) => item.value === initial);
+            if (index > 0)
+                list.setSelectedIndex(index); // index 0 is already the SelectList default
+        }
         list.onSelect = (item) => onSelect(item.value);
         list.onCancel = onCancel;
         return list;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",