feat(models): strong/cheap/vision model slots + multi-provider engine federation

Model slots wave (2026-09-20), chunk B:

- settings: new `models` section {strong, cheap, vision} slots (each
  field independent, same shape as a role override); ROLE_SLOT maps all
  nine roles to tiers (strong=prober+teacher, cheap=researcher/
  demoBuilder/extractor/auditor/labeler, vision=visualMaker+pdfReader);
  resolution chain per role: override → slot → factory pin.
- config: ModelSpec gains provider (all pins openrouter, the BYOK
  default); MODEL_PINS in stores.ts now spans all nine roles (the strong
  slot's factory rep IS the prober pin).
- engine: piModels() registers EVERY builtin provider catalog;
  piEngineForSpec(resolved spec) is the new engine factory (pi-ai
  resolves per-provider keys from env itself); piEngineFor stays as the
  config-pin fallback. chat-handler resolves the conversation chain
  (chat override → strong slot → pin) and injects engineFor into the job
  runner, closing the old gap where per-role overrides never reached
  job engines.
- /api/models: models federate ONLY keyed providers (providers surface
  with keyPresent, env-wins, fresh per call); slots (resolved tier pins)
  join rolePins; catalogDefaultsFor inherits the strong slot; the models
  settings section gets the same catalog gate as chat.
- pricing: PRICES/CONTEXT_LIMITS uniformly keyed provider:id
  (regenerated from ALL pi-ai catalogs, 1354 keys); usage stamps
  (TurnUsage, JobUsage, extraction stages) switch to provider:id —
  owner decision: no legacy compat, old stamps render unpriced.

src/server/chat-handler.ts

@@ -1,7 +1,7 @@
 import type { UIMessage } from "ai";
 import type { Usage } from "@earendil-works/pi-ai";
 import { createProberAgent, createTeacherAgent, type AgentBuildOptions, type TeachingAgent } from "../agent/teacher-agent.ts";
-import { piEngineFor } from "../agent/models.ts";
+import { piEngineForSpec } from "../agent/models.ts";
 import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createExtractionPipeline } from "../agent/subagents/extraction.ts";
 import { runGraphContextJob, type GraphContextDeps } from "../agent/subagents/graph-context.ts";
@@ -10,8 +10,8 @@ import type { ModelRole } from "../../config.ts";
 import { claimSteers, deliverJobResult, setContextRespawn, setJobRespawn, setTurnRunner } from "./jobs.ts";
 import { recordToPiMessages } from "./pi/record-adapter.ts";
 import { createPiTurnResponse } from "./pi/ui-stream.ts";
-import { effectiveSettings, stores } from "./stores.ts";
-import { extractionEnabled, graphContextEnabled } from "../core/settings-resolution.ts";
+import { effectiveSettings, MODEL_PINS, stores } from "./stores.ts";
+import { extractionEnabled, graphContextEnabled, resolveRoleSpec } from "../core/settings-resolution.ts";
 import { beginTurn, endTurn } from "./turn-liveness.ts";
 import { persistTurn, triggerExtraction, triggerGraphContext, withMessageIds } from "./turn-service.ts";
 import type { CallUsage } from "../core/contracts.ts";
