@gtrabanco/pi-agentic-workflow 0.7.1 → 0.8.0

package/README.es.md

@@ -74,7 +74,7 @@ Dos archivos JSON, ambos opcionales:
 {
   "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
   "commands": {
-    "plan-feature": { "model": "anthropic/claude-sonnet-4-5", "thinking": "medium" },
+    "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
     "review-change": { "thinking": "max" }
   },
   "onUnavailableRoute": "stop"
@@ -87,8 +87,14 @@ de arriba usa el modelo del default con thinking `max`; todo lo demás corre con
 que ya tuviera la sesión, porque la ruta por defecto del paquete es
 `{"model": "inherit", "thinking": "inherit"}`.
 
-- `model` debe ser `provider/modelId` — la referencia exacta que muestra
-  `/model` — o `"inherit"`.
+- `model` puede ser `provider/modelId` — la referencia exacta que muestra
+  `/model` — `"inherit"`, o un **array** ordenado de 1–4 referencias (una cadena
+  de respaldo). Para una cadena, el dispatch prueba cada referencia en orden y
+  aplica la primera que se resuelve y tiene credenciales, sin tocar la sesión
+  mientras prueba; cuando todas las entradas son inservibles el comando se
+  detiene (o, con `onUnavailableRoute` en `inherit`, avisa y corre con el modelo
+  actual), nombrando cada candidato y por qué se saltó. `plan-feature` de arriba
+  prueba `anthropic/claude-sonnet-4-5` primero y luego `openai/gpt-5.2`.
 - `thinking` es uno de `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
   o `"inherit"`.
 - Claves desconocidas, `null` y referencias mal formadas se **rechazan**, no se
@@ -125,11 +131,24 @@ vuelve.
 /agentic-workflow-settings
 ```
 
+`/aw-settings` es un atajo para la misma consola.
+
 Muestra en qué corre cada comando ahora mismo, y qué archivo se niega a parsearse,
 y luego deja editar **un archivo a la vez** y guardar en alcance global o de
 proyecto. No guarda encima de un archivo que no sabe leer, y no toca el
 archivo de proyecto mientras el proyecto no sea de confianza.
 
+Los selectores de modelo y thinking de la consola son buscables y con ventana:
+escribir estrecha la lista, el cursor se queda en pantalla, un indicador de
+posición muestra dónde estás y el valor en vigor viene preseleccionado y
+etiquetado `(current)` / `(default route)`. Una edición de ruta pregunta qué
+campo cambiar (model, thinking), así que guardar sin cambios deja el archivo
+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.
+
 ## Diagnóstico
 
 | Ves | Significa |

package/README.md

@@ -72,7 +72,7 @@ Two JSON files, both optional:
 {
   "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
   "commands": {
-    "plan-feature": { "model": "anthropic/claude-sonnet-4-5", "thinking": "medium" },
+    "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
     "review-change": { "thinking": "max" }
   },
   "onUnavailableRoute": "stop"
@@ -85,8 +85,14 @@ above runs on the default model with `max` thinking; anything else runs on
 whatever the session already had, because the shipped default route is
 `{"model": "inherit", "thinking": "inherit"}`.
 
-- `model` must be `provider/modelId` — the exact reference `/model` shows — or
-  `"inherit"`.
+- `model` can be `provider/modelId` — the exact reference `/model` shows —
+  `"inherit"`, or an ordered **array** of 1–4 references (a fallback chain). For
+  a chain, dispatch probes each reference in order and applies the first one that
+  resolves and has credentials, without touching the session while probing; when
+  every entry is unusable the command stops (or, with `onUnavailableRoute`
+  `inherit`, warns and runs on the current model), naming each candidate and why
+  it was skipped. `plan-feature` above tries `anthropic/claude-sonnet-4-5` first,
+  then `openai/gpt-5.2`.
 - `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
   or `"inherit"`.
 - Unknown keys, `null`s and malformed references are **rejected**, not ignored: a
@@ -120,10 +126,22 @@ thinking level and you keep it while the model still comes back.
 /agentic-workflow-settings
 ```
 
+`/aw-settings` is a shorthand for the same console.
+
 Shows what each command runs on right now, and which file is refusing to parse,
 then lets you edit **one file at a time** and save to global or project scope. It will not save over a file it cannot parse, and it will not
 touch the project file while the project is untrusted.
 
+The console's model and thinking pickers are searchable and windowed: typing
+narrows the list, the cursor stays on screen, a position indicator shows where
+you are, and the value currently in force is pre-selected and labelled
+`(current)` / `(default route)`. A route edit asks which field to change
+(model, thinking), so a no-change save leaves the file byte-identical; the
+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.
+
 ## Troubleshooting
 
 | You see | Means |

package/dist/config/schema.js

@@ -1,4 +1,4 @@
-import { THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
+import { MAX_MODEL_CHAIN, THINKING_LEVELS, UNAVAILABLE_ROUTE_POLICIES } from "./types.js";
 /**
  * Strict validator for one config file (SPEC S5-S8, D-E5).
  *
@@ -52,6 +52,37 @@ function checkRoute(value, path, issues) {
             continue;
         }
         if (key === "model") {
+            if (Array.isArray(entry)) {
+                // A chain must be non-empty, hold only references, and stay within the cap.
+                if (entry.length === 0) {
+                    issues.push({
+                        path: `${path}.model`,
+                        message: `must be "inherit", "provider/modelId", or a non-empty chain of references, got an empty array`,
+                    });
+                    continue;
+                }
+                if (entry.length > MAX_MODEL_CHAIN) {
+                    issues.push({
+                        path: `${path}.model`,
+                        message: `chain holds ${entry.length} entries; ${MAX_MODEL_CHAIN} is the maximum`,
+                    });
+                    continue;
+                }
+                let chainValid = true;
+                for (let index = 0; index < entry.length; index += 1) {
+                    if (!isModelReference(entry[index])) {
+                        issues.push({
+                            path: `${path}.model`,
+                            message: `chain entry ${index + 1} (${describe(entry[index])}) must be "provider/modelId"`,
+                        });
+                        chainValid = false;
+                        break;
+                    }
+                }
+                if (chainValid)
+                    route.model = entry;
+                continue;
+            }
             if (entry !== "inherit" && !isModelReference(entry)) {
                 issues.push({
                     path: `${path}.model`,

package/dist/config/types.d.ts

@@ -14,7 +14,16 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 export type ThinkingSetting = ThinkingLevel | "inherit";
 /** `"inherit"` or an exact `provider/modelId` reference (split at the first slash). */
 export type ModelRef = `${string}/${string}`;
-export type ModelSetting = "inherit" | ModelRef;
+/** An ordered fallback chain of references; the first resolvable + configured entry wins (issue #154, root cause E). */
+export type ModelChain = readonly ModelRef[];
+/**
+ * `"inherit"`, one reference, or an ordered fallback chain of 1–4 references.
+ * A chain is probed by order, and the first entry that resolves AND has
+ * configured auth is applied (OB-6, OB-8, OB-9).
+ */
+export type ModelSetting = "inherit" | ModelRef | ModelChain;
+/** Cap on chain length (issue deliberation: 8 was "almost certainly a mistake"; 4 keeps the view readable). */
+export declare const MAX_MODEL_CHAIN = 4;
 export interface Route {
     model: ModelSetting;
     thinking: ThinkingSetting;

package/dist/config/types.js

@@ -9,4 +9,6 @@
  */
 /** Pi's thinking levels, mirrored here so the domain layer stays Pi-free. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** Cap on chain length (issue deliberation: 8 was "almost certainly a mistake"; 4 keeps the view readable). */
+export const MAX_MODEL_CHAIN = 4;
 export const UNAVAILABLE_ROUTE_POLICIES = ["stop", "inherit"];

package/dist/extension/factory.js

@@ -1,7 +1,7 @@
 import { loadConfig } from "../config/load.js";
 import { readCatalogue } from "../routing/catalogue.js";
 import { createRouter } from "../routing/dispatch.js";
-import { SETTINGS_COMMAND } from "../routing/types.js";
+import { SETTINGS_COMMAND, SETTINGS_COMMAND_ALIAS } from "../routing/types.js";
 export function createExtension(deps) {
     const { registrar, surface, skillsDir, agentDir, hint, settings } = deps;
     const catalogue = readCatalogue(skillsDir);
@@ -18,7 +18,11 @@ export function createExtension(deps) {
             ctx.notify(`pi-agentic-workflow: skills/${issue.dir}: ${issue.message}`, "warning");
         }
     };
-    const knownCommands = new Set([...catalogue.commands.map((entry) => entry.name), SETTINGS_COMMAND]);
+    const knownCommands = new Set([
+        ...catalogue.commands.map((entry) => entry.name),
+        SETTINGS_COMMAND,
+        SETTINGS_COMMAND_ALIAS,
+    ]);
     const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands });
     for (const command of catalogue.commands) {
         registrar.registerCommand(command.name, {
@@ -29,21 +33,28 @@ export function createExtension(deps) {
             },
         });
     }
+    // One handler for both names — `/aw-settings` is a pointer to the same console
+    // and the same two config files, never a separate route surface (OB-5, AC6).
+    const settingsHandler = async (_args, ctx) => {
+        reportCatalogueIssues(ctx);
+        // Bound for the console: two verbs and the session they act on, so it cannot
+        // reach for `settle` or `dispatch` by accident.
+        const routing = { inFlight: () => router.inFlight(), undoInFlight: () => router.undoInFlight(ctx) };
+        try {
+            await settings({ catalogue, ctx, routing });
+        }
+        catch (error) {
+            // A console that dies mid-question must say so, not take the session down.
+            ctx.notify(`Settings could not be opened: ${error.message}`, "error");
+        }
+    };
     registrar.registerCommand(SETTINGS_COMMAND, {
         description: "Show and configure per-command model routing",
-        handler: async (_args, ctx) => {
-            reportCatalogueIssues(ctx);
-            // Bound for the console: two verbs and the session they act on, so it cannot
-            // reach for `settle` or `dispatch` by accident.
-            const routing = { inFlight: () => router.inFlight(), undoInFlight: () => router.undoInFlight(ctx) };
-            try {
-                await settings({ catalogue, ctx, routing });
-            }
-            catch (error) {
-                // A console that dies mid-question must say so, not take the session down.
-                ctx.notify(`Settings could not be opened: ${error.message}`, "error");
-            }
-        },
+        handler: settingsHandler,
+    });
+    registrar.registerCommand(SETTINGS_COMMAND_ALIAS, {
+        description: "Show and configure per-command model routing",
+        handler: settingsHandler,
     });
     return { router, catalogue };
 }

package/dist/extension/index.js

@@ -3,6 +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 { createHintStore, stateFilePath } from "../routing/state.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
@@ -20,6 +21,48 @@ import { SETTINGS_COMMAND } from "../routing/types.js";
  */
 const skillsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
 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).
+ */
+function richUi(ctx) {
+    const base = ctx.ui;
+    return {
+        select: (title, options) => base.select(title, [...options]),
+        input: (title, placeholder) => base.input(title, placeholder),
+        confirm: (title, message) => base.confirm(title, message),
+        notify: (message, kind) => base.notify(message, kind),
+        pick: async (title, options, opts = {}) => {
+            if (ctx.mode !== "tui") {
+                const picked = await base.select(title, [...options]);
+                if (opts.multiple)
+                    return picked ? [picked] : undefined;
+                return picked;
+            }
+            const items = options.map((value) => ({ value, label: value }));
+            const result = await base.custom((_tui, theme, _keybindings, done) => {
+                const selectListTheme = {
+                    selectedPrefix: (text) => theme.bold(`› ${text}`),
+                    selectedText: (text) => theme.inverse(text),
+                    description: (text) => `  ${text}`,
+                    scrollInfo: (text) => theme.bold(text),
+                    noMatch: (text) => theme.italic(text),
+                };
+                return createPickerComponent({
+                    items,
+                    maxVisible: PICKER_MAX_VISIBLE,
+                    theme: selectListTheme,
+                    onSelect: (value) => done(value),
+                    onCancel: () => done(undefined),
+                });
+            }, { overlay: true });
+            if (opts.multiple)
+                return result === undefined ? undefined : [result];
+            return result;
+        },
+    };
+}
 function toInvocationContext(ctx) {
     return {
         cwd: ctx.cwd,
@@ -29,7 +72,7 @@ function toInvocationContext(ctx) {
         isIdle: () => ctx.isIdle(),
         isProjectTrusted: () => ctx.isProjectTrusted(),
         notify: (message, kind) => ctx.ui.notify(message, kind),
-        ui: ctx.ui,
+        ui: richUi(ctx),
         availableModels: () => ctx.modelRegistry.getAll(),
         find: (provider, modelId) => ctx.modelRegistry.find(provider, modelId),
         hasConfiguredAuth: (model) => ctx.modelRegistry.hasConfiguredAuth(model),

package/dist/routing/dispatch.js

@@ -111,7 +111,13 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
             const session = surface(ctx);
             const route = effectiveRoute(loaded.config, command.name);
             let target;
-            if (route.model !== "inherit") {
+            /** The reference string behind `target`, for the select-failure message (a chain names the chosen entry). */
+            let chosenRef;
+            if (route.model === "inherit") {
+                // inherit: no probe — run on the session model (OB-9).
+            }
+            else if (typeof route.model === "string") {
+                // Single reference: behaviour and message shape unchanged (OB-9).
                 const reference = parseModelReference(route.model);
                 const found = reference ? ctx.find(reference.provider, reference.id) : undefined;
                 const blocker = !found
@@ -127,6 +133,36 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 }
                 else {
                     target = found;
+                    chosenRef = route.model;
+                }
+            }
+            else {
+                // Chain: probe entries in order with only ctx.find + hasConfiguredAuth
+                // (no session mutation), collecting one skip reason per entry, and apply
+                // the first usable one (OB-8, OB-9, OB-10).
+                const reasons = [];
+                for (const reference of route.model) {
+                    const parsed = parseModelReference(reference);
+                    const found = parsed ? ctx.find(parsed.provider, parsed.id) : undefined;
+                    if (!found) {
+                        reasons.push(`${reference} is not in the model registry`);
+                        continue;
+                    }
+                    if (!ctx.hasConfiguredAuth(found)) {
+                        reasons.push(`${reference} has no configured credentials`);
+                        continue;
+                    }
+                    target = found;
+                    chosenRef = reference;
+                    break;
+                }
+                if (!target) {
+                    const tried = route.model.join(", ");
+                    const detail = reasons.join("; ");
+                    if (loaded.config.onUnavailableRoute !== "inherit") {
+                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: the configured model chain ${tried} is unavailable (${detail}). ${configureHint}`);
+                    }
+                    ctx.notify(`/${command.name}: the configured model chain ${tried} is unavailable (${detail}), so it runs on the current session model. ${configureHint}`, "warning");
                 }
             }
             const snapshot = { model: ctx.model, thinking: session.getThinkingLevel() };
@@ -135,9 +171,9 @@ export function createRouter({ surface, loadConfig, hint, settingsCommand, known
                 const selected = await session.setModel(target);
                 if (!selected) {
                     if (loaded.config.onUnavailableRoute !== "inherit") {
-                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: ${route.model} could not be selected. ${configureHint}`);
+                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: ${chosenRef} could not be selected. ${configureHint}`);
                     }
-                    ctx.notify(`/${command.name}: ${route.model} could not be selected, so it runs on the current session model. ${configureHint}`, "warning");
+                    ctx.notify(`/${command.name}: ${chosenRef} could not be selected, so it runs on the current session model. ${configureHint}`, "warning");
                 }
                 else {
                     applied.model = target;

package/dist/routing/types.d.ts

@@ -39,12 +39,25 @@ export interface ExtensionSurface<M extends ModelRef = ModelRef> {
     getThinkingLevel(): ThinkingLevel;
     setThinkingLevel(level: ThinkingLevel): void;
 }
+/** Options for the optional rich picker (OB-1, OB-3, P4/P6). */
+export interface PickerOptions {
+    /** The value already in force, preselected when the picker opens (OB-3). */
+    initial?: string;
+    /** Allow selecting several entries (bulk apply/clear, P6). */
+    multiple?: boolean;
+}
 /** The interactive slice of `ctx.ui` the settings console uses (AC10). */
 export interface SettingsUi {
     select(title: string, options: readonly string[]): Promise<string | undefined> | string | undefined;
     input(title: string, placeholder?: string): Promise<string | undefined> | string | undefined;
     confirm(title: string, message: string): Promise<boolean> | boolean;
     notify(message: string, kind?: "info" | "warning" | "error"): void;
+    /**
+     * Optional rich picker: filterable, windowed, with a position indicator and a
+     * preselected current value. A structural superset — a caller without it
+     * falls back to `select`/`input`. Returns `readonly string[]` when `multiple`.
+     */
+    pick?(title: string, options: readonly string[], opts?: PickerOptions): Promise<string | readonly string[] | undefined> | string | readonly string[] | undefined;
 }
 /**
  * Everything a command handler needs from the invocation, reduced to what we
@@ -78,6 +91,8 @@ export type DispatchOutcome = {
 };
 /** Slash name of the settings console (SPEC S4, AC3, AC10). */
 export declare const SETTINGS_COMMAND = "agentic-workflow-settings";
+/** Shorthand alias for the same console — a pointer to the same handler, never a separate route (OB-5, AC6). */
+export declare const SETTINGS_COMMAND_ALIAS = "aw-settings";
 /**
  * The router, as the settings console needs it: two verbs, already bound to the
  * session they act on. Declared once because both the console's deps and the

package/dist/routing/types.js

@@ -1,3 +1,5 @@
 export const modelRefKey = (model) => `${model.provider}/${model.id}`;
 /** Slash name of the settings console (SPEC S4, AC3, AC10). */
 export const SETTINGS_COMMAND = "agentic-workflow-settings";
+/** Shorthand alias for the same console — a pointer to the same handler, never a separate route (OB-5, AC6). */
+export const SETTINGS_COMMAND_ALIAS = "aw-settings";

package/dist/settings/console.d.ts

@@ -45,11 +45,22 @@ export declare const prompts: {
     readonly setDefaultRoute: "Set the default route";
     readonly setOverride: "Set a command override";
     readonly clearOverride: "Clear a command override";
+    readonly bulkApply: "Apply one route to several commands";
+    readonly bulkClear: "Clear several overrides";
+    readonly addAnother: "Add another?";
     readonly policy: "Set the unavailable-route policy";
     readonly save: "Save";
     readonly cancel: "Cancel";
     readonly model: (target: string) => string;
     readonly modelPicked: (target: string) => string;
     readonly thinking: (target: string) => string;
+    readonly fields: "Which fields should change?";
+    readonly fieldsBoth: "model and thinking";
+    readonly fieldsModel: "model only";
+    readonly fieldsThinking: "thinking only";
+    readonly chainAction: (target: string) => string;
+    readonly chainAppend: "Add a fallback";
+    readonly chainRemoveLast: "Remove the last";
+    readonly chainDone: "Done";
 };
 export declare function runSettingsConsole(deps: SettingsDeps): Promise<ConsoleOutcome>;