switchback-core 0.0.0-stage → 2026.10.15

package/package.json

@@ -1,6 +1,51 @@
 {
-  "name": "switchback-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "switchback-core",
+	"version": "2026.10.15",
+	"type": "module",
+	"description": "Host-agnostic core for switchback: fallback routing, error classification ports, block state and configuration.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jr2804/switchback.git",
+		"directory": "packages/core"
+	},
+	"homepage": "https://github.com/jr2804/switchback#readme",
+	"bugs": "https://github.com/jr2804/switchback/issues",
+	"keywords": [
+		"switchback",
+		"fallback",
+		"quota",
+		"routing",
+		"llm"
+	],
+	"files": [
+		"src"
+	],
+	"exports": {
+		".": "./src/index.ts",
+		"./*": "./src/*"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@typesafe-ai/sdk": "^0.7.0",
+		"yaml": "^2.9.1"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^1.1.0",
+		"@earendil-works/pi-coding-agent": "^1.1.0"
+	}
+}

package/src/atomic-write.ts

@@ -0,0 +1,96 @@
+/**
+ * The one atomic file writer behind every switchback store.
+ *
+ * A store is written to a temp file in the destination directory and then
+ * renamed over the destination, so a reader (another pi session, a crashed
+ * run's leftovers) never sees a half-written file.
+ *
+ * Two things the shape has to get right on Windows, where the rename is not
+ * atomic for free:
+ *
+ * - **The temp name is per write, not per file.** A fixed `<path>.tmp` makes
+ *   two writers in one directory (two pi sessions sharing
+ *   `<piConfigDir>/switchback/`) fight over the same staging file: whichever
+ *   renames first moves the *other's* bytes away, and the loser then fails on a
+ *   source that no longer exists.
+ * - **The rename is retried with a real backoff.** While anything else holds
+ *   the destination - an indexer, an antivirus scanner, another process - Windows
+ *   refuses the rename and Node reports `EPERM`. That window is short, so an
+ *   immediate retry loses the race: with two back-to-back attempts the crash
+ *   store failed about one full test run in three (measured 2026-10-09), and the
+ *   retry that existed then slept zero milliseconds between attempts. The budget
+ *   below is 10…320 ms.
+ *
+ * The callers own their own error vocabulary (`CrashError`, `SecretsError`,
+ * `ConfigError`); this module reports a failure as `AtomicWriteError` with the
+ * last filesystem error as its `cause`.
+ */
+
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Rename attempts before a write is declared failed: 6 backoffs, 10…320 ms. */
+const RENAME_ATTEMPTS = 7;
+
+/** First backoff; each further attempt doubles it (10, 20, 40, 80, 160, 320). */
+const RENAME_BACKOFF_MS = 10;
+
+/** Per-process counter, so two writes in one process never share a temp path. */
+let tmpSeq = 0;
+
+/** A store write that could not be completed; `cause` is the last fs error. */
+export class AtomicWriteError extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(`switchback: atomic: ${message}`, options);
+		this.name = "AtomicWriteError";
+	}
+}
+
+/** The staging path the next write to `path` uses. Distinct on every call. */
+export function atomicTmpPath(path: string): string {
+	tmpSeq += 1;
+	return `${path}.${process.pid}.${tmpSeq}.tmp`;
+}
+
+/**
+ * Write `contents` to `path` atomically, creating the parent directory if
+ * needed. Throws {@link AtomicWriteError} - and leaves no temp file behind -
+ * when the rename still fails after the retry budget.
+ */
+export function writeFileAtomic(path: string, contents: string): void {
+	const tmp = atomicTmpPath(path);
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(tmp, contents, "utf8");
+		let lastError: unknown = undefined;
+		for (let attempt = 0; attempt < RENAME_ATTEMPTS; attempt++) {
+			try {
+				renameSync(tmp, path);
+				return;
+			} catch (error) {
+				lastError = error;
+				if (attempt < RENAME_ATTEMPTS - 1) sleep(RENAME_BACKOFF_MS * 2 ** attempt);
+			}
+		}
+		throw new AtomicWriteError(`could not rename ${tmp} onto ${path} after ${RENAME_ATTEMPTS} attempts`, {
+			cause: lastError,
+		});
+	} catch (error) {
+		// Cleanup is best-effort: with a broken parent (a file where a directory
+		// should be) rmSync itself throws ENOTDIR on POSIX, and letting that
+		// escape would mask the write failure this block exists to report.
+		try {
+			rmSync(tmp, { force: true });
+		} catch {
+			// nothing to remove - the staging file was never created
+		}
+		throw error instanceof AtomicWriteError
+			? error
+			: new AtomicWriteError(`could not write ${path}`, { cause: error });
+	}
+}
+
+/** Block the calling thread. Stores are written from sync code, so there is no loop to await. */
+function sleep(ms: number): void {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/src/availability.ts

@@ -0,0 +1,151 @@
+/**
+ * Per-route availability resolution.
+ *
+ * Resolves every entry in the user's configured fallback list against the
+ * current pi model registry. Each entry is classified as:
+ *   - effective                 - the model is in the catalog AND its provider has working credentials.
+ *   - greyed-model-not-in-catalog - the catalog no longer lists this model id.
+ *   - greyed-provider-unavailable  - the provider is not credentialed in the current pi session.
+ *
+ * Resolution is per-call (no caching) so an entry that reappears after the user
+ * fixes their setup becomes effective again with no config edit. Greyed entries
+ * are NEVER written to the account-scoped block map
+ * (`<piConfigDir>/switchback/blocks.json`); they are an availability concern,
+ * not a quota concern.
+ *
+ * The user config is the single source of truth for which entries to consider;
+ * we never silently drop entries. Removing a greyed entry from the config is
+ * an explicit user action.
+ */
+
+import type { AvailabilityPort, HostModel } from "./ports.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("/");
+	if (slash <= 0 || slash === modelId.length - 1) return undefined;
+	return { provider: modelId.slice(0, slash), id: modelId.slice(slash + 1) };
+}
+
+/** The named physical model, when the registry knows it. Generic in the host's model type. */
+export function lookupModel<M extends HostModel>(
+	registry: { find(provider: string, modelId: string): M | undefined },
+	modelId: ModelId,
+): M | undefined {
+	const split = splitModelId(modelId);
+	if (split === undefined) return undefined;
+	return registry.find(split.provider, split.id);
+}
+
+/**
+ * Resolve every configured fallback against the registry. Returns the full list
+ * (effective + greyed) plus counts. Pure apart from the registry read.
+ */
+export function resolveFallbacks(fallbacks: readonly ModelId[], registry: AvailabilityPort): ResolvedFallbacks {
+	const entries: ResolvedEntry[] = [];
+	let effectiveCount = 0;
+	let greyedCount = 0;
+	for (const modelId of fallbacks) {
+		const split = splitModelId(modelId);
+		if (split === undefined) {
+			entries.push({ id: modelId, availability: "greyed-model-not-in-catalog", reason: "invalid-id-format" });
+			greyedCount += 1;
+			continue;
+		}
+		const model = registry.find(split.provider, split.id);
+		if (!model) {
+			entries.push({ id: modelId, availability: "greyed-model-not-in-catalog", reason: "model-not-in-catalog" });
+			greyedCount += 1;
+			continue;
+		}
+		const authStatus = registry.getProviderAuthStatus(split.provider);
+		if (!authStatus.configured) {
+			entries.push({
+				id: modelId,
+				availability: "greyed-provider-unavailable",
+				reason: authStatus.label ?? "no-credentials",
+			});
+			greyedCount += 1;
+			continue;
+		}
+		if (!registry.hasConfiguredAuth(model)) {
+			entries.push({
+				id: modelId,
+				availability: "greyed-provider-unavailable",
+				reason: "model-not-credentialed",
+			});
+			greyedCount += 1;
+			continue;
+		}
+		entries.push({ id: modelId, availability: "effective" });
+		effectiveCount += 1;
+	}
+	return { entries, effectiveCount, greyedCount };
+}
+
+/** Return the list of effective model ids in their configured order. */
+export function effectiveIds(resolved: ResolvedFallbacks): ModelId[] {
+	const out: ModelId[] = [];
+	for (const entry of resolved.entries) {
+		if (entry.availability === "effective") out.push(entry.id);
+	}
+	return out;
+}
+
+/** Return a single greyed entry's reason string, or undefined when not greyed. */
+export function greyedReason(entry: ResolvedEntry | undefined): string | undefined {
+	if (!entry || entry.availability === "effective") return undefined;
+	return entry.reason;
+}
+
+/**
+ * Pick the next effective, non-blocked entry.
+ *
+ * The walk is ordered and forward-moving, which is what makes a chain of failures
+ * advance through the list instead of bouncing between its first two entries:
+ *
+ *   - `startAfter` names the entry to continue past (the model that just failed, or
+ *     the session's current model when it is no longer usable). The walk starts at
+ *     the entry after it in configured order and wraps around once. Without
+ *     `startAfter` the walk starts at the head of the list.
+ *   - `skip` is never returned (normally the same id as `startAfter`; they differ
+ *     only where the router must not pick an id it is not advancing past).
+ *
+ * Degraded mode (returns the most-preferred effective entry even when blocked) is
+ * only allowed when there is exactly one effective entry. With multiple effective
+ * entries, every-blocked returns undefined so the router surfaces an explicit
+ * "exhausted" decision - a failing-provider response is NOT preferable to an
+ * explicit "all blocked" signal when there are still options.
+ */
+export function pickNextEffective(
+	resolved: ResolvedFallbacks,
+	skip: ModelId | undefined,
+	blocked: BlockedMap,
+	now: number,
+	startAfter?: ModelId,
+	excluded?: ReadonlySet<ModelId>,
+	disabled?: DisabledMap,
+): { modelId: ModelId; degraded: boolean } | undefined {
+	const effective = effectiveIds(resolved);
+	if (effective.length === 0) return undefined;
+	const count = effective.length;
+	const start = startAfter === undefined ? 0 : effective.indexOf(startAfter) + 1;
+	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 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
+	// surfaces "exhausted" rather than silently degrading.
+	return undefined;
+}
+
+export type { Availability, ResolvedEntry, ResolvedFallbacks };

package/src/classifier-catalog.ts

@@ -0,0 +1,129 @@
+/**
+ * The classifier providers the config dialogue offers.
+ *
+ * Every entry is derived from pi at runtime: the model registry already knows
+ * which providers exist, what they are called, where they live and which
+ * classifier models each one ships. Switchback keeps **no** provider table of
+ * its own - not a provider id, not a display name, not a base URL, not a model
+ * id. Anything hardcoded here would drift the moment pi-ai's generated catalog
+ * moves, and pi-ai's `dist/providers/data/*.json` is a build artifact, not an
+ * extension point.
+ *
+ * An endpoint pi does not know (a local Ollama server, a self-hosted gateway)
+ * is not part of the offer: the wizard's "Other" escape hatch collects the
+ * provider id and base URL from the user, and switchback registers that
+ * endpoint itself. Once configured it appears in the registry like any other
+ * provider, so later edits are prefilled from the config rather than guessed.
+ */
+
+/** One classifier model a provider ships, as pi's registry reports it. */
+export interface ClassifierModelSummary {
+	/** Model id to write into the config. */
+	id: string;
+	/** Wire API that model speaks (the value for the config's `api` key). */
+	api: string;
+}
+
+/** One provider as pi's registry reports it, reduced to what the wizard needs. */
+export interface ClassifierProviderSource {
+	/** Provider id. */
+	id: string;
+	/** Provider display name. */
+	name: string;
+	/** Provider base URL, when the provider declares one. */
+	baseUrl?: string;
+	/** Classifier models this provider ships (empty when it has none). */
+	classifiers: readonly ClassifierModelSummary[];
+	/** How many chat models pi already has for this provider (clash detection). */
+	chatModels: number;
+}
+
+/** One choice in the decision-model wizard's provider step. */
+export interface ClassifierProviderOption {
+	/** Provider id written to the config. */
+	provider: string;
+	/** Choice label, e.g. "typesafe — TypeSafe". */
+	label: string;
+	/** Provider display name, without the id prefix the label carries. */
+	displayName: string;
+	/**
+	 * Base URL. Present when the provider declares one; absent means "resolve
+	 * from pi's catalog", i.e. the config carries no `baseUrl` key.
+	 */
+	baseUrl?: string;
+	/**
+	 * Wire API to write alongside `baseUrl`, taken from the provider's own
+	 * classifier models. Absent when the provider declares none.
+	 */
+	api?: string;
+	/** Classifier model ids the provider ships, sorted. */
+	models: readonly string[];
+	/**
+	 * True for an endpoint the user named themselves (the wizard's "Other"
+	 * path, or a provider already configured with a direct endpoint). Everything
+	 * pi's catalog reports is false: those are resolved, not registered.
+	 */
+	local: boolean;
+	/** How many chat models pi already has for this provider; 0 when unknown. */
+	chatModels: number;
+}
+
+/**
+ * Build the provider choices from pi's registry view: every provider that ships
+ * at least one classifier model, alphabetically. A provider with no classifier
+ * models is left out rather than offered as a dead end - a direct endpoint is
+ * reachable through the wizard's "Other" choice.
+ */
+export function buildClassifierProviders(source: readonly ClassifierProviderSource[]): ClassifierProviderOption[] {
+	const options: ClassifierProviderOption[] = [];
+	for (const provider of source) {
+		if (provider.classifiers.length === 0) continue;
+		const models = provider.classifiers.map((model) => model.id);
+		const api = provider.classifiers[0]?.api;
+		options.push({
+			provider: provider.id,
+			label: `${provider.id} — ${provider.name}`,
+			displayName: provider.name,
+			...(provider.baseUrl !== undefined ? { baseUrl: provider.baseUrl } : {}),
+			...(api !== undefined ? { api } : {}),
+			models: [...models].sort(),
+			local: false,
+			chatModels: provider.chatModels,
+		});
+	}
+	options.sort((a, b) => a.provider.localeCompare(b.provider));
+	return options;
+}
+
+/**
+ * A short note for a choice's screen title: where the prefilled base URL came
+ * from, so the value is explainable rather than magic.
+ */
+export function classifierBaseUrlNote(option: ClassifierProviderOption): string {
+	if (option.baseUrl === undefined) return "resolved from pi's model catalog (no baseUrl needed)";
+	return `from pi's model catalog: ${option.baseUrl}`;
+}
+
+/**
+ * Whether writing a direct endpoint (`baseUrl`) for this choice would make pi
+ * replace models it already owns.
+ *
+ * pi's `applyExtension` returns `config.models.map(...)` whenever an extension
+ * registers a provider with a model list, so declaring a classifier under a
+ * provider that already serves chat models drops those chat models for the
+ * session. Derived from the registry rather than a list of "reserved" ids:
+ * whatever pi has models for is reserved, by definition.
+ */
+export function directEndpointWouldClobber(option: ClassifierProviderOption): boolean {
+	return option.chatModels > 0;
+}
+
+/**
+ * Build a suggested decision-model name from the provider + model id. Used as
+ * the prefilled default in the last wizard step. Keeps the user's keystrokes
+ * to a Tab + Enter for the common case of accepting the suggestion.
+ */
+export function defaultDecisionModelName(provider: string, modelId: string): string {
+	const cleanedModel = modelId.replace(/[:/]/g, "-").replace(/-latest$/u, "");
+	return `${provider}-${cleanedModel}`;
+}

package/src/classifier-discovery.ts

@@ -0,0 +1,113 @@
+/**
+ * Live discovery of System One-compatible models from a local Ollama server.
+ *
+ * Ollama v0.35+ advertises model capabilities in `/api/tags`, and a model that
+ * can answer the Jev System One prompt is listed with `"decision"` in its
+ * capabilities array. The wizard surfaces those ids in the model step, so a
+ * freshly configured endpoint does not have to wait for a routing failure to
+ * discover the wrong model id.
+ *
+ * llama-server (llama.cpp) has no equivalent endpoint, so the wizard falls back
+ * to "type the model id" for that endpoint. Future work may add a /v1/models
+ * shim there.
+ */
+
+import type { FetchLike } from "./systemone.ts";
+
+/** One Ollama model as `/api/tags` reports it. */
+export interface OllamaModelSummary {
+	/** The model id as Ollama writes it (e.g. `nimble:latest`). */
+	id: string;
+	/** True iff the model lists `"decision"` in its capabilities. */
+	decisionCapable: boolean;
+	/** All advertised capabilities, for diagnostics. */
+	capabilities: readonly string[];
+}
+
+/** The default probe timeout for one `/api/tags` request. */
+export const OLLAMA_DISCOVERY_TIMEOUT_MS = 10_000;
+
+/** Shape we read from `/api/tags`. */
+interface OllamaTagsResponse {
+	models?: Array<{
+		name?: string;
+		model?: string;
+		details?: { capabilities?: string[] };
+		capabilities?: string[];
+	}>;
+}
+
+/**
+ * One `/api/tags` round-trip against a local Ollama server. The caller supplies
+ * the Ollama root (e.g. `http://localhost:11434`), not the System One base URL -
+ * Ollama's `/api/tags` lives at the root regardless of the System One endpoint's
+ * `/v1` prefix.
+ *
+ * Returns the empty array on any error (network failure, non-200, malformed
+ * body) and leaves the error to the caller via the `error` field on the result.
+ * The wizard prefers "show what we know" over a hard failure when discovery is
+ * best-effort.
+ */
+export async function discoverOllamaModels(opts: {
+	baseUrl: string;
+	fetch?: FetchLike;
+	timeoutMs?: number;
+}): Promise<{ models: OllamaModelSummary[]; error?: string }> {
+	const timeoutMs = opts.timeoutMs ?? OLLAMA_DISCOVERY_TIMEOUT_MS;
+	const url = ollamaTagsUrl(opts.baseUrl);
+	const fetchImpl = opts.fetch ?? globalThis.fetch;
+	if (typeof fetchImpl !== "function") {
+		return { models: [], error: "no fetch implementation available" };
+	}
+	try {
+		const response = await fetchImpl(url, {
+			method: "GET",
+			headers: { accept: "application/json" },
+			body: "",
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		if (!response.ok) {
+			return { models: [], error: `ollama /api/tags ${response.status}` };
+		}
+		const json = (await response.json()) as OllamaTagsResponse;
+		const models: OllamaModelSummary[] = [];
+		for (const entry of json.models ?? []) {
+			const id = entry.name ?? entry.model;
+			if (typeof id !== "string" || id.length === 0) continue;
+			const capsRaw = entry.capabilities ?? entry.details?.capabilities ?? [];
+			const capabilities = capsRaw.filter((cap): cap is string => typeof cap === "string");
+			models.push({
+				id,
+				decisionCapable: capabilities.includes("decision"),
+				capabilities,
+			});
+		}
+		return { models };
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		return { models: [], error: message };
+	}
+}
+
+/**
+ * The `/api/tags` URL for a given Ollama root. Accepts roots in either form
+ * (`http://localhost:11434` or `http://localhost:11434/v1`); both work because
+ * `/api/tags` is not under the System One `/v1` prefix.
+ */
+function ollamaTagsUrl(baseUrl: string): string {
+	const trimmed = baseUrl.replace(/\/+$/u, "").replace(/\/v1$/u, "");
+	return `${trimmed}/api/tags`;
+}
+
+/**
+ * Filter the discover result to System One-capable models only, sorted by id.
+ * The wizard uses this to populate the model picker; a model without the
+ * capability is offered under "Other (type the model id)" so they can still be
+ * entered by hand for testing.
+ */
+export function decisionCapableModels(models: readonly OllamaModelSummary[]): string[] {
+	return models
+		.filter((m) => m.decisionCapable)
+		.map((m) => m.id)
+		.sort();
+}