@@ -39,6 +39,12 @@ const jobRunner = createJobRunner({
 	chatStore: stores.chatStore,
 	jobStore: stores.jobStore,
 	deliver: deliverJobResult,
+	// Model slots wave (2026-09-20): job engines resolve the full chain —
+	// role override → slot → factory pin — read FRESH per job (a settings
+	// PUT between dispatch and spawn lands). Closes the old gap where
+	// per-role overrides reached rolePins but never the engines.
+	engineFor: (role) =>
+		piEngineForSpec(resolveRoleSpec(role, stores.settingsStore.readSettings(), MODEL_PINS)),
 });
 /** The app's ONE extraction pipeline instance — both front doors share it:
  *  quiz-triggered session runs (turn-service) and notes imports
@@ -205,8 +211,18 @@ export async function handleChatRequest(
 	// for the conversation agents; piEngineFor falls back to config on absent
 	// fields and clamps the thinking level to the model's supported list).
 	const settings = stores.chatStore.getChat(chatId)?.settings;
-	const engine = piEngineFor(role, settings);
-	const modelId = engine.model.id;
+	// Model slots wave (2026-09-20): the conversation chain is the chat's
+	// own override over the STRONG slot (prober + teacher's tier) over the
+	// factory pin — each field independent, same discipline as the roles.
+	const strong = effective.models.strong;
+	const engine = piEngineForSpec({
+		provider: settings?.model?.provider ?? strong.provider,
+		id: settings?.model?.id ?? strong.id,
+		thinkingLevel: settings?.thinkingLevel ?? strong.thinkingLevel,
+	});
+	// Provider-qualified stamp (model slots wave): matches the price table's
+	// provider:id keys.
+	const modelId = `${engine.model.provider}:${engine.model.id}`;
 	// Tests inject a factory: the agent is stateless per turn (docs/
 	// pi-engine-swap.md §2), so each request builds a fresh one off the
 	// transcript — the factory mirrors that seam exactly.

src/server/model-catalog.ts

@@ -16,19 +16,22 @@
 
 import { getSupportedThinkingLevels, type Api, type Model } from "@earendil-works/pi-ai";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { MODELS } from "../../config.ts";
 import { piModels } from "../agent/models.ts";
 import { settingsStore } from "../store/settings.ts";
 import { effectiveSettings } from "./stores.ts";
+import { keyValue } from "./keys.ts";
 import type { ChatSettings } from "../core/contracts/chat.ts";
 import type {
 	CatalogDefaults,
+	CatalogProvider,
 	ModelCatalogEntry,
 	ModelCatalogResponse,
 	RolePins,
+	SlotPins,
 } from "../core/contracts/models.ts";
-import type { EffectiveModelSpec } from "../core/settings-resolution.ts";
-import { BACKGROUND_MODEL_ROLES, type BackgroundModelRole } from "../core/settings.ts";
+import type { EffectiveModelSpec, EffectiveSlot } from "../core/settings-resolution.ts";
+import { AUTH_PROVIDER_KEYS } from "../core/auth-keys.ts";
+import { BACKGROUND_MODEL_ROLES, type BackgroundModelRole, type ModelSlotName, type ModelsSettings } from "../core/settings.ts";
 
 /** The picker's client-safe model entry (contract: core/contracts/models.ts). */
 export type ModelDto = ModelCatalogEntry;
@@ -37,10 +40,10 @@ export type ModelDto = ModelCatalogEntry;
  *  chat section in, CatalogDefaults out; `catalogDefaults()` below is the
  *  fs wrapper). Absent fields (or no record — BYOK first boot) fall back
  *  to the config pin, exactly as before. */
-export function catalogDefaultsFor(chat?: ChatSettings): CatalogDefaults {
+export function catalogDefaultsFor(chat: ChatSettings | undefined, strong: EffectiveSlot): CatalogDefaults {
 	return {
-		model: chat?.model ?? { provider: "openrouter", id: MODELS.prober.model },
-		thinkingLevel: (chat?.thinkingLevel ?? MODELS.prober.effort) as ThinkingLevel,
+		model: chat?.model ?? { provider: strong.provider, id: strong.id },
+		thinkingLevel: chat?.thinkingLevel ?? strong.thinkingLevel,
 	};
 }
 
@@ -49,7 +52,7 @@ export function catalogDefaultsFor(chat?: ChatSettings): CatalogDefaults {
  *  the settings record's `chat` section; the picker's defaults row shows
  *  it once chosen. */
 export function catalogDefaults(): CatalogDefaults {
-	return catalogDefaultsFor(settingsStore.readSettings()?.chat);
+	return catalogDefaultsFor(settingsStore.readSettings()?.chat, effectiveSettings().models.strong);
 }
 
 /** Project the resolved per-role specs to the client DTO (pure — the
@@ -77,6 +80,42 @@ export function catalogRolePins(): RolePins {
 	return rolePinsFor(effectiveSettings().agent.models);
 }
 
+/** The three slot tiers' RESOLVED pins (model slots wave, 2026-09-20) —
+ *  effectiveSettings().models verbatim: slot over factory rep pin, the
+ *  same resolution the engine wiring uses, so the Models settings page's
+ *  captions cannot drift from what actually runs. */
+export function catalogSlots(): SlotPins {
+	const slots = effectiveSettings().models;
+	const pins = {} as SlotPins;
+	for (const name of ["strong", "cheap", "vision"] as const) {
+		const slot: EffectiveSlot = slots[name];
+		pins[name] = {
+			model: { provider: slot.provider, id: slot.id },
+			thinkingLevel: slot.thinkingLevel,
+		};
+	}
+	return pins;
+}
+
+/** The providers surface (model slots wave, 2026-09-20): one row per
+ *  plain-key model provider (core/auth-keys.ts's pi-ai-derived table),
+ *  with keyPresent read env-wins through the keys seam, fresh per call —
+ *  saving a key immediately federates the provider into the picker. */
+export function catalogProviders(): CatalogProvider[] {
+	return AUTH_PROVIDER_KEYS.map((p) => ({
+		id: p.id,
+		envVar: p.envVar,
+		keyPresent: keyValue(p.envVar) !== undefined,
+	})).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** The providers whose key is present — the picker federates exactly
+ *  these (a keyless provider's models are unreachable by design; the
+ *  Keys page is the discovery surface, same discipline as search). */
+function keyedProviderIds(): Set<string> {
+	return new Set(catalogProviders().filter((p) => p.keyPresent).map((p) => p.id));
+}
+
 /** Project one catalog model to the client DTO. */
 export function toModelDto(model: Model<Api>): ModelDto {
 	return {
@@ -102,12 +141,20 @@ export function toModelDto(model: Model<Api>): ModelDto {
  *  defaults a settings-less chat runs + the background roles' resolved
  *  pins (the settings UI's per-role default captions). */
 export function modelCatalog(): ModelCatalogResponse {
+	const keyed = keyedProviderIds();
 	const models = piModels()
 		.getProviders()
+		.filter((p) => keyed.has(p.id))
 		.flatMap((p) => piModels().getModels(p.id))
 		.map(toModelDto)
 		.sort((a, b) => (a.provider === b.provider ? a.id.localeCompare(b.id) : a.provider.localeCompare(b.provider)));
-	return { models, defaults: catalogDefaults(), rolePins: catalogRolePins() };
+	return {
+		models,
+		defaults: catalogDefaults(),
+		rolePins: catalogRolePins(),
+		slots: catalogSlots(),
+		providers: catalogProviders(),
+	};
 }
 
 /** One validated outcome for a settings write. */
@@ -133,8 +180,11 @@ export function validateChatSettings(settings: ChatSettings): SettingsValidation
 		}
 	}
 	if (settings.thinkingLevel !== undefined) {
-		const provider = settings.model?.provider ?? "openrouter";
-		const id = settings.model?.id ?? MODELS.prober.model;
+		// The conversation chain's fallback is the strong slot (model slots
+		// wave, 2026-09-20) — the model a settings-less chat would run.
+		const strong = effectiveSettings().models.strong;
+		const provider = settings.model?.provider ?? strong.provider;
+		const id = settings.model?.id ?? strong.id;
 		const model = piModels().getModel(provider, id);
 		if (!model) return { ok: false, error: `No model "${id}" in the ${provider} catalog` };
 		const supported = getSupportedThinkingLevels(model);
@@ -147,4 +197,48 @@ export function validateChatSettings(settings: ChatSettings): SettingsValidation
 		}
 	}
 	return { ok: true };
-}
+}
+/** Validate a models-section write (PUT /api/settings/models) against the
+ *  catalog — the same gate the chat section gets. Model swaps must name a
+ *  real provider+model; a thinkingLevel must be supported by the model the
+ *  slot would resolve to (the slot's own model, else the factory rep pin).
+ *  keyPresent is NOT gated here (a stored pin for a provider whose key
+ *  lapsed stays valid — it fails honestly at stream time, and the picker
+ *  stops offering it). */
+export function validateModelsSettings(settings: ModelsSettings): SettingsValidation {
+	for (const name of ["strong", "cheap", "vision"] as const) {
+		const slot = settings[name];
+		if (!slot) continue;
+		const verdict = validateSlotSpec(name, slot);
+		if (!verdict.ok) return verdict;
+	}
+	return { ok: true };
+}
+
+function validateSlotSpec(name: ModelSlotName, slot: { model?: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }): SettingsValidation {
+	const providers = piModels().getProviders().map((p) => p.id);
+	if (slot.model) {
+		const { provider, id } = slot.model;
+		if (!providers.includes(provider)) {
+			return { ok: false, error: `Unknown provider "${provider}" — configured: ${providers.join(", ")}` };
+		}
+		if (!piModels().getModel(provider, id)) {
+			return { ok: false, error: `No model "${id}" in the ${provider} catalog` };
+		}
+	}
+	if (slot.thinkingLevel !== undefined) {
+		const provider = slot.model?.provider ?? effectiveSettings().models[name].provider;
+		const id = slot.model?.id ?? effectiveSettings().models[name].id;
+		const model = piModels().getModel(provider, id);
+		if (!model) return { ok: false, error: `No model "${id}" in the ${provider} catalog` };
+		const supported = getSupportedThinkingLevels(model);
+		if (!supported.includes(slot.thinkingLevel)) {
+			return {
+				ok: false,
+				error: `${id} does not support thinking level "${slot.thinkingLevel}"`,
+				supported,
+			};
+		}
+	}
+	return { ok: true };
+}

src/server/settings-body.ts

@@ -19,9 +19,10 @@ import type {
 	BackgroundModelRole,
 	GeneralSettings,
 	GraphSettings,
+	ModelsSettings,
 	RoleModelOverride,
 } from "../core/settings.ts";
-import { BACKGROUND_MODEL_ROLES } from "../core/settings.ts";
+import { BACKGROUND_MODEL_ROLES, MODEL_SLOTS } from "../core/settings.ts";
 import { TOGGLEABLE_TOOLS } from "../core/pending.ts";
 
 /** Parsed-or-rejected — `ok: false` carries the 400's error message. */
@@ -292,6 +293,31 @@ export function parseGraphSettingsBody(body: unknown): SettingsBodyResult<GraphS
 	return { ok: true, settings };
 }
 
+/** models: { strong?, cheap?, vision? } — the slot tiers (model slots
+ *  wave, 2026-09-20). Each slot is the same shape as a role override; a
+ *  present-but-empty slot object is rejected (absent slot = unset; say
+ *  what you mean). Catalog validity is checked by the route
+ *  (validateChatSettings discipline). */
+export function parseModelsSettingsBody(body: unknown): SettingsBodyResult<ModelsSettings> {
+	const raw = asRecord(body);
+	if (!raw) return { ok: false, error: "Invalid JSON body" };
+	const settings: ModelsSettings = {};
+	for (const key of Object.keys(raw)) {
+		const known = MODEL_SLOTS as readonly string[];
+		if (!known.includes(key)) {
+			return { ok: false, error: `unknown slot "${key}" (supported: ${known.join(", ")})` };
+		}
+		const parsed = parseRoleOverride(raw[key], key);
+		if (!parsed.ok) return { ok: false, error: parsed.error };
+		if (Object.keys(parsed.override).length) {
+			settings[key as (typeof MODEL_SLOTS)[number]] = parsed.override;
+		} else {
+			return { ok: false, error: `slot "${key}" must set model or thinkingLevel (absent slot = unset)` };
+		}
+	}
+	return { ok: true, settings };
+}
+
 /** The section→parser map for PUT /api/settings/[section] (the route also
  *  carries the special prompts sub-resource). */
 export const SETTINGS_SECTIONS = {
@@ -300,6 +326,7 @@ export const SETTINGS_SECTIONS = {
 	agent: parseAgentSettingsBody,
 	appearance: parseAppearanceSettingsBody,
 	graph: parseGraphSettingsBody,
+	models: parseModelsSettingsBody,
 } as const;
 
 export type SettingsSectionName = keyof typeof SETTINGS_SECTIONS;

src/server/stores.ts

@@ -22,20 +22,25 @@ export const stores = {
 
 export type Stores = typeof stores;
 
-/** config.ts's MODELS narrowed to the background roles — the compiled
- *  factory layer the resolution reads. core stays pure (it takes this as a
- *  parameter, never imports config at runtime); the prober/teacher pins
- *  are chat-settings-controlled and deliberately absent here. Tests pin
- *  that the role set matches core's BACKGROUND_MODEL_ROLES. */
-const BACKGROUND_MODEL_PINS: ModelRoleSpecs = {
+/** config.ts's MODELS as the compiled factory layer the resolution reads —
+ *  ALL NINE roles since the model-slots wave (2026-09-20): the strong
+ *  slot's factory fallback IS the prober pin. core stays pure (it takes
+ *  this as a parameter, never imports config at runtime). Per-role
+ *  OVERRIDES stay background-only (the conversation pair is
+ *  chat-settings-controlled) — that split lives in core's
+ *  BACKGROUND_MODEL_ROLES, unchanged. */
+const MODEL_PINS: ModelRoleSpecs = {
+	prober: MODELS.prober,
+	teacher: MODELS.teacher,
 	researcher: MODELS.researcher,
 	demoBuilder: MODELS.demoBuilder,
 	visualMaker: MODELS.visualMaker,
+	pdfReader: MODELS.pdfReader,
 	extractor: MODELS.extractor,
 	auditor: MODELS.auditor,
 	labeler: MODELS.labeler,
 };
-export { BACKGROUND_MODEL_PINS };
+export { MODEL_PINS };
 
 /**
  * The resolved view of the settings record (core/settings-resolution.ts):
@@ -44,5 +49,5 @@ export { BACKGROUND_MODEL_PINS };
  * no caching layer (stale toggles after a settings PUT would be worse).
  */
 export function effectiveSettings(): EffectiveSettings {
-	return resolveSettings(settingsStore.readSettings(), BACKGROUND_MODEL_PINS);
+	return resolveSettings(settingsStore.readSettings(), MODEL_PINS);
 }