switchback-core 2026.10.14 → 2026.10.16

package/src/index.ts

@@ -47,7 +47,24 @@ export {
 	CONTEXT_CANDIDATE_PROMPT_VERSION,
 } from "./context-fit.ts";
 export type { CandidateWindow, ContextCandidateChoice, ContextCandidateInput } from "./context-fit.ts";
-export { blockModel, isBlocked, readBlockedMap, unblockModel, stateFilePath } from "./state.ts";
+export {
+	blockModel,
+	clearDisabled,
+	disableModel,
+	disabledFilePath,
+	enableModel,
+	getPinnedModel,
+	isBlocked,
+	isDisabled,
+	pinFilePath,
+	readBlockedMap,
+	readDisabledMap,
+	readPinMap,
+	setPinnedModel,
+	stateFilePath,
+	unblockModel,
+} from "./state.ts";
+export type { PinMap } from "./state.ts";
 export {
 	readCrashMap,
 	recordCrash,
@@ -70,13 +87,17 @@ export {
 	ConfigError,
 	piConfigDir,
 	switchbackStateDir,
-	LOCAL_CLASSIFIER_APIS,
-	resolveJevConfig,
+	resolveDecisionModel,
 	resolveSecretApiKey,
 	validateFileConfig,
 } from "./config.ts";
-export type { SwitchbackConfig, SwitchbackFileConfig, JevConfig, SecretResolver } from "./config.ts";
-export type { JevRef, DecisionModelEntry, ResolvedSwitchbackConfig, ResolvedSwitchbackFileConfig } from "./types.ts";
+export type { SwitchbackConfig, SwitchbackFileConfig, DecisionModelConfig, SecretResolver } from "./config.ts";
+export type {
+	DecisionModelEntry,
+	DecisionModelId,
+	ResolvedSwitchbackConfig,
+	ResolvedSwitchbackFileConfig,
+} from "./types.ts";
 export {
 	addDecisionModel,
 	addFallback,
@@ -99,6 +120,7 @@ export {
 	setDecisionModel,
 	setDebug,
 	setFallbacks,
+	setIdleReset,
 	setVirtualModelName,
 	updateDecisionModel,
 } from "./config-editor.ts";
@@ -133,6 +155,7 @@ export type { AvailabilityPort } from "./ports.ts";
 export type {
 	Availability,
 	BlockedMap,
+	DisabledMap,
 	ClassifiedError,
 	ErrorClass,
 	ErrorScope,

package/src/routing.ts

@@ -67,12 +67,26 @@ import type { NoClassifierReason } from "./classify.ts";
 import { chooseContextCandidate, fitsContext } from "./context-fit.ts";
 import { assessFailure, recordDecideCrash } from "./failure.ts";
 import { decideIdleReset } from "./idle.ts";
-import { getPinnedModel, isBlocked, unblockModel } from "./state.ts";
-import type { BlockedMap, JevConfig, ModelId, ResolvedSwitchbackConfig, SwitchbackState, ErrorScope } from "./types.ts";
+import { getPinnedModel, isBlocked, isDisabled, unblockModel } from "./state.ts";
+import type {
+	BlockedMap,
+	DisabledMap,
+	DecisionModelConfig,
+	ModelId,
+	ResolvedSwitchbackConfig,
+	SwitchbackState,
+	ErrorScope,
+} from "./types.ts";
 
 export interface RouteInputs {
 	now: number;
 	blocked: BlockedMap;
+	/**
+	 * Models the user disabled by hand (`/switchback-disable`). Unlike `blocked`
+	 * these never expire; a disabled model is skipped in every chain and never
+	 * chosen as a pin or continuation target.
+	 */
+	disabled: DisabledMap;
 	/** The host's reasoning-level rules; see `packages/core/src/ports.ts`. */
 	support: ThinkingSupportPort;
 	/** Optional simulate-mode error message injected for `retry` requests. */
@@ -154,10 +168,11 @@ async function pickWithContextFit(opts: {
 	skip: ModelId | undefined;
 	excluded?: ReadonlySet<ModelId>;
 	blocked: BlockedMap;
+	disabled: DisabledMap;
 	now: number;
 	startAfter: ModelId | undefined;
 	registry: RouterRegistryPort;
-	jev: JevConfig | undefined;
+	decisionModel: DecisionModelConfig | undefined;
 	contextTokens: number | undefined;
 	reason?: string;
 	failedScope?: ErrorScope | undefined;
@@ -165,7 +180,7 @@ async function pickWithContextFit(opts: {
 	const excluded = opts.excluded ?? new Set<ModelId>();
 	const usable = walkOrder(opts.resolved, opts.startAfter)
 		.filter((id) => id !== opts.skip && !excluded.has(id))
-		.filter((id) => !isBlocked(id, opts.now, opts.blocked));
+		.filter((id) => !isBlocked(id, opts.now, opts.blocked) && !isDisabled(id, opts.disabled));
 	let eligible = usable
 		.map((id) => ({ id, model: lookupModel(opts.registry, id) }))
 		.filter((entry): entry is { id: ModelId; model: HostModel } => entry.model !== undefined);
@@ -177,7 +192,15 @@ async function pickWithContextFit(opts: {
 		if (fitting.length > 0) eligible = fitting;
 	}
 	if (eligible.length === 0)
-		return pickNextEffective(opts.resolved, opts.skip, opts.blocked, opts.now, opts.startAfter, excluded);
+		return pickNextEffective(
+			opts.resolved,
+			opts.skip,
+			opts.blocked,
+			opts.now,
+			opts.startAfter,
+			excluded,
+			opts.disabled,
+		);
 	const failedProvider = opts.skip === undefined ? undefined : providerPart(opts.skip);
 	const ordered = orderByScope(
 		eligible.map((entry) => entry.id),
@@ -188,7 +211,7 @@ async function pickWithContextFit(opts: {
 	if (ordered.length === 1) return { modelId: floor, degraded: false };
 	const choice = await chooseContextCandidate({
 		registry: opts.registry,
-		jev: opts.jev,
+		decisionModel: opts.decisionModel,
 		preferred: floor,
 		contextTokens: tokens ?? 0,
 		candidates: ordered.map((id) => {
@@ -227,7 +250,7 @@ function orderByScope(
 function describeNoClassifier(reason: NoClassifierReason): string {
 	switch (reason) {
 		case "not-configured":
-			return "no classifier configured (set jev: in switchback.yaml)";
+			return "no classifier configured (set decisionModel: in switchback.yaml)";
 		case "unresolvable":
 			return "configured classifier not found in registry";
 		case "timeout":
@@ -282,7 +305,8 @@ export async function decide(
 		if (
 			previousId &&
 			resolved.entries.some((e) => e.id === previousId && e.availability === "effective") &&
-			!isBlocked(previousId, now, blocked)
+			!isBlocked(previousId, now, blocked) &&
+			!isDisabled(previousId, inputs.disabled)
 		) {
 			return {
 				decision: { kind: "stick", modelId: previousId, reason: "continuation" },
@@ -302,7 +326,11 @@ export async function decide(
 	const pinned = getPinnedModel(modelConfig.id);
 	if (pinned !== undefined) {
 		const pin = resolved.entries.find((e) => e.id === pinned);
-		if (pin?.availability === "effective" && !isBlocked(pinned, now, blocked)) {
+		if (
+			pin?.availability === "effective" &&
+			!isBlocked(pinned, now, blocked) &&
+			!isDisabled(pinned, inputs.disabled)
+		) {
 			return resolveDispatchLevel(
 				{
 					decision:
@@ -330,7 +358,7 @@ export async function decide(
 	// above still outranks it (it is the user's explicit override).
 	const idle = await decideIdleReset({
 		registry,
-		jev: modelConfig.jev,
+		decisionModel: modelConfig.decisionModel,
 		option: modelConfig.idleReset,
 		messages: request.messages,
 		now,
@@ -345,10 +373,11 @@ export async function decide(
 			resolved,
 			skip: undefined,
 			blocked,
+			disabled: inputs.disabled,
 			now,
 			startAfter: undefined,
 			registry,
-			jev: modelConfig.jev,
+			decisionModel: modelConfig.decisionModel,
 			reason: "idle-reset",
 			contextTokens: inputs.contextTokens,
 		});
@@ -381,7 +410,11 @@ export async function decide(
 	// current model is left behind, and the walk continues FORWARD from it.
 	if (current !== undefined) {
 		const cur = resolved.entries.find((e) => e.id === current);
-		if (cur?.availability === "effective" && !isBlocked(current, now, blocked)) {
+		if (
+			cur?.availability === "effective" &&
+			!isBlocked(current, now, blocked) &&
+			!isDisabled(current, inputs.disabled)
+		) {
 			return {
 				decision: { kind: "stick", modelId: current, reason: "session-sticky" },
 				nextState: keepState(current, request.state, request.state?.transientRetries ?? 0),
@@ -396,10 +429,11 @@ export async function decide(
 		resolved,
 		skip: undefined,
 		blocked,
+		disabled: inputs.disabled,
 		now,
 		startAfter: current,
 		registry,
-		jev: modelConfig.jev,
+		decisionModel: modelConfig.decisionModel,
 		contextTokens: inputs.contextTokens,
 	});
 	if (!pick) {
@@ -470,10 +504,11 @@ async function decideRetry(
 			resolved,
 			skip: undefined,
 			blocked,
+			disabled: inputs.disabled,
 			now,
 			startAfter: advanceFrom,
 			registry,
-			jev: modelConfig.jev,
+			decisionModel: modelConfig.decisionModel,
 			contextTokens: inputs.contextTokens,
 		});
 		if (!pick) {
@@ -493,7 +528,7 @@ async function decideRetry(
 		failedId,
 		errorMessage,
 		stopReason,
-		jev: modelConfig.jev,
+		decisionModel: modelConfig.decisionModel,
 		registry,
 		now,
 		blocked,
@@ -521,10 +556,11 @@ async function decideRetry(
 			excluded: retryExcluded,
 			failedScope: classified?.scope,
 			blocked,
+			disabled: inputs.disabled,
 			now,
 			startAfter: advanceFrom,
 			registry,
-			jev: modelConfig.jev,
+			decisionModel: modelConfig.decisionModel,
 			contextTokens: inputs.contextTokens,
 		});
 		recordDecideCrash(failedId, registry, errorMessage, now, null, result.reason, "blind-cycle");
@@ -581,10 +617,11 @@ async function decideRetry(
 			excluded: retryExcluded,
 			failedScope: classified?.scope,
 			blocked,
+			disabled: inputs.disabled,
 			now,
 			startAfter: advanceFrom,
 			registry,
-			jev: modelConfig.jev,
+			decisionModel: modelConfig.decisionModel,
 			contextTokens: inputs.contextTokens,
 		});
 		recordDecideCrash(
@@ -625,10 +662,11 @@ async function decideRetry(
 		excluded: retryExcluded,
 		failedScope: classified?.scope,
 		blocked,
+		disabled: inputs.disabled,
 		now,
 		startAfter: advanceFrom,
 		registry,
-		jev: modelConfig.jev,
+		decisionModel: modelConfig.decisionModel,
 		contextTokens: inputs.contextTokens,
 	});
 	recordDecideCrash(

package/src/simulate.ts

@@ -30,7 +30,7 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import type { Decision } from "./decision.ts";
 import type { NotifyPort, RouterRegistryPort, ThinkingSupportPort } from "./ports.ts";
 import { decide } from "./routing.ts";
-import type { BlockedMap, ModelId, ResolvedSwitchbackConfig } from "./types.ts";
+import type { BlockedMap, DisabledMap, ModelId, ResolvedSwitchbackConfig } from "./types.ts";
 
 export interface SimulateConfig {
 	scenarios: Record<string, string>;
@@ -112,10 +112,17 @@ export async function simulateRetry(
 	scenarioMessage: string,
 	modelConfig: ResolvedSwitchbackConfig,
 	registry: RouterRegistryPort,
-	inputs: { support: ThinkingSupportPort; now?: number; blocked?: BlockedMap; notify?: NotifyPort },
+	inputs: {
+		support: ThinkingSupportPort;
+		now?: number;
+		blocked?: BlockedMap;
+		disabled?: DisabledMap;
+		notify?: NotifyPort;
+	},
 ): Promise<SimulateResult> {
 	const now = inputs.now ?? Date.now();
 	const blocked = inputs.blocked ?? {};
+	const disabled = inputs.disabled ?? {};
 	const firstFallback = modelConfig.fallbacks[0];
 	if (firstFallback === undefined) throw new SimulateError("model config has no fallbacks");
 	const [provider, id] = firstFallback.split("/");
@@ -167,6 +174,7 @@ export async function simulateRetry(
 	const result = await decide("retry", fakeRequest, modelConfig, registry, {
 		now,
 		blocked,
+		disabled,
 		support: inputs.support,
 		simulateErrorMessage: scenarioMessage,
 		...(inputs.notify ? { notify: inputs.notify } : {}),

package/src/state.ts

@@ -20,7 +20,8 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomic } from "./atomic-write.ts";
 import { switchbackStateDir } from "./config.ts";
-import type { BlockedMap, ModelId } from "./types.ts";
+import type { BlockedMap, DisabledMap, ModelId } from "./types.ts";
+export type { DisabledMap };
 
 /** Path to the blocked-until map. The new (account-scoped) location. */
 export function stateFilePath(): string {
@@ -122,6 +123,67 @@ export function unblockModel(modelId: ModelId, path: string = stateFilePath()):
 	writeRaw(path, map);
 }
 
+/**
+ * Manually disabled models, persisted to `<state dir>/disabled.json`.
+ *
+ * This is the user's explicit "never route here" list, set and cleared by the
+ * `/switchback-disable` and `/switchback-enable` commands. Unlike blocks it has
+ * no reset time: a disabled model stays out of every chain until it is enabled
+ * again. It lives in the state dir (not switchback.yaml) so regenerating the
+ * config - for example re-running the switchback-free skill - cannot silently
+ * re-enable a model the user turned off. Values are the epoch-ms disable time,
+ * kept so a status display can say since when.
+ */
+/** Path to the manually-disabled map. */
+export function disabledFilePath(): string {
+	return join(switchbackStateDir(), "disabled.json");
+}
+
+function readDisabledRaw(path: string): DisabledMap {
+	return readRaw(path);
+}
+
+function writeDisabledRaw(path: string, map: DisabledMap): void {
+	writeRaw(path, map);
+}
+
+/** Read the manually-disabled map. Entries never expire; only `enableModel` removes them. */
+export function readDisabledMap(path: string = disabledFilePath()): DisabledMap {
+	return readDisabledRaw(path);
+}
+
+/** Check whether a model was manually disabled. Takes the map: callers read it once per decision. */
+export function isDisabled(modelId: ModelId, map: DisabledMap): boolean {
+	return map[modelId] !== undefined;
+}
+
+/** Disable a model. Returns false when it was already disabled. */
+export function disableModel(modelId: ModelId, now: number = Date.now(), path: string = disabledFilePath()): boolean {
+	const map = readDisabledRaw(path);
+	if (map[modelId] !== undefined) return false;
+	map[modelId] = now;
+	writeDisabledRaw(path, map);
+	return true;
+}
+
+/** Enable a model again. Returns false when it was not disabled. */
+export function enableModel(modelId: ModelId, path: string = disabledFilePath()): boolean {
+	const map = readDisabledRaw(path);
+	if (!(modelId in map)) return false;
+	delete map[modelId];
+	writeDisabledRaw(path, map);
+	return true;
+}
+
+/** Clear the whole list (the `/switchback-enable all` path). Returns how many were removed. */
+export function clearDisabled(path: string = disabledFilePath()): number {
+	const map = readDisabledRaw(path);
+	const count = Object.keys(map).length;
+	if (count === 0) return 0;
+	writeDisabledRaw(path, {});
+	return count;
+}
+
 /**
  * Manually pinned model per virtual model, persisted to
  * `<piConfigDir>/switchback/pin.json`. A pin is the user's explicit "route here"

package/src/systemone.ts

@@ -1,24 +1,26 @@
 /**
- * Minimal System One classifier transport.
+ * System One classifier transport, delegated to the official SDK
+ * (`@typesafe-ai/sdk`): URL building, auth, retries, backoff, abort and body
+ * encoding are the package's; switchback only picks the endpoint, maps the
+ * question/answer types it already shares with pi-ai, and keeps its own
+ * fail-closed answer validation (the SDK types the reply but does not
+ * runtime-validate it).
  *
- * Why this exists instead of importing pi's own transport:
- * `@earendil-works/pi-ai/api/typesafe-system-one.lazy` resolves in this
- * repository (it has its own node_modules) but NOT in a package installed by
- * `pi install`. Pi supplies host packages to extensions by *bare specifier*
- * only, so `import ... from "@earendil-works/pi-ai"` works while any deep
- * subpath fails with "Cannot find module". The type-only imports below are
- * erased at load, so they are safe; a value import is not.
+ * Why not pi's own transport: `@earendil-works/pi-ai/api/typesafe-system-one.lazy`
+ * resolves in this repository but NOT in a package installed by `pi install` -
+ * pi supplies host packages to extensions by *bare specifier* only, so any deep
+ * subpath fails with "Cannot find module". The type-only pi-ai imports below
+ * are erased at load; the SDK is switchback-core's own real dependency and
+ * resolves everywhere.
  *
- * The wire protocol is small and stable (Ollama v0.35+ and TypeSafe both serve
- * it): POST `${baseUrl}/systemone` with `{ model, state, questions }`, read
- * `{ answers }`. `bool` questions travel as the wire-level `noul` type.
- *
- * This is switchback's own adapter for its own opt-in local-classifier
- * endpoint. It deliberately does not reimplement pi's retry/usage-costing
- * layers: a local server needs neither, and classifyError already applies its
- * own timeout and treats a transport error as "no classifier".
+ * URL conventions differ and are bridged in `toSdkBaseUrl`: switchback (and
+ * pi, and OpenAI-compatible servers) carry the version segment in `baseUrl`
+ * (`http://host:11434/v1` + `/systemone`), while the SDK takes an API root and
+ * appends `/v1/systemone` itself.
  */
 
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import type { EntryType, Fetch, Questions } from "@typesafe-ai/sdk";
 import type {
 	ClassifierAnswer,
 	ClassifierApi,
@@ -52,19 +54,11 @@ export function classifierState(text: string): ClassifierContext["state"] {
 	return text.slice(0, 16_000) as unknown as ClassifierContext["state"];
 }
 
-/** Default request timeout. classifyError wraps the call in its own race (see `CLASSIFIER_TIMEOUT_MS`). */
+/** Per-attempt timeout handed to the SDK; classifyError wraps the call in its own race (see `CLASSIFIER_TIMEOUT_MS`). */
 const REQUEST_TIMEOUT_MS = 30_000;
 
-/** The subset of `fetch` this transport uses, injectable for tests. */
-export type FetchLike = (
-	url: string,
-	init: { method: string; headers: Record<string, string>; body: string; signal?: AbortSignal },
-) => Promise<{
-	ok: boolean;
-	status: number;
-	text(): Promise<string>;
-	json(): Promise<unknown>;
-}>;
+/** The fetch implementation the SDK uses; injectable for tests. Alias of the SDK's own `Fetch`. */
+export type FetchLike = Fetch;
 
 export interface SystemOneOptions {
 	/** Bearer token. Local servers ignore it, but the header is always sent. */
@@ -85,6 +79,17 @@ function wireQuestions(questions: Record<string, ClassifierQuestion>): Record<st
 	);
 }
 
+/**
+ * Translate switchback's `baseUrl` (version segment included, pi/OpenAI
+ * compatible convention) into the SDK's API root (version segment appended by
+ * the SDK): `http://host:11434/v1` -> `http://host:11434`, so the SDK's
+ * `/v1/systemone` lands on the same URL the old transport built.
+ */
+function toSdkBaseUrl(baseUrl: string): string {
+	const trimmed = baseUrl.replace(/\/+$/, "");
+	return trimmed.endsWith("/v1") ? trimmed.slice(0, -"/v1".length) : trimmed;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -143,7 +148,6 @@ function parseAnswers(label: string, value: unknown, context: ClassifierContext)
  */
 export function systemOneClassifier(baseUrl: string, options: SystemOneOptions = {}): ProviderClassifier {
 	const label = options.label ?? "System One";
-	const url = `${baseUrl.replace(/\/+$/, "")}/systemone`;
 	return {
 		async classify(
 			model: ClassifierModel<ClassifierApi>,
@@ -161,24 +165,26 @@ export function systemOneClassifier(baseUrl: string, options: SystemOneOptions =
 			try {
 				const apiKey = classifierOptions?.apiKey ?? options.apiKey;
 				if (!apiKey) throw new Error(`No API key for provider: ${model.provider}`);
-				const doFetch = options.fetch ?? (globalThis.fetch as unknown as FetchLike);
-				const signal = classifierOptions?.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS);
-				const response = await doFetch(url, {
-					method: "POST",
-					headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
-					body: JSON.stringify({
-						model: model.id,
-						state: context.state,
-						questions: wireQuestions(context.questions),
-					}),
-					signal,
+				const client = new TypeSafeClient({
+					apiKey,
+					baseURL: toSdkBaseUrl(baseUrl),
+					// Local SystemOne servers (Ollama, sham gateways) do not accept
+					// `Content-Encoding: zstd`, which the SDK defaults to on Node >= 22.15.
+					compression: false,
+					...(options.fetch !== undefined ? { fetch: options.fetch } : {}),
 				});
-				const bodyText = response.ok ? "" : await response.text();
-				if (!response.ok)
-					throw new Error(`${label} returned ${response.status}${bodyText ? `: ${bodyText}` : ""}`);
-				const body: unknown = await response.json();
-				if (!isRecord(body)) throw new Error(`${label} returned an unexpected response`);
-				result.answers = parseAnswers(label, body["answers"], context);
+				const reply = await client.systemOne(
+					{
+						model: model.id,
+						state: context.state as unknown as NonNullable<EntryType>,
+						questions: wireQuestions(context.questions) as unknown as Questions,
+					},
+					{
+						signal: classifierOptions?.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+						timeout: REQUEST_TIMEOUT_MS,
+					},
+				);
+				result.answers = parseAnswers(label, reply.answers, context);
 				return result;
 			} catch (error) {
 				result.stopReason = classifierOptions?.signal?.aborted ? "aborted" : "error";
@@ -198,7 +204,7 @@ export function systemOneClassifier(baseUrl: string, options: SystemOneOptions =
 export interface SystemOneClassifierPortOptions {
 	/** Base URL of the System One endpoint; `undefined` matches "not configured". */
 	baseUrl: string | undefined;
-	/** The provider/id pair `findOfType` resolves - pass the config's `jev` identity. */
+	/** The provider/id pair `findOfType` resolves - pass the config's `decisionModel` identity. */
 	identity: { provider: string; id: string };
 	/** Bearer token for the endpoint. */
 	apiKey?: string;

package/src/thinking.ts

@@ -116,7 +116,7 @@ export interface ThinkingLevelChoice {
 export async function chooseThinkingLevel(opts: {
 	registry: ClassifierPort;
 	support: ThinkingSupportPort;
-	jev: { provider: string; id: string } | undefined;
+	decisionModel: { provider: string; id: string } | undefined;
 	model: HostModel;
 	requested: ThinkingLevelId;
 	context: ThinkingLevelContext;
@@ -144,7 +144,7 @@ export async function chooseThinkingLevel(opts: {
 		failover: opts.context.failover ? "yes" : "no",
 	};
 
-	const call = await callClassifier(opts.registry, opts.jev, {
+	const call = await callClassifier(opts.registry, opts.decisionModel, {
 		state,
 		questions: { level: criteria },
 	});