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/core/contracts/chat.ts

@@ -86,7 +86,8 @@ export const GRAPH_CONTEXT_TOKENS_STOPS = [0, 64, 256, 1024, 4096, 16384] as con
  *  billed (CallUsage per agent step). Steps, not a sum: cost and context
  *  folds happen at read time (core/prices.ts). */
 export interface ExtractionStageUsage {
-	/** The OpenRouter model id that ran this stage. */
+	/** The model that ran this stage, provider-qualified ("provider:id" —
+	 *  model slots wave, 2026-09-20; matches PRICES' uniform keys). */
 	model: string;
 	steps: CallUsage[];
 }
@@ -142,7 +143,8 @@ export interface TurnUsage {
 	 *  entry to the transcript (the block this turn "belongs" to). */
 	messageId: string;
 	at: string;
-	/** The OpenRouter model id that ran the turn. */
+	/** The model that ran the turn, provider-qualified ("provider:id" —
+	 *  model slots wave, 2026-09-20; matches PRICES' uniform keys). */
 	model: string;
 	/** One entry per agent step (model call) in this turn. */
 	steps: CallUsage[];

src/core/contracts/jobs.ts

@@ -41,7 +41,8 @@ export interface JobRecord {
  * field NO model call reported stays undefined — absent is not zero (the
  * money-channel doctrine; cost renders "—", never $0). */
 export interface JobUsage {
-	/** The OpenRouter model id that ran the sub-agent. */
+	/** The model that ran the sub-agent, provider-qualified ("provider:id" —
+	 *  model slots wave, 2026-09-20; matches PRICES' uniform keys). */
 	model: string;
 	/** Running totals summed over the run's model calls so far. */
 	inputTokens: number | undefined;

src/core/contracts/models.ts

@@ -6,7 +6,7 @@
  * components never import from the server band).
  */
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { BackgroundModelRole } from "../settings.ts";
+import type { BackgroundModelRole, ModelSlotName } from "../settings.ts";
 
 /** One picker row: everything the UI shows about a model, projected from
  *  pi-ai's catalog. Costs are USD per 1M tokens (the same catalog, the same
@@ -42,6 +42,12 @@ export type RolePins = Record<
 	{ model: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }
 >;
 
+/** One slot tier's RESOLVED pin (model slots wave, 2026-09-20): the
+ *  strong/cheap/vision tier's concrete model — slot override falling back
+ *  to the factory rep pin. The settings UI captions each slot row with it
+ *  and the picker pre-fills from it. */
+export type SlotPins = Record<ModelSlotName, { model: { provider: string; id: string }; thinkingLevel?: ThinkingLevel }>;
+
 /** GET /api/models response. */
 export interface ModelCatalogResponse {
 	models: ModelCatalogEntry[];
@@ -49,4 +55,23 @@ export interface ModelCatalogResponse {
 	/** The six background roles' resolved pins (same resolution the agent
 	 *  factories use — src/server/stores.ts effectiveSettings). */
 	rolePins: RolePins;
+	/** The three slot tiers' resolved pins (model slots wave, 2026-09-20):
+	 *  same resolution chain — role override → slot → factory pin — reported
+	 *  at tier granularity; effectiveSettings().models verbatim. */
+	slots: SlotPins;
+	/** Providers with a PRESENT key, and which env var gates each — the
+	 *  model slots wave's federation surface (2026-09-20): the picker lists
+	 *  models from these providers' pi-ai catalogs only. Keyless providers
+	 *  are simply absent (the Keys page is the discovery surface, same
+	 *  discipline as the search engines). */
+	providers: CatalogProvider[];
+}
+
+/** One row of the providers surface. */
+export interface CatalogProvider {
+	id: string;
+	/** The env var whose presence federates this provider in. */
+	envVar: string;
+	/** Whether that var is currently present (env or auth file). */
+	keyPresent: boolean;
 }

src/core/settings-resolution.ts

@@ -23,23 +23,40 @@
  */
 
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ModelRole } from "../../config.ts";
 import type { ChatSettings } from "./contracts/chat.ts";
 import type { SearchEngineId } from "./search.ts";
 import {
 	BACKGROUND_MODEL_ROLES,
 	FACTORY_SETTINGS,
+	MODEL_SLOTS,
+	ROLE_SLOT,
 	type AgentSettings,
 	type BackgroundModelRole,
 	type FactorySettings,
 	type GeneralSettings,
 	type GraphSettings,
+	type ModelSlot,
+	type ModelSlotName,
 	type RoleModelOverride,
 	type UserSettings,
 } from "./settings.ts";
 
 /** The factory layer for model roles — config.ts's MODELS shape (types only
- *  here; the runtime object is threaded in by the caller). */
-export type ModelRoleSpecs = Record<BackgroundModelRole, { model: string; effort: ThinkingLevel }>;
+ *  here; the runtime object is threaded in by the caller). Model slots
+ *  (2026-09-20): the factory map spans ALL nine roles (the strong slot's
+ *  factory fallback is the prober pin), while per-role OVERRIDES stay
+ *  background-only (the conversation pair is chat-settings-controlled). */
+export type ModelRoleSpecs = Record<ModelRole, { provider: string; model: string; effort: ThinkingLevel }>;
+
+/** A fully-resolved model slot: the tier's concrete model (slot over factory
+ *  rep pin) — strong's factory rep is the prober pin, cheap's the researcher
+ *  pin, vision's the visualMaker pin (owner-settled tier mapping). */
+export interface EffectiveSlot {
+	provider: string;
+	id: string;
+	thinkingLevel: ThinkingLevel;
+}
 
 /** A fully-resolved model pin for one background role. */
 export interface EffectiveModelSpec {
@@ -68,23 +85,78 @@ export interface EffectiveSettings {
 		 *  lives in server/search.ts, where keys are visible. */
 		search: { engine?: SearchEngineId };
 	};
+	/** The resolved strong/cheap/vision slots (model slots wave,
+	 *  2026-09-20): each tier's concrete model (slot over factory rep pin)
+	 *  — the per-role chain (override → slot → pin) is resolved into
+	 *  agent.models; these are the tier-level views the picker captions. */
+	models: Record<ModelSlotName, EffectiveSlot>;
 	appearance: EffectiveAppearance;
 	graph: Required<GraphSettings>;
 }
 
-/** Resolve one background role's spec: record override per field,
- *  config.ts pin per absent field (provider pinned to openrouter today). */
+/** Full-chain resolution for ANY role (model slots wave, 2026-09-20):
+ *  per-role override (background roles only) → slot → factory pin. The
+ *  conversation pair (prober/teacher) resolves the same chain MINUS the
+ *  role override (their override is the chat's own settings — the
+ *  chat-handler overlays it itself). This is the engine wiring's one call. */
+export function resolveRoleSpec(
+	role: ModelRole,
+	record: UserSettings | null,
+	factory: ModelRoleSpecs,
+): EffectiveModelSpec {
+	const bg = BACKGROUND_MODEL_ROLES as readonly string[];
+	const override = bg.includes(role) ? record?.agent?.models?.[role as BackgroundModelRole] : undefined;
+	return resolveModelSpec(role as BackgroundModelRole, override, factory, record?.models);
+}
+
+/** The factory representative pin for a slot tier — the pin the slot
+ *  falls back to when unset (owner-settled mapping: strong's rep is the
+ *  prober pin — prober and teacher share the strong tier — cheap's the
+ *  researcher pin, vision's the visualMaker pin). */
+export function factorySlotRep(slot: ModelSlotName, factory: ModelRoleSpecs): EffectiveSlot {
+	const rep =
+		slot === "strong" ? factory.prober : slot === "cheap" ? factory.researcher : factory.visualMaker;
+	// The factory contract spans all nine roles (stores.ts MODEL_PINS) —
+	// the rep lookup cannot miss; the cast is for the checker only.
+	const r = rep as { provider: string; model: string; effort: ThinkingLevel };
+	return { provider: r.provider, id: r.model, thinkingLevel: r.effort };
+}
+
+/** Resolve one slot: the slot override per field, the factory rep pin per
+ *  absent field (model slots wave, 2026-09-20). */
+export function resolveSlot(
+	slot: ModelSlotName,
+	override: ModelSlot | undefined,
+	factory: ModelRoleSpecs,
+): EffectiveSlot {
+	const rep = factorySlotRep(slot, factory);
+	return {
+		provider: override?.model?.provider ?? rep.provider,
+		id: override?.model?.id ?? rep.id,
+		thinkingLevel: override?.thinkingLevel ?? rep.thinkingLevel,
+	};
+}
+
+/** Resolve one background role's spec — the model slots chain (owner
+ *  decision 2026-09-20): role override → SLOT → factory pin, each field
+ *  independent (a role can borrow only the slot's model, or only its
+ *  thinking budget). An absent provider coordinate anywhere resolves to
+ *  the factory pin's provider (the BYOK default, openrouter today) —
+ *  legacy ids without a provider ride the factory provider. */
 export function resolveModelSpec(
 	role: BackgroundModelRole,
 	override: RoleModelOverride | undefined,
 	factory: ModelRoleSpecs,
+	slots?: Partial<Record<ModelSlotName, ModelSlot>>,
 ): EffectiveModelSpec {
-	const spec = factory[role];
-	const model = override?.model;
+	// The factory contract spans all nine roles; background roles always hit.
+	const spec = factory[role] as { provider: string; model: string; effort: ThinkingLevel };
+	const slotName = ROLE_SLOT[role] as ModelSlotName | undefined;
+	const slot = slotName ? slots?.[slotName] : undefined;
 	return {
-		provider: model?.provider ?? "openrouter",
-		id: model?.id ?? spec.model,
-		thinkingLevel: override?.thinkingLevel ?? spec.effort,
+		provider: override?.model?.provider ?? slot?.model?.provider ?? spec.provider,
+		id: override?.model?.id ?? slot?.model?.id ?? spec.model,
+		thinkingLevel: override?.thinkingLevel ?? slot?.thinkingLevel ?? spec.effort,
 	};
 }
 
@@ -92,6 +164,7 @@ export function resolveModelSpec(
  *  field then lands on its factory default. */
 export function resolveSettings(record: UserSettings | null, factory: ModelRoleSpecs): EffectiveSettings {
 	const agent = record?.agent ?? {};
+	const modelsSection = record?.models ?? {};
 	const appearance = record?.appearance ?? {};
 	const md = appearance.mdRendering ?? {};
 	const graph = record?.graph ?? {};
@@ -99,7 +172,7 @@ export function resolveSettings(record: UserSettings | null, factory: ModelRoleS
 	const factoryMd = factoryAppearance.mdRendering;
 	const models = {} as Record<BackgroundModelRole, EffectiveModelSpec>;
 	for (const role of BACKGROUND_MODEL_ROLES) {
-		models[role] = resolveModelSpec(role, agent.models?.[role], factory);
+		models[role] = resolveModelSpec(role, agent.models?.[role], factory, modelsSection);
 	}
 	return {
 		general: {
@@ -112,6 +185,11 @@ export function resolveSettings(record: UserSettings | null, factory: ModelRoleS
 			prompts: agent.prompts ?? {},
 			search: agent.search ?? {},
 		},
+		models: {
+			strong: resolveSlot("strong", modelsSection.strong, factory),
+			cheap: resolveSlot("cheap", modelsSection.cheap, factory),
+			vision: resolveSlot("vision", modelsSection.vision, factory),
+		},
 		appearance: {
 			mode: appearance.mode ?? factoryAppearance.mode,
 			background: appearance.background ?? factoryAppearance.background,

src/core/settings.ts

@@ -57,6 +57,51 @@ export interface RoleModelOverride {
 	thinkingLevel?: ThinkingLevel;
 }
 
+// ─── Model slots (model slots wave, 2026-09-20) ──────────────────────────────
+
+/** The capability tiers a user can pin models into (owner-settled mapping):
+ *  strong = prober + teacher (also the per-session default-teacher
+ *  starting point); cheap = researcher, demo-builder, extractor, auditor,
+ *  labeler; vision = visual-maker + pdf-reader. Resolution per role:
+ *  ROLE OVERRIDE → slot → factory pin. */
+export const MODEL_SLOTS = ["strong", "cheap", "vision"] as const;
+export type ModelSlotName = (typeof MODEL_SLOTS)[number];
+
+/** One slot's override — same per-field independence as a role override:
+ *  absent model keeps the tier's current model, absent thinkingLevel keeps
+ *  its thinking budget. */
+export interface ModelSlot {
+	/** The model swap: both coordinates or neither. */
+	model?: { provider: string; id: string };
+	/** The thinking budget swap. */
+	thinkingLevel?: ThinkingLevel;
+}
+
+/** The `models` settings section (owner decision 2026-09-20: a dedicated
+ *  section — slots are engine-level choices, not one session's). All slots
+ *  optional: an absent slot means every role of its tier runs whatever the
+ *  deeper tiers of the chain resolve to (per-role override → factory pin). */
+export interface ModelsSettings {
+	strong?: ModelSlot;
+	cheap?: ModelSlot;
+	vision?: ModelSlot;
+}
+
+/** Which slot a role draws from (model slots wave, 2026-09-20). Includes the
+ *  conversation pair and pdfReader (not BackgroundModelRoles — the slot
+ *  tier spans every role; only background roles surface per-role overrides). */
+export const ROLE_SLOT: Readonly<Record<string, ModelSlotName>> = {
+	prober: "strong",
+	teacher: "strong",
+	researcher: "cheap",
+	demoBuilder: "cheap",
+	extractor: "cheap",
+	auditor: "cheap",
+	labeler: "cheap",
+	visualMaker: "vision",
+	pdfReader: "vision",
+};
+
 /** General settings — app-level behavior. Version DISPLAY and plans login
  *  live outside the record (package.json / auth.json) by owner decision. */
 export interface GeneralSettings {
@@ -140,6 +185,8 @@ export interface UserSettings {
 	 *  controls. NOT shown in the settings panel (owner decision). */
 	chat?: ChatSettings;
 	agent?: AgentSettings;
+	/** The strong/cheap/vision model slots (model slots wave, 2026-09-20). */
+	models?: ModelsSettings;
 	appearance?: AppearanceSettings;
 	graph?: GraphSettings;
 	[key: string]: unknown;
@@ -244,6 +291,18 @@ function sanitizeRoleOverride(raw: unknown): RoleModelOverride | undefined {
 	return Object.keys(out).length ? out : undefined;
 }
 
+/** The models section (model slots wave, 2026-09-20): each slot keeps
+ *  only well-formed parts — the same shape rules as a role override, so a
+ *  stale client can't park junk in a slot. */
+function sanitizeModels(raw: Record<string, unknown>): ModelsSettings {
+	const out: ModelsSettings = {};
+	for (const slot of MODEL_SLOTS) {
+		const cleaned = sanitizeRoleOverride(raw[slot]);
+		if (cleaned) out[slot] = cleaned;
+	}
+	return out;
+}
+
 function sanitizeBooleanMap(raw: unknown): Record<string, boolean> | undefined {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const out: Record<string, boolean> = {};
@@ -348,6 +407,10 @@ export function sanitizeUserSettings(raw: unknown): UserSettings | null {
 	if (r.appearance !== null && typeof r.appearance === "object" && !Array.isArray(r.appearance)) {
 		out.appearance = sanitizeAppearance(r.appearance as Record<string, unknown>);
 	}
+	if (r.models !== null && typeof r.models === "object" && !Array.isArray(r.models)) {
+		const models = sanitizeModels(r.models as Record<string, unknown>);
+		if (Object.keys(models).length) out.models = models;
+	}
 	if (r.graph !== null && typeof r.graph === "object" && !Array.isArray(r.graph)) {
 		out.graph = sanitizeGraph(r.graph as Record<string, unknown>);
 	}