switchback-core 2026.10.14 → 2026.10.16

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "switchback-core",
-	"version": "2026.10.14",
+	"version": "2026.10.16",
 	"type": "module",
 	"description": "Host-agnostic core for switchback: fallback routing, error classification ports, block state and configuration.",
 	"license": "MIT",
@@ -29,6 +29,7 @@
 		"access": "public"
 	},
 	"dependencies": {
+		"@typesafe-ai/sdk": "^0.7.0",
 		"yaml": "^2.9.1"
 	},
 	"peerDependencies": {

package/src/availability.ts

@@ -19,7 +19,7 @@
  */
 
 import type { AvailabilityPort, HostModel } from "./ports.ts";
-import type { Availability, BlockedMap, ModelId, ResolvedEntry, ResolvedFallbacks } from "./types.ts";
+import type { Availability, BlockedMap, DisabledMap, ModelId, ResolvedEntry, ResolvedFallbacks } from "./types.ts";
 
 function splitModelId(modelId: ModelId): { provider: string; id: string } | undefined {
 	const slash = modelId.indexOf("/");
@@ -124,6 +124,7 @@ export function pickNextEffective(
 	now: number,
 	startAfter?: ModelId,
 	excluded?: ReadonlySet<ModelId>,
+	disabled?: DisabledMap,
 ): { modelId: ModelId; degraded: boolean } | undefined {
 	const effective = effectiveIds(resolved);
 	if (effective.length === 0) return undefined;
@@ -132,14 +133,14 @@ export function pickNextEffective(
 	for (let i = 0; i < count; i++) {
 		const candidate = effective[(start + i) % count]!;
 		if (candidate === skip || excluded?.has(candidate) === true) continue;
+		if (disabled?.[candidate] !== undefined) continue;
 		const blockedUntil = blocked[candidate];
 		if (blockedUntil !== undefined && blockedUntil > now) continue;
 		return { modelId: candidate, degraded: false };
 	}
 	// Degraded mode: only when exactly one effective entry exists. Edge case #4.
-	// An excluded model (one that already failed in this cascade) is never offered,
-	// not even degraded.
-	if (count === 1 && excluded?.has(effective[0]!) !== true) {
+	// An excluded or manually disabled model is never offered, not even degraded.
+	if (count === 1 && excluded?.has(effective[0]!) !== true && disabled?.[effective[0]!] === undefined) {
 		return { modelId: effective[0]!, degraded: true };
 	}
 	// Multiple effective entries all blocked: return undefined so the router

package/src/classify.ts

@@ -33,7 +33,7 @@
  *      Kept deliberately: the directive explicitly allows typed signals from
  *      pi, only the message-derived heuristics are forbidden.
  *
- *   2. CLASSIFIER: the configured `jev` entry via `ctx.modelRegistry.classify`.
+ *   2. CLASSIFIER: the configured `decisionModel` entry via `ctx.modelRegistry.classify`.
  *      The structured-output answers (class / reset score / scope) are the
  *      ONLY message-derived decisions. Score is mapped to ms via
  *      `scoreToResetAtMs` (rubric index, 31d cap). Timeout, parse error,
@@ -90,7 +90,7 @@ const MAX_RESET_MS = 31 * 24 * 3_600_000;
  * v4 (2026-10-06): the `scope` question now anchors each option in wording the
  * message actually contains. v3 asked the model to judge counterfactuals ("other
  * models still work") and named only `unknown` in its instructions, so `unknown`
- * took the prior mass and won on every case measured - `typesafe/jev-latest`
+ * took the prior mass and won on every case measured - `typesafe/decisionModel-latest`
  * answered `unknown` at 84-92% with `account` second. The new text gives the
  * model the lexical cues an error message really carries (a named model, a key
  * or plan, an address) and asks for `unknown` only as a last resort. Verdicts
@@ -104,7 +104,7 @@ const MAX_RESET_MS = 31 * 24 * 3_600_000;
  * model or series / a credential, plan, balance or usage quota / an address or
  * region), which is a property of the question rather than of any provider.
  * Measured before and after on two held-out messages that were never in the
- * corpus: `typesafe/jev-latest` 7/7 with and without the examples, so the
+ * corpus: `typesafe/decisionModel-latest` 7/7 with and without the examples, so the
  * hosted classifier never needed them; `parable/tinyjev:latest` drops 7/7 ->
  * 5/7, losing `weekly token limit exhausted` and `monthly cap`, which the
  * smaller model needed a concrete anchor for. The hosted path is what the
@@ -239,9 +239,12 @@ function normaliseScope(value: unknown): ErrorScope {
 	return "unknown";
 }
 
-/** Find a classifier in the model registry. The provider+id are looked up via JevConfig. */
-function findJev(registry: ClassifierPort, jev: { provider: string; id: string }): ClassifierEntry | undefined {
-	return registry.findOfType("classifier", jev.provider, jev.id);
+/** Find a classifier in the model registry. The provider+id are looked up via DecisionModelConfig. */
+function findJev(
+	registry: ClassifierPort,
+	decisionModel: { provider: string; id: string },
+): ClassifierEntry | undefined {
+	return registry.findOfType("classifier", decisionModel.provider, decisionModel.id);
 }
 
 /**
@@ -340,14 +343,14 @@ export type ClassifierCallResult =
  */
 export async function callClassifier(
 	registry: ClassifierPort,
-	jev: { provider: string; id: string } | undefined,
+	decisionModel: { provider: string; id: string } | undefined,
 	context: ClassifierContext,
 	timeoutMs: number = CLASSIFIER_TIMEOUT_MS,
 ): Promise<ClassifierCallResult> {
-	if (jev === undefined) {
+	if (decisionModel === undefined) {
 		return { kind: "no-classifier", reason: "not-configured" };
 	}
-	const handle = findJev(registry, jev);
+	const handle = findJev(registry, decisionModel);
 	if (handle === undefined) {
 		return { kind: "no-classifier", reason: "unresolvable" };
 	}
@@ -408,7 +411,7 @@ export function readConfidence(result: ClassifierResult, questionId: string): nu
 export async function classifyError(
 	message: string,
 	registry: ClassifierPort,
-	jev: { provider: string; id: string } | undefined,
+	decisionModel: { provider: string; id: string } | undefined,
 	now: number = Date.now(),
 	stopReason?: StopReason,
 ): Promise<ClassificationResult> {
@@ -442,7 +445,7 @@ export async function classifyError(
 
 	// Branch 2: classifier. Any failure (not configured, unresolvable,
 	// timeout, threw, unparseable) falls through to "no-classifier".
-	const call = await callClassifier(registry, jev, {
+	const call = await callClassifier(registry, decisionModel, {
 		state: classifierState(message),
 		questions: JEV_QUESTIONS,
 	});

package/src/config-editor.ts

@@ -11,10 +11,9 @@
  * Validation lives in exactly one place. Every mutation is structural only
  * (locate a node, set/splice/delete); `saveLayer()` re-validates the whole
  * document through the exported `validateFileConfig()` - the same gate the
- * loader applies - and then re-checks every `jev.decisionModel` reference
- * through the exported `resolveJevConfig()`. The editor therefore carries
- * no rule set of its own: a save either produces exactly what `loadConfig()`
- * would accept, or throws the loader's own ConfigError messages.
+ * loader applies. The editor therefore carries no rule set of its own: a save
+ * either produces exactly what `loadConfig()` would accept, or throws the
+ * loader's own ConfigError messages.
  *
  * Secrets: API keys never enter the file as literals. The decision-model
  * operations accept a secret NAME (`apiKeySecretName`), and the value is
@@ -36,8 +35,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomic } from "./atomic-write.ts";
 import { isMap, isSeq, parseDocument, type Document, type YAMLMap, type YAMLSeq } from "yaml";
-import { ConfigError, LOCAL_CLASSIFIER_APIS, piConfigDir, resolveJevConfig, validateFileConfig } from "./config.ts";
-import type { DecisionModelEntry, JevConfig, JevRef, ModelId, SwitchbackFileConfig } from "./types.ts";
+import { ConfigError, piConfigDir, validateFileConfig } from "./config.ts";
+import type { IdleResetConfig, ModelId, SwitchbackFileConfig } from "./types.ts";
 
 /** Which switchback.yaml layer the editor has open. */
 export type ConfigLayer = "global" | "project";
@@ -130,7 +129,7 @@ export function loadLayer(layer: ConfigLayer): LoadedLayer {
  * an invalid state.
  */
 export function readLayerConfig(loaded: LoadedLayer): SwitchbackFileConfig {
-	return validateFileConfig(loaded.doc.toJSON(), loaded.path);
+	return validateFileConfig(loaded.doc.toJSON(), loaded.path).config;
 }
 
 function errorMessage(error: unknown): string {
@@ -262,163 +261,166 @@ export function moveFallback(loaded: LoadedLayer, virtualId: string, from: numbe
 }
 
 /**
- * Set or clear a model's classifier. `null` clears the key (the model then
- * reports and blind-cycles without classifying), the ref form points at a
- * `decisionModels:` entry by name, and the inline form writes a complete
- * `JevConfig`. Reference validity is enforced at save time through
- * `resolveJevConfig`, so a dangling name fails the save, not the next load.
+ * Set or clear a model's decision model. `null` clears the key (the model then
+ * reports and blind-cycles without classifying). The value is a decision-model
+ * address ("provider/model-id"); connection details, when the address needs a
+ * direct endpoint, live in the top-level `decisionModels:` map under the same
+ * address.
  */
-export function setDecisionModel(
-	loaded: LoadedLayer,
-	virtualId: string,
-	value: JevConfig | { decisionModel: string } | null,
-): void {
+export function setDecisionModel(loaded: LoadedLayer, virtualId: string, address: string | null): void {
 	const { node } = findModelNode(loaded, virtualId);
-	if (value === null) {
-		node.delete("jev");
+	if (address === null) {
+		node.delete("decisionModel");
 		return;
 	}
-	node.set("jev", loaded.doc.createNode(value));
+	node.set("decisionModel", address);
 }
 
-/** A decision-model entry as the editor accepts it: the apiKey is a secret NAME, never a value. */
+/** A decision-model entry as the editor accepts it. */
 export interface DecisionModelInput {
-	name: string;
-	provider: string;
-	id: string;
+	/** "provider/model-id" - the map key, and the value a chain names. */
+	address: string;
+	/** Direct SystemOne endpoint; omit for catalog resolution. */
 	baseUrl?: string;
-	api?: string;
-	/** Stored in YAML as `secret:<name>`; the value itself goes into the encrypted store. */
+	/**
+	 * Secret-store name, written as `secret:<name>`. Omit for an endpoint that
+	 * ignores the bearer token; the entry then carries `apiKey: local`.
+	 */
 	apiKeySecretName?: string;
 }
 
-/** Field-level patch for an existing decision model; `null` clears an optional field. */
+/** Field-level patch for an existing decision model; `null` clears the field. */
 export interface DecisionModelPatch {
-	provider?: string;
-	id?: string;
+	/** `null` also clears `apiKey` (the loader rule: it requires baseUrl). */
 	baseUrl?: string | null;
-	api?: string | null;
+	/** `null` writes `apiKey: local` - only meaningful with a baseUrl. */
 	apiKeySecretName?: string | null;
 }
 
-/** A file-level decisionModels entry as the parser produces it. */
-type DecisionModelNode = Omit<DecisionModelEntry, "apiKey"> & { apiKey?: string };
+/** A `decisionModels:` map value as the parser produces it. */
+interface DecisionModelNode {
+	baseUrl?: string;
+	apiKey?: string;
+}
 
 function decisionModelToNode(doc: Document, input: DecisionModelInput): YAMLMap {
 	const entry: DecisionModelNode = {
-		name: input.name,
-		provider: input.provider,
-		id: input.id,
 		...(input.baseUrl !== undefined ? { baseUrl: input.baseUrl } : {}),
-		...(input.api !== undefined ? { api: input.api } : {}),
-		...(input.apiKeySecretName !== undefined ? { apiKey: `secret:${input.apiKeySecretName}` } : {}),
+		...(input.baseUrl !== undefined
+			? { apiKey: input.apiKeySecretName === undefined ? "local" : `secret:${input.apiKeySecretName}` }
+			: {}),
 	};
 	return doc.createNode(entry) as YAMLMap;
 }
 
-function requireDecisionModelsSeq(loaded: LoadedLayer): YAMLSeq {
-	const seq = loaded.doc.get("decisionModels");
-	if (seq === undefined || seq === null) {
-		const created = loaded.doc.createNode([]) as YAMLSeq;
+function requireDecisionModelsMap(loaded: LoadedLayer): YAMLMap {
+	const map = loaded.doc.get("decisionModels");
+	if (map === undefined || map === null) {
+		const created = loaded.doc.createNode({}) as YAMLMap;
 		loaded.doc.set("decisionModels", created);
 		return created;
 	}
-	if (!isSeq(seq)) throw new ConfigError("decisionModels must be an array", loaded.path);
-	return seq;
+	if (!isMap(map)) {
+		throw new ConfigError('decisionModels must be a map keyed by "provider/model-id"', loaded.path);
+	}
+	return map;
 }
 
-/** Find a decisionModels entry node by name (the reference key). */
-function findDecisionModelNode(loaded: LoadedLayer, name: string): { seq: YAMLSeq; index: number; node: YAMLMap } {
-	const seq = requireDecisionModelsSeq(loaded);
-	for (const [index, item] of seq.items.entries()) {
-		if (item === null || !isMap(item)) continue;
-		if (item.get("name") === name) return { seq, index, node: item };
+/** Find a decisionModels entry node by its address (the map key). */
+function findDecisionModelNode(loaded: LoadedLayer, address: string): { map: YAMLMap; node: YAMLMap } {
+	const map = requireDecisionModelsMap(loaded);
+	const node = map.get(address, true);
+	if (node === undefined || node === null || !isMap(node)) {
+		throw new ConfigError(`decisionModels.${address} not found`, loaded.path);
 	}
-	throw new ConfigError(`decisionModel "${name}" not found`, loaded.path);
+	return { map, node };
 }
 
-/** Append a decision-model entry (duplicate names fail the save via `validateFileConfig`). */
+/** Add a decision-model entry (duplicate addresses fail the save via `validateFileConfig`). */
 export function addDecisionModel(loaded: LoadedLayer, input: DecisionModelInput): void {
-	const seq = requireDecisionModelsSeq(loaded);
-	for (const item of seq.items) {
-		if (item !== null && isMap(item) && item.get("name") === input.name) {
-			throw new ConfigError(`decisionModels contains the name "${input.name}" more than once`, loaded.path);
-		}
+	const map = requireDecisionModelsMap(loaded);
+	if (map.has(input.address)) {
+		throw new ConfigError(`decisionModels already contains "${input.address}"`, loaded.path);
 	}
-	seq.items.push(decisionModelToNode(loaded.doc, input));
+	map.set(input.address, decisionModelToNode(loaded.doc, input));
 }
 
-/** Patch one decision model's fields. `baseUrl: null` also clears `api`/`apiKey` (loader rule: they require baseUrl). */
-export function updateDecisionModel(loaded: LoadedLayer, name: string, patch: DecisionModelPatch): void {
-	const { node } = findDecisionModelNode(loaded, name);
-	if (patch.provider !== undefined) node.set("provider", patch.provider);
-	if (patch.id !== undefined) node.set("id", patch.id);
+/** Patch one decision model's connection details. */
+export function updateDecisionModel(loaded: LoadedLayer, address: string, patch: DecisionModelPatch): void {
+	const { node } = findDecisionModelNode(loaded, address);
 	if (patch.baseUrl !== undefined) {
 		if (patch.baseUrl === null) {
 			node.delete("baseUrl");
-			// api and apiKey are only valid alongside baseUrl; clearing baseUrl clears them.
-			node.delete("api");
+			// apiKey is only valid alongside baseUrl; clearing baseUrl clears it.
 			node.delete("apiKey");
 		} else {
 			node.set("baseUrl", patch.baseUrl);
+			if (!node.has("apiKey")) node.set("apiKey", "local");
 		}
 	}
-	if (patch.api !== undefined) {
-		if (patch.api === null) node.delete("api");
-		else node.set("api", patch.api);
-	}
 	if (patch.apiKeySecretName !== undefined) {
-		if (patch.apiKeySecretName === null) node.delete("apiKey");
-		else node.set("apiKey", `secret:${patch.apiKeySecretName}`);
+		node.set("apiKey", patch.apiKeySecretName === null ? "local" : `secret:${patch.apiKeySecretName}`);
 	}
 }
 
 /**
- * Rename a decision model and rewrite every `jev.decisionModel` reference to
- * it in the same transaction, so a rename cannot dangle references.
+ * Rename a decision-model address and rewrite every `models[].decisionModel`
+ * that names it in the same transaction, so a rename cannot dangle references.
  */
-export function renameDecisionModel(loaded: LoadedLayer, oldName: string, newName: string): void {
-	if (oldName !== newName) {
-		const seq = requireDecisionModelsSeq(loaded);
-		for (const item of seq.items) {
-			if (item !== null && isMap(item) && item.get("name") === newName) {
-				throw new ConfigError(`decisionModels contains the name "${newName}" more than once`, loaded.path);
-			}
+export function renameDecisionModel(loaded: LoadedLayer, oldAddress: string, newAddress: string): void {
+	if (oldAddress !== newAddress) {
+		const { map, node } = findDecisionModelNode(loaded, oldAddress);
+		if (map.has(newAddress)) {
+			throw new ConfigError(`decisionModels already contains "${newAddress}"`, loaded.path);
 		}
+		map.delete(oldAddress);
+		map.set(newAddress, node);
 	}
-	const { node } = findDecisionModelNode(loaded, oldName);
-	node.set("name", newName);
 	for (const item of requireModelsSeq(loaded).items) {
 		if (item === null || !isMap(item)) continue;
-		const jev = item.get("jev");
-		if (jev === null || jev === undefined || !isMap(jev)) continue;
-		if (jev.get("decisionModel") === oldName) jev.set("decisionModel", newName);
+		if (item.get("decisionModel") === oldAddress) item.set("decisionModel", newAddress);
 	}
 }
 
 /**
- * Remove a decision model. References are NOT rewritten: a model that still
- * names the removed entry fails `saveLayer()` through `resolveJevConfig` with
- * the loader's actionable message, so the user decides what happens to the
- * referencing model instead of the editor silently clearing it.
+ * Remove a decision model. References are NOT rewritten: a chain that still
+ * names the removed address falls back to catalog resolution, which pi can do
+ * and OpenCode cannot - the user decides what happens to the referencing model
+ * instead of the editor silently clearing it.
  */
-export function removeDecisionModel(loaded: LoadedLayer, name: string): void {
-	const { seq, index } = findDecisionModelNode(loaded, name);
-	seq.items.splice(index, 1);
+export function removeDecisionModel(loaded: LoadedLayer, address: string): void {
+	const { map } = findDecisionModelNode(loaded, address);
+	map.delete(address);
+	// An empty map is litter: drop the key so the file reads as if no entry was ever made.
+	if (map.items.length === 0) loaded.doc.delete("decisionModels");
 }
 
-/** How many configured models reference a decision model (the dialogue's confirm/warning text). */
-export function countDecisionModelReferences(loaded: LoadedLayer, name: string): number {
+/** How many configured models name a decision model (the dialogue's confirm/warning text). */
+export function countDecisionModelReferences(loaded: LoadedLayer, address: string): number {
 	let count = 0;
 	for (const item of requireModelsSeq(loaded).items) {
 		if (item === null || !isMap(item)) continue;
-		const jev = item.get("jev");
-		if (jev === null || jev === undefined || !isMap(jev)) continue;
-		if (jev.get("decisionModel") === name) count += 1;
+		if (item.get("decisionModel") === address) count += 1;
 	}
 	return count;
 }
 
+/**
+ * Set or clear a model's `idleReset:` option. A duration ("30m", "2h", ...)
+ * returns to the head of the fallback list after that much idle time;
+ * `classifier` asks the decision model; `null` deletes the key, which is the
+ * loader's default (`never`). Validation of the value itself is the loader's
+ * job at save time, so an unknown value surfaces with the loader's message.
+ */
+export function setIdleReset(loaded: LoadedLayer, virtualId: string, option: IdleResetConfig | null): void {
+	const { node } = findModelNode(loaded, virtualId);
+	if (option === null) {
+		node.delete("idleReset");
+		return;
+	}
+	node.set("idleReset", option);
+}
+
 /** Set the top-level `debug:` flag (per-switch diagnostics notifications). */
 export function setDebug(loaded: LoadedLayer, enabled: boolean): void {
 	loaded.doc.set("debug", enabled);
@@ -427,25 +429,17 @@ export function setDebug(loaded: LoadedLayer, enabled: boolean): void {
 /**
  * Validate the mutated document through the loader's single gate and write it
  * atomically. Throws ConfigError (the loader's own messages) when the edited
- * state is not a config `loadConfig()` would accept - including dangling
- * `jev.decisionModel` references, checked here through the exported
- * `resolveJevConfig`. On a throw the in-memory document keeps the edit so the
- * dialogue can re-enter the same editor for a fix.
+ * state is not a config `loadConfig()` would accept. On a throw the in-memory
+ * document keeps the edit so the dialogue can re-enter the same editor for a fix.
  */
 export function saveLayer(loaded: LoadedLayer): void {
 	if (loaded.doc.contents === undefined || loaded.doc.contents === null) {
 		loaded.doc.contents = loaded.doc.createNode({});
 	}
-	const parsed = validateFileConfig(loaded.doc.toJSON(), loaded.path);
-	for (const model of parsed.models) {
-		resolveJevConfig(parsed.decisionModels, model.jev as JevRef | undefined);
-	}
+	validateFileConfig(loaded.doc.toJSON(), loaded.path);
 	try {
 		writeFileAtomic(loaded.path, loaded.doc.toString());
 	} catch (error) {
 		throw new ConfigError(`cannot write config: ${errorMessage(error)}`, loaded.path);
 	}
 }
-
-/** The wire APIs a direct-endpoint decision model may use (re-exported for the dialogue menu). */
-export { LOCAL_CLASSIFIER_APIS };