pi-switchback 0.0.0-stage → 2026.10.14

package/src/dialogue-ui.ts

@@ -0,0 +1,201 @@
+/**
+ * The primitives layer of the `/switchback-config` dialogue.
+ *
+ * Everything here is shared by both halves of the dialogue - the shell
+ * (`src/dialogue.ts`) and the decision-model wizard
+ * (`src/dialogue-classifier.ts`) - and none of it belongs to either:
+ *
+ *  - the session (the loaded layer plus the secret store) and the structural
+ *    UI types,
+ *  - the primitives every screen needs: a screen title naming the file being
+ *    edited, a validated read of that layer, a save that either succeeds or
+ *    reverts exactly the failed action, and a model lookup,
+ *  - every prompt (required, name-last, optional) in one place, so the wording
+ *    of "a value is required" or "empty clears, Esc keeps" is defined once,
+ *  - the two pure formatters that render a classifier for a menu
+ *    (`describeJev`) or name its secret entry (`secretNameFor`).
+ *
+ * It is a module of its own so the two halves can both depend on it without
+ * importing each other.
+ *
+ * See `src/dialogue.ts` for the design of the dialogue as a whole.
+ */
+
+import { loadLayer, readLayerConfig, saveLayer, type LoadedLayer } from "switchback-core/config-editor.ts";
+import type { ClassifierProviderOption } from "switchback-core/classifier-catalog.ts";
+import type { ProbeResult } from "switchback-core/classifier-probe.ts";
+import type { SecretStore } from "./secrets.ts";
+import type { JevConfig, JevRef, SwitchbackConfig, SwitchbackFileConfig } from "switchback-core/types.ts";
+
+/** The dialog surface the dialogue needs (a subset of pi's `ctx.ui`). */
+export interface DialogueUi {
+	notify(message: string, type?: "info" | "warning" | "error"): void;
+	select(title: string, options: string[]): Promise<string | undefined>;
+	confirm(title: string, message: string): Promise<boolean>;
+	input(title: string, placeholder?: string): Promise<string | undefined>;
+}
+
+/** The command context the dialogue runs in (structurally satisfied by pi's context). */
+export interface DialogueContext {
+	hasUI: boolean;
+	ui: DialogueUi;
+	/**
+	 * Optional searchable model picker (TUI contexts supply it). When present,
+	 * "Add fallback..." opens a fuzzy-searchable catalog list instead of asking for
+	 * `provider/id` from memory; when absent the dialogue falls back to the prompt.
+	 */
+	pickModel?: (title: string, current: readonly string[]) => Promise<string | undefined>;
+	/**
+	 * Classifier endpoints pi knows about, for the decision-model wizard's provider
+	 * choice and base-URL defaults (see `packages/core/src/classifier-catalog.ts`). Empty or
+	 * absent falls back to free-text prompts.
+	 */
+	classifierProviders?: readonly ClassifierProviderOption[];
+	/**
+	 * Send the one-shot capability prompt (choice + score + noul) to a configured
+	 * decision model. Supplied by the command handler, which has the model registry
+	 * and switchback's transport; absent means the test is not offered.
+	 */
+	probeClassifier?: (jev: JevConfig) => Promise<ProbeResult>;
+}
+
+export interface DialogueSession {
+	loaded: LoadedLayer;
+	secrets: SecretStore;
+}
+/** Describe a model's classifier for menus: reference, inline, or none. */
+export function describeJev(jev: JevRef | undefined): string {
+	if (jev === undefined) return "(none - report and cycle)";
+	if ("decisionModel" in jev) return `decision model "${jev.decisionModel}"`;
+	const direct = jev.baseUrl !== undefined ? ` (direct: ${jev.baseUrl})` : "";
+	return `${jev.provider}/${jev.id}${direct}`;
+}
+export function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function screenTitle(loaded: LoadedLayer, body: string): string {
+	const fresh = loaded.existed ? "" : " (new file)";
+	return `[${loaded.layer} layer: ${loaded.path}${fresh}]\n${body}`;
+}
+/**
+ * The validated config snapshot for menus; a file that fails the loader's
+ * rules is reported (with the fix hint) and ends the dialogue - the editor
+ * only round-trips config the loader itself accepts.
+ */
+export function readConfigOrReport(ctx: DialogueContext, loaded: LoadedLayer): SwitchbackFileConfig | undefined {
+	try {
+		return readLayerConfig(loaded);
+	} catch (error) {
+		ctx.ui.notify(
+			`${errorMessage(error)}\nThe editor only opens valid config; fix switchback.yaml by hand and retry.`,
+			"error",
+		);
+		return undefined;
+	}
+}
+
+/**
+ * Save and report success; on a ConfigError, report the loader's message and
+ * reload the layer from disk so exactly the failed action is reverted (the
+ * file on disk always holds the last good config). Returns true when saved.
+ */
+export async function saveOrRevert(ctx: DialogueContext, session: DialogueSession): Promise<boolean> {
+	try {
+		saveLayer(session.loaded);
+		return true;
+	} catch (error) {
+		ctx.ui.notify(
+			`${screenTitle(session.loaded, "not saved")}\n${errorMessage(error)}\nThe change was reverted - the file on disk is unchanged.`,
+			"error",
+		);
+		try {
+			session.loaded = loadLayer(session.loaded.layer);
+		} catch (reloadError) {
+			ctx.ui.notify(`cannot reload layer after failed save: ${errorMessage(reloadError)}`, "error");
+		}
+		return false;
+	}
+}
+
+/**
+ * The validated config snapshot, or undefined when the layer has no content
+ * yet (fresh file) - callers treat undefined as "nothing to clash with"; the
+ * save gate still validates everything that ends up in the file.
+ */
+export function tryReadConfig(loaded: LoadedLayer): SwitchbackFileConfig | undefined {
+	try {
+		return readLayerConfig(loaded);
+	} catch {
+		return undefined;
+	}
+}
+/** Required single-line input: Esc aborts the step, empty input re-prompts. */
+export async function promptRequired(
+	ctx: DialogueContext,
+	title: string,
+	placeholder: string,
+): Promise<string | undefined> {
+	for (;;) {
+		const value = await ctx.ui.input(title, placeholder);
+		if (value === undefined) return undefined;
+		const trimmed = value.trim();
+		if (trimmed.length > 0) return trimmed;
+		ctx.ui.notify("a value is required (Esc leaves the step)", "warning");
+	}
+}
+/**
+ * Name-last step of the decision-model wizard: the input arrives prefilled with
+ * a derived default, empty input keeps the default, Esc aborts. A name already
+ * in use is rejected with a warning and the prompt loops.
+ */
+export async function promptNameLast(
+	ctx: DialogueContext,
+	loaded: LoadedLayer,
+	suggestedName: string,
+	knownNames: readonly string[],
+): Promise<string | undefined> {
+	for (;;) {
+		const value = await ctx.ui.input(
+			screenTitle(loaded, `new decision model - name (Enter keeps "${suggestedName}")`),
+			suggestedName,
+		);
+		if (value === undefined) return undefined;
+		const trimmed = value.trim();
+		const name = trimmed.length === 0 ? suggestedName : trimmed;
+		if (knownNames.includes(name)) {
+			ctx.ui.notify(`a decision model named "${name}" already exists`, "warning");
+			continue;
+		}
+		return name;
+	}
+}
+
+/** Optional single-line input: Esc = keep (undefined), empty = clear (null), text = set. */
+export async function promptOptional(
+	ctx: DialogueContext,
+	title: string,
+	current: string | undefined,
+): Promise<string | null | undefined> {
+	const shown = current !== undefined && current.length > 0 ? ` (current: ${current})` : " (not set)";
+	const value = await ctx.ui.input(`${title}${shown} - empty clears, Esc keeps`, "value");
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? null : trimmed;
+}
+export function findModel(config: SwitchbackFileConfig, id: string): SwitchbackConfig | undefined {
+	return config.models.find((m) => m.id === id);
+}
+/**
+ * Secret names are an internal detail of the encrypted store, so the dialogue
+ * derives one instead of asking: `ollama-key`, `local-jev-key`, and so on. A
+ * second key for the same entry simply replaces the stored value under that name.
+ */
+export function secretNameFor(hint: string): string {
+	const cleaned = hint
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/gu, "-")
+		.replace(/^-+|-+$/gu, "");
+	return `${cleaned.length === 0 ? "classifier" : cleaned}-key`;
+}

package/src/dialogue.ts

@@ -0,0 +1,425 @@
+/**
+ * Interactive `/switchback-config` dialogue: an edit loop over one
+ * switchback.yaml layer, built on pi's built-in dialogs (`ctx.ui.select`,
+ * `confirm`, `input`, `notify`).
+ *
+ * This module is the shell: it picks the layer, owns the main menu, the
+ * per-model menu and the fallback editor, and hands the classifier work to
+ * `src/dialogue-classifier.ts`. Session state, the screen primitives and
+ * every prompt live in `src/dialogue-ui.ts`.
+ *
+ * Design: every mutation goes through `packages/core/src/config-editor.ts` and is saved
+ * immediately (`saveLayer`). The file on disk therefore always holds the
+ * last good config, which makes failure handling trivial: when a save
+ * throws the loader's own ConfigError, the dialogue reports it and reloads
+ * the layer from disk - exactly the failed action is reverted, nothing else.
+ * No undo bookkeeping, and the document in memory never drifts from a valid
+ * state for longer than one action.
+ *
+ * The dialogue is deliberately thin: it owns prompt/confirm flow and error
+ * reporting only. All rules live in the loader (single validator), all file
+ * mutation lives in the editor, all secret material lives in the encrypted
+ * store - a literal API key is unrepresentable here because the editor only
+ * accepts a secret NAME and the value goes straight into the store.
+ *
+ * UI surface: structural types (`DialogueContext`) instead of pi's command
+ * context type. The real command context is assignable to the structural
+ * shape, tests can mock it without a TUI, and this module keeps a bare
+ * import surface (install-safe: no host-package imports at all).
+ *
+ * Screen titles always carry the file path being edited, so it is always
+ * obvious which layer - project or global - a change lands in.
+ */
+
+import {
+	addFallback,
+	addVirtualModel,
+	defaultLayer,
+	globalConfigPath,
+	layerExists,
+	loadLayer,
+	moveFallback,
+	projectConfigPath,
+	readLayerConfig,
+	removeFallback,
+	removeVirtualModel,
+	renameVirtualModel,
+	setDebug,
+	setVirtualModelName,
+	type ConfigLayer,
+	type LoadedLayer,
+} from "switchback-core/config-editor.ts";
+import { createSecretStore, type SecretStore } from "./secrets.ts";
+import {
+	describeJev,
+	errorMessage,
+	findModel,
+	promptRequired,
+	readConfigOrReport,
+	saveOrRevert,
+	screenTitle,
+	type DialogueContext,
+	type DialogueSession,
+} from "./dialogue-ui.ts";
+import { decisionModelPicker, decisionModelsMenu } from "./dialogue-classifier.ts";
+import type { SwitchbackConfig, SwitchbackFileConfig } from "switchback-core/types.ts";
+
+/**
+ * Label for one layer in the chooser: which file, and what is in it right now.
+ * Paths live in the screen title, so a label stays stable and scriptable.
+ */
+export function layerOptionLabel(layer: ConfigLayer): string {
+	const name = layer === "global" ? "Global" : "Project";
+	return `${name} - ${describeLayerState(layer)}`;
+}
+
+/** "not present", "N model(s)" or "unreadable (invalid config)" for a layer. */
+function describeLayerState(layer: ConfigLayer): string {
+	if (!layerExists(layer)) return "not present";
+	try {
+		const models = readLayerConfig(loadLayer(layer)).models.length;
+		return `${models} model${models === 1 ? "" : "s"}`;
+	} catch {
+		return "unreadable (invalid config)";
+	}
+}
+
+/**
+ * Ask which layer to edit.
+ *
+ * This is the dialogue's first prompt, and the target of "Switch layer...",
+ * because the layer changes what every later action means: project entries
+ * override global entries with the same model id, so writing to the wrong file
+ * either shadows the other config or fails to. The chooser shows both files,
+ * what each currently holds, and which one is being edited; the preferred layer
+ * is offered first (Enter keeps it). Esc cancels the dialogue.
+ */
+async function selectLayer(ctx: DialogueContext, current: ConfigLayer | undefined): Promise<ConfigLayer | undefined> {
+	const preferred = current ?? defaultLayer();
+	const labels: Record<ConfigLayer, string> = {
+		global: layerOptionLabel("global"),
+		project: layerOptionLabel("project"),
+	};
+	const order: ConfigLayer[] = preferred === "global" ? ["global", "project"] : ["project", "global"];
+	const title = [
+		current === undefined ? "which config layer do you want to edit?" : `switch layer (currently: ${current})`,
+		`  global:  ${globalConfigPath()}`,
+		`  project: ${projectConfigPath()}`,
+		"Project entries override global entries with the same model id.",
+	].join("\n");
+	const choice = await ctx.ui.select(
+		title,
+		order.map((layer) => labels[layer]),
+	);
+	if (choice === undefined) return undefined;
+	return choice === labels["global"] ? "global" : "project";
+}
+
+/**
+ * Run the dialogue. Returns when the user is done; every completed action has
+ * already been saved to the layer file by then.
+ */
+export async function runDialogue(ctx: DialogueContext, store?: SecretStore): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify("/switchback-config needs a UI-capable context (TUI or RPC)", "warning");
+		return;
+	}
+	const secrets = store ?? createSecretStore();
+	const chosen = await selectLayer(ctx, undefined);
+	if (chosen === undefined) return;
+	let layer: ConfigLayer = chosen;
+	for (;;) {
+		const loaded = openLayer(ctx, layer);
+		if (loaded === undefined) return;
+		const session: DialogueSession = { loaded, secrets };
+		const outcome = await mainMenu(ctx, session);
+		if (outcome === "done") return;
+		const next = await selectLayer(ctx, loaded.layer);
+		if (next === undefined) return;
+		layer = next;
+	}
+}
+
+/** Load a layer for editing; a read or YAML failure is reported and ends the dialogue. */
+function openLayer(ctx: DialogueContext, layer: ConfigLayer): LoadedLayer | undefined {
+	try {
+		return loadLayer(layer);
+	} catch (error) {
+		ctx.ui.notify(`cannot open ${layer} layer: ${errorMessage(error)}`, "error");
+		return undefined;
+	}
+}
+
+/**
+ * Ask for one physical model. With a TUI picker available the catalog is
+ * searchable (the `/model` experience); otherwise the user types `provider/id`.
+ */
+async function chooseFallback(
+	ctx: DialogueContext,
+	session: DialogueSession,
+	title: string,
+	current: readonly string[],
+): Promise<string | undefined> {
+	if (ctx.pickModel !== undefined) return ctx.pickModel(title, current);
+	return promptRequired(ctx, title, "provider/id");
+}
+
+type MainOutcome = "done" | "switch";
+
+async function mainMenu(ctx: DialogueContext, session: DialogueSession): Promise<MainOutcome> {
+	for (;;) {
+		// A layer with no content yet (first save) has no valid config to read;
+		// offer the reduced menu until the first virtual model exists.
+		if (session.loaded.doc.contents === undefined || session.loaded.doc.contents === null) {
+			const choice = await ctx.ui.select(screenTitle(session.loaded, "no config in this layer yet"), [
+				"Add virtual model...",
+				"Switch layer...",
+				"Done",
+			]);
+			if (choice === undefined || choice === "Done") return "done";
+			if (choice.startsWith("Switch layer")) return "switch";
+			await addVirtualModelWizard(ctx, session);
+			continue;
+		}
+		const config = readConfigOrReport(ctx, session.loaded);
+		if (config === undefined) return "done";
+		const options: string[] = config.models.map((m) => `${m.id} - ${m.name}`);
+		const addOption = "Add virtual model...";
+		const debugOption = `Toggle debug (currently ${config.debug === true ? "on" : "off"})`;
+		const dmOption = `Decision models (${config.decisionModels?.length ?? 0})...`;
+		const switchOption = "Switch layer...";
+		const doneOption = "Done";
+		options.push(addOption, debugOption, dmOption, switchOption, doneOption);
+
+		const choice = await ctx.ui.select(screenTitle(session.loaded, "switchback configuration"), options);
+		if (choice === undefined || choice === doneOption) return "done";
+		if (choice === switchOption) return "switch";
+		if (choice === debugOption) {
+			await toggleDebug(ctx, session, config);
+			continue;
+		}
+		if (choice === dmOption) {
+			await decisionModelsMenu(ctx, session);
+			continue;
+		}
+		if (choice === addOption) {
+			await addVirtualModelWizard(ctx, session);
+			continue;
+		}
+		const model = config.models.find((m) => `${m.id} - ${m.name}` === choice);
+		if (model !== undefined) await virtualModelMenu(ctx, session, model);
+	}
+}
+
+async function toggleDebug(
+	ctx: DialogueContext,
+	session: DialogueSession,
+	config: SwitchbackFileConfig,
+): Promise<void> {
+	const next = !(config.debug === true);
+	setDebug(session.loaded, next);
+	if (await saveOrRevert(ctx, session)) {
+		ctx.ui.notify(`debug ${next ? "on" : "off"} - saved to ${session.loaded.path}`, "info");
+	}
+}
+
+async function virtualModelMenu(
+	ctx: DialogueContext,
+	session: DialogueSession,
+	model: SwitchbackConfig,
+): Promise<void> {
+	const renameIdOption = "Rename model id (pi restart required)";
+	const renameNameOption = "Change display name";
+	const editFallbacks = (n: number): string => `Edit fallbacks (${n})`;
+	const decisionOption = (config: SwitchbackConfig): string => `Decision model: ${describeJev(config.jev)}`;
+	const removeOption = "Remove model";
+	const backOption = "Back";
+	for (;;) {
+		const config = readConfigOrReport(ctx, session.loaded);
+		if (config === undefined) return;
+		const current = findModel(config, model.id);
+		if (current === undefined) return; // removed elsewhere in this session
+		const fallbacksOption = editFallbacks(current.fallbacks.length);
+		const decisionLabel = decisionOption(current);
+		const choice = await ctx.ui.select(screenTitle(session.loaded, `${current.id} - ${current.name}`), [
+			renameIdOption,
+			renameNameOption,
+			fallbacksOption,
+			decisionLabel,
+			removeOption,
+			backOption,
+		]);
+		if (choice === undefined || choice === backOption) return;
+		if (choice === renameIdOption) {
+			const newId = await promptRequired(
+				ctx,
+				screenTitle(
+					session.loaded,
+					`rename ${current.id} - new model id (bare "auto" becomes "switchback/auto")`,
+				),
+				current.id,
+			);
+			if (newId === undefined) continue;
+			renameVirtualModel(session.loaded, current.id, newId);
+			if (await saveOrRevert(ctx, session)) {
+				model.id = newId;
+				ctx.ui.notify(`renamed to ${newId} - the running pi keeps the old id until restart`, "info");
+			}
+			continue;
+		}
+		if (choice === renameNameOption) {
+			const newName = await promptRequired(
+				ctx,
+				screenTitle(session.loaded, `display name for ${current.id}`),
+				current.name,
+			);
+			if (newName === undefined) continue;
+			setVirtualModelName(session.loaded, current.id, newName);
+			if (await saveOrRevert(ctx, session)) model.name = newName;
+			continue;
+		}
+		if (choice === fallbacksOption) {
+			await fallbacksEditor(ctx, session, current.id);
+			continue;
+		}
+		if (choice === decisionLabel) {
+			await decisionModelPicker(ctx, session, current.id);
+			continue;
+		}
+		if (choice === removeOption) {
+			const configNow = readConfigOrReport(ctx, session.loaded);
+			if (configNow === undefined) return;
+			if (configNow.models.length <= 1) {
+				ctx.ui.notify("the last virtual model cannot be removed - add another one first", "warning");
+				continue;
+			}
+			const confirmed = await ctx.ui.confirm(
+				screenTitle(session.loaded, `remove ${current.id}`),
+				`Remove ${current.id} and its ${current.fallbacks.length} fallback(s) from ${session.loaded.path}?`,
+			);
+			if (!confirmed) continue;
+			removeVirtualModel(session.loaded, current.id);
+			if (await saveOrRevert(ctx, session)) {
+				ctx.ui.notify(`removed ${current.id}`, "info");
+				return;
+			}
+		}
+	}
+}
+
+async function fallbacksEditor(ctx: DialogueContext, session: DialogueSession, virtualId: string): Promise<void> {
+	const addOption = "Add fallback...";
+	const removeOption = "Remove fallback...";
+	const upOption = "Move up...";
+	const downOption = "Move down...";
+	const doneOption = "Done";
+	for (;;) {
+		const config = readConfigOrReport(ctx, session.loaded);
+		if (config === undefined) return;
+		const model = findModel(config, virtualId);
+		if (model === undefined) return;
+		const body = ["Fallbacks (first = preferred):", ...model.fallbacks.map((f, i) => `  ${i + 1}. ${f}`)].join(
+			"\n",
+		);
+		const choice = await ctx.ui.select(screenTitle(session.loaded, body), [
+			addOption,
+			removeOption,
+			upOption,
+			downOption,
+			doneOption,
+		]);
+		if (choice === undefined || choice === doneOption) return;
+		const labels = model.fallbacks.map((f, i) => `${i + 1}. ${f}`);
+		if (choice === addOption) {
+			const fallback = await chooseFallback(
+				ctx,
+				session,
+				screenTitle(session.loaded, `add fallback to ${virtualId} ("provider/id")`),
+				model.fallbacks,
+			);
+			if (fallback === undefined) continue;
+			addFallback(session.loaded, virtualId, fallback);
+			await saveOrRevert(ctx, session);
+			continue;
+		}
+		if (choice === removeOption) {
+			if (model.fallbacks.length <= 1) {
+				ctx.ui.notify("at least one fallback is required - add one before removing the last", "warning");
+				continue;
+			}
+			const target = await ctx.ui.select(screenTitle(session.loaded, "remove which fallback?"), labels);
+			const index = target === undefined ? -1 : labels.indexOf(target);
+			if (index < 0) continue;
+			removeFallback(session.loaded, virtualId, index);
+			await saveOrRevert(ctx, session);
+			continue;
+		}
+		if (choice === upOption || choice === downOption) {
+			const up = choice === upOption;
+			const candidates = model.fallbacks
+				.map((f, i) => ({ label: `${i + 1}. ${f}`, index: i }))
+				.filter((e) => (up ? e.index > 0 : e.index < model.fallbacks.length - 1));
+			if (candidates.length === 0) {
+				ctx.ui.notify(`that fallback list has nothing to move ${up ? "up" : "down"}`, "warning");
+				continue;
+			}
+			const target = await ctx.ui.select(
+				screenTitle(session.loaded, `move which fallback ${up ? "up" : "down"}?`),
+				candidates.map((e) => e.label),
+			);
+			const picked = target === undefined ? undefined : candidates.find((e) => e.label === target);
+			if (picked === undefined) continue;
+			moveFallback(session.loaded, virtualId, picked.index, up ? picked.index - 1 : picked.index + 1);
+			await saveOrRevert(ctx, session);
+		}
+	}
+}
+/** Wizard: create a new virtual model entry (id, name, at least one fallback). */
+async function addVirtualModelWizard(ctx: DialogueContext, session: DialogueSession): Promise<void> {
+	const id = await promptRequired(
+		ctx,
+		screenTitle(session.loaded, 'new virtual model - id (bare "auto" becomes "switchback/auto")'),
+		"auto",
+	);
+	if (id === undefined) return;
+	const name = await promptRequired(ctx, screenTitle(session.loaded, `display name for ${id}`), "e.g. Auto (fast)");
+	if (name === undefined) return;
+	const fallbacks: string[] = [];
+	const addOption = "Add fallback...";
+	const doneOption = "Done (needs at least one)";
+	for (;;) {
+		const body = [
+			"Fallbacks for the new model (first = preferred):",
+			...(fallbacks.length === 0 ? ["  (none yet)"] : fallbacks.map((f, i) => `  ${i + 1}. ${f}`)),
+		].join("\n");
+		const choice = await ctx.ui.select(screenTitle(session.loaded, body), [addOption, doneOption]);
+		if (choice === undefined) return;
+		if (choice === addOption) {
+			const fallback = await chooseFallback(
+				ctx,
+				session,
+				screenTitle(session.loaded, `fallback ${fallbacks.length + 1} ("provider/id")`),
+				fallbacks,
+			);
+			if (fallback !== undefined) fallbacks.push(fallback);
+			continue;
+		}
+		if (fallbacks.length === 0) {
+			ctx.ui.notify("at least one fallback is required - add one first", "warning");
+			continue;
+		}
+		break;
+	}
+	try {
+		addVirtualModel(session.loaded, { id, name, fallbacks });
+	} catch (error) {
+		ctx.ui.notify(errorMessage(error), "warning");
+		return;
+	}
+	if (await saveOrRevert(ctx, session)) {
+		ctx.ui.notify(
+			`${id} added with ${fallbacks.length} fallback(s) - use its menu to attach a decision model`,
+			"info",
+		);
+	}
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Barrel re-export for tests and downstream consumers of the pi adapter. The pi
+ * extension entry (`../index.ts`) imports its modules directly to keep its surface
+ * small; this barrel exists so a consumer can import the whole pi-side surface
+ * from `pi-switchback` without enumerating modules. The host-agnostic half lives
+ * in `switchback-core` and is re-exported here so one import still reaches
+ * everything.
+ */
+
+export * from "switchback-core";
+export { buildRoute, ConfigInvalidError } from "./build-route.ts";
+export { runDialogue, layerOptionLabel } from "./dialogue.ts";
+export { describeJev } from "./dialogue-ui.ts";
+export { createModelPicker, buildModelItems, MODEL_PICKER_MAX_VISIBLE } from "./model-picker.ts";
+export type { ModelPickerSource, PickerColor, PickerKeybindings, PickerTheme, PickerTui } from "./model-picker.ts";
+export type { DialogueContext, DialogueUi } from "./dialogue-ui.ts";
+export { createSecretStore, secretsFilePath, powershellDpapi, SecretsError } from "./secrets.ts";
+export type { SecretStore, Dpapi } from "./secrets.ts";