@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/core/recent-models.ts

@@ -0,0 +1,91 @@
+/**
+ * Recently selected target/model refs ("targetId/wireModelId").
+ *
+ * Recents are runtime state, not user configuration, so they live in the state
+ * dir (recent-models.json) and never in settings.yaml. Keeping them out
+ * of the settings file means an Alt+L model pick does not rewrite settings.yaml
+ * just to bump a recency list, which would fire the config watcher in every
+ * other running session. Favorites (modelSelector.favorites) remain in
+ * settings.yaml because they are deliberate user configuration.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "./safe-resource-write.js";
+import { clioStateDir, stateRootRemoved } from "./xdg.js";
+
+export function recentModelsPath(): string {
+	return join(clioStateDir(), "recent-models.json");
+}
+
+let cache: string[] | null = null;
+let cachePath: string | null = null;
+
+function readFromDisk(path: string): string[] | null {
+	if (!existsSync(path)) return null;
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (!Array.isArray(parsed)) return [];
+		const seen = new Set<string>();
+		const out: string[] = [];
+		for (const entry of parsed) {
+			if (typeof entry !== "string") continue;
+			const trimmed = entry.trim();
+			if (trimmed.length === 0 || seen.has(trimmed)) continue;
+			seen.add(trimmed);
+			out.push(trimmed);
+		}
+		return out;
+	} catch {
+		// A corrupted file counts as empty rather than absent so a stale legacy
+		// settings list cannot resurrect over fresher (but unreadable) state.
+		return [];
+	}
+}
+
+function writeToDisk(path: string, refs: ReadonlyArray<string>): void {
+	safeResourceWrite(path, `${JSON.stringify(refs, null, "\t")}\n`, { encoding: "utf8" });
+}
+
+/**
+ * Current recents, newest first, truncated to `limit`. An absent or unreadable
+ * file is an empty list.
+ */
+export function listRecentModels(options?: { limit?: number }): string[] {
+	const path = recentModelsPath();
+	if (cache === null || cachePath !== path) {
+		cache = readFromDisk(path) ?? [];
+		cachePath = path;
+	}
+	const limit = Math.max(1, Math.floor(options?.limit ?? 12));
+	return cache.slice(0, limit);
+}
+
+/** Move `ref` to the front of the recents list and persist to the state dir. */
+export function rememberRecentModel(ref: string, limit: number): string[] {
+	const path = recentModelsPath();
+	// Re-read so refs remembered by other processes since our last load are
+	// merged instead of overwritten. Plain last-writer-wins on the file is
+	// acceptable for a recency list; no lock needed.
+	const base = readFromDisk(path) ?? (cachePath === path && cache !== null ? cache : []);
+	const max = Math.max(1, Math.floor(limit));
+	const next = [ref, ...base.filter((entry) => entry !== ref)].slice(0, max);
+	cache = next;
+	cachePath = path;
+	// An Alt+L model pick in a session outliving `clio-coder uninstall` must not
+	// rebuild the state root around recent-models.json. The in-memory list still
+	// updates so the picker behaves for the rest of the run; see stateRootRemoved().
+	if (stateRootRemoved()) return next;
+	try {
+		writeToDisk(path, next);
+	} catch {
+		// Best-effort, as above.
+	}
+	return next;
+}
+
+/** Test hook: clear the in-process cache after CLIO_* dir overrides change. */
+export function resetRecentModelsCache(): void {
+	cache = null;
+	cachePath = null;
+}

package/src/core/release.ts

@@ -0,0 +1,2 @@
+/** Canonical user-facing maturity warning for the v0.3 experimental line. */
+export const EXPERIMENTAL_RELEASE_WARNING = "EXPERIMENTAL — behavior may break or change without notice.";

package/src/core/residency-protection.ts

@@ -0,0 +1,56 @@
+/**
+ * Wire model ids the operator's configuration references, each tagged with the
+ * role it serves. The residency layer (src/engine/apis/residency.ts) protects
+ * these from eviction by any other Clio stream: a scout worker must never
+ * unload the orchestrator's coder, and no profile may evict another profile's
+ * model. The orchestrator derives the set from its live effective settings;
+ * dispatch copies it onto each WorkerSpec so worker subprocesses protect the
+ * same models.
+ *
+ * The role travels with the id because an eviction message that names only a
+ * model id reads as an anonymous collision. A resident serving `memory` is the
+ * proactive-memory plane; unloading it silently stops task memory rather than
+ * freeing a spare model, and the operator has to be told which plane they are
+ * about to lose.
+ */
+
+import type { ClioSettings } from "./config.js";
+
+/**
+ * Which plane of the operator's configuration references a model:
+ *   - `chat`: the orchestrator model, the one the interactive session talks to.
+ *   - `memory`: the background plane for proactive task memory.
+ *   - `worker`: the worker default or one of the worker profiles.
+ *   - `target-default`: a target's `defaultModel`, the fallback any session picks up.
+ */
+export type ResidencyRole = "chat" | "memory" | "worker" | "target-default";
+
+/** One configured model id and the role its configuration entry serves. */
+export interface ProtectedModelRef {
+	modelId: string;
+	role: ResidencyRole;
+}
+
+/**
+ * Configured model ids with their roles. The first role that claims an id wins,
+ * ordered chat > memory > worker > target-default, so a model serving both the
+ * chat plane and a target default is reported by the more specific role.
+ */
+export function protectedResidencyModels(settings: ClioSettings): ProtectedModelRef[] {
+	const byId = new Map<string, ResidencyRole>();
+	const add = (id: string | null | undefined, role: ResidencyRole): void => {
+		const trimmed = id?.trim();
+		if (!trimmed || byId.has(trimmed)) return;
+		byId.set(trimmed, role);
+	};
+	add(settings.orchestrator.model, "chat");
+	add(settings.background.model, "memory");
+	add(settings.workers.default.model, "worker");
+	for (const profile of Object.values(settings.workers.profiles ?? {})) add(profile.model, "worker");
+	for (const target of settings.targets) add(target.defaultModel, "target-default");
+	return [...byId].map(([modelId, role]) => ({ modelId, role }));
+}
+
+export function protectedResidencyModelIds(settings: ClioSettings): string[] {
+	return protectedResidencyModels(settings).map((ref) => ref.modelId);
+}

package/src/core/resolve-config-value.ts

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+
+const commandResultCache = new Map<string, string | undefined>();
+
+export interface ConfigValueWarning {
+	code: "dynamic-command-in-static-resolution";
+	message: string;
+	command: string;
+}
+
+export interface ResolveConfigValueOptions {
+	env?: NodeJS.ProcessEnv;
+	cwd?: string;
+	onWarning?: (warning: ConfigValueWarning) => void;
+}
+
+function env(options?: ResolveConfigValueOptions): NodeJS.ProcessEnv {
+	return options?.env ?? process.env;
+}
+
+function shellCommand(command: string): string | undefined {
+	const isWindows = process.platform === "win32";
+	const shell = isWindows ? process.env.ComSpec || "cmd.exe" : process.env.SHELL || "/bin/sh";
+	const args = isWindows ? ["/d", "/s", "/c", command] : ["-lc", command];
+	const result = spawnSync(shell, args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+		timeout: 10_000,
+		windowsHide: true,
+	});
+	if (result.error || result.status !== 0) return undefined;
+	const value = result.stdout.trim();
+	return value.length > 0 ? value : undefined;
+}
+
+function executeCommand(commandConfig: string): string | undefined {
+	if (commandResultCache.has(commandConfig)) return commandResultCache.get(commandConfig);
+	const value = shellCommand(commandConfig.slice(1));
+	commandResultCache.set(commandConfig, value);
+	return value;
+}
+
+function warnStaticCommand(config: string, options?: ResolveConfigValueOptions): void {
+	options?.onWarning?.({
+		code: "dynamic-command-in-static-resolution",
+		message: "bang-prefixed config command left literal by static config value resolver",
+		command: config.slice(1),
+	});
+}
+
+export function expandConfigValue(value: string, options?: ResolveConfigValueOptions): string {
+	const sourceEnv = env(options);
+	return value.replace(/\$(\w+)|\$\{([^}]+)\}/g, (match, bare: string | undefined, braced: string | undefined) => {
+		const key = bare ?? braced;
+		if (!key) return match;
+		return sourceEnv[key] ?? "";
+	});
+}
+
+export function expandConfigPath(value: string, options?: ResolveConfigValueOptions): string {
+	const cwd = options?.cwd ?? process.cwd();
+	const expandedEnv = expandConfigValue(value.trim(), options);
+	let expanded = expandedEnv;
+	if (expanded === "~") {
+		expanded = homedir();
+	} else if (expanded.startsWith(`~${sep}`) || expanded.startsWith("~/")) {
+		expanded = `${homedir()}${expanded.slice(1)}`;
+	} else if (expanded.startsWith("~")) {
+		expanded = join(homedir(), expanded.slice(1));
+	}
+	return resolve(cwd, expanded);
+}
+
+function resolveStaticConfigValue(config: string, options?: ResolveConfigValueOptions): string | undefined {
+	if (config.startsWith("!")) warnStaticCommand(config, options);
+	const sourceEnv = env(options);
+	const envValue = sourceEnv[config];
+	if (envValue !== undefined && envValue.length > 0) return envValue;
+	const expanded = expandConfigValue(config, options);
+	return expanded.length > 0 ? expanded : undefined;
+}
+
+export function resolveDynamicConfigValue(config: string, options?: ResolveConfigValueOptions): string | undefined {
+	if (config.startsWith("!")) return executeCommand(config);
+	return resolveStaticConfigValue(config, options);
+}

package/src/core/response-schema.ts

@@ -0,0 +1,279 @@
+export const RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES = 64 * 1024;
+
+/**
+ * The one runtime whose wire dialect carries a JSON-schema response constraint.
+ *
+ * This is a name check rather than a capability check, deliberately. The
+ * constraint travels as `response_format: { type: "json_object", schema }`,
+ * which is llama-server's own spelling and not the openai-completions standard
+ * (`type: "json_schema"` with a nested `json_schema` object). A generic
+ * OpenAI-compatible gateway accepts that request, ignores the unrecognized
+ * `schema` key, and returns HTTP 200 with unconstrained JSON, so widening this
+ * to the api family would convert a clean refusal into a silent
+ * non-enforcement. lmstudio-native declares `structuredOutputs: "json-schema"`
+ * truthfully and is still excluded here, because Clio has no dialect for its
+ * transport. Widen this only together with a dialect for the runtime added.
+ */
+export const RESPONSE_SCHEMA_RUNTIME_ID = "llamacpp";
+
+/** Whether this runtime speaks the dialect above. Transport shape, not capability. */
+export function runtimeSpeaksResponseSchemaDialect(runtime: { id: string; kind: string; apiFamily: string }): boolean {
+	return (
+		runtime.id === RESPONSE_SCHEMA_RUNTIME_ID && runtime.kind === "http" && runtime.apiFamily === "openai-completions"
+	);
+}
+
+/**
+ * Whether a response schema and a tool surface can constrain the same
+ * completion on this runtime.
+ *
+ * llama-server compiles `response_format.schema` into a sampler grammar. A
+ * request that also carries `tools` needs the tool-call grammar over that same
+ * completion, and the server refuses to build both: it answers HTTP 400
+ * `Failed to initialize samplers: failed to parse grammar` before generating a
+ * token. Schema alone succeeds and schema plus one tool fails, so this is a
+ * property of the wire dialect rather than of the target or the model, and no
+ * capability probe reports it. `structuredOutputs: "json-schema"` stays
+ * truthful for the schema-only request it describes.
+ *
+ * A caller that admits runs decides here instead of paying the round trip. A
+ * request carrying both earns the same {@link UnsupportedResponseSchemaError}
+ * a target with no schema support at all would earn, which arms the same
+ * prompt-parser fallback with nothing spent.
+ */
+export function responseSchemaConflictsWithTools(
+	runtime: { id: string; kind: string; apiFamily: string },
+	toolCount: number,
+): boolean {
+	return toolCount > 0 && runtimeSpeaksResponseSchemaDialect(runtime);
+}
+
+/**
+ * Admission-time signal that the resolved worker runtime cannot enforce a
+ * response schema. A caller that treats native enforcement as an optimization
+ * may retry without the schema only after receiving this exact error type.
+ */
+export class UnsupportedResponseSchemaError extends Error {
+	readonly code = "UNSUPPORTED_RESPONSE_SCHEMA";
+
+	constructor(message: string) {
+		super(message);
+		this.name = "UnsupportedResponseSchemaError";
+	}
+}
+
+/**
+ * Whether a run's failure text is the server refusing the request this
+ * dialect produced.
+ *
+ * llama-server compiles `response_format.schema` into a sampler grammar and
+ * rejects the request with HTTP 400 when that grammar cannot be built. The
+ * observed trigger is a request that also carries `tools`: the tool-call
+ * grammar and the schema grammar cannot both constrain one completion, so the
+ * server answers `Failed to initialize samplers: failed to parse grammar`
+ * before generating a token. Nothing in the capability probe predicts it, so
+ * the refusal only arrives mid-run.
+ *
+ * This is the same admission-time judgment `UnsupportedResponseSchemaError`
+ * carries, arriving one round trip later. Callers that treat native
+ * enforcement as an optimization may retry without the schema on either. The
+ * check only means anything on a run that actually carried a schema; callers
+ * must gate it that way rather than let a 400 about anything else match.
+ */
+export function isResponseSchemaRejection(diagnostic: string | null | undefined): boolean {
+	if (!diagnostic) return false;
+	const text = diagnostic.toLowerCase();
+	if (!/\b(?:400|422)\b|invalid_request_error|bad request/.test(text)) return false;
+	return /grammar|json[ _-]?schema|response[ _-]?format/.test(text);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+const SUPPORTED_SCHEMA_KEYS = new Set(["type", "properties", "required", "items", "additionalProperties"]);
+const SUPPORTED_SCHEMA_TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+
+function definesToJson(value: object): boolean {
+	let current: object | null = value;
+	while (current) {
+		if (Object.getOwnPropertyDescriptor(current, "toJSON")) return true;
+		current = Object.getPrototypeOf(current) as object | null;
+	}
+	return false;
+}
+
+function jsonDataError(value: unknown): string | null {
+	type Frame = { value: unknown; path: string; exit?: object };
+	const stack: Frame[] = [{ value, path: "$" }];
+	const active = new Set<object>();
+
+	while (stack.length > 0) {
+		const frame = stack.pop();
+		if (!frame) break;
+		if (frame.exit) {
+			active.delete(frame.exit);
+			continue;
+		}
+
+		const current = frame.value;
+		if (current === null || typeof current === "string" || typeof current === "boolean") continue;
+		if (typeof current === "number") {
+			if (!Number.isFinite(current)) return `${frame.path} must be a finite number`;
+			continue;
+		}
+		if (typeof current !== "object") return `${frame.path} contains a non-JSON value`;
+		if (active.has(current)) return `${frame.path} contains a circular reference`;
+
+		if (!Array.isArray(current) && !isPlainObject(current)) {
+			return `${frame.path} must contain only plain objects and arrays`;
+		}
+		if (definesToJson(current)) {
+			return `${frame.path} must not define toJSON`;
+		}
+
+		active.add(current);
+		stack.push({ value: null, path: frame.path, exit: current });
+
+		if (Array.isArray(current)) {
+			const descriptors = Object.getOwnPropertyDescriptors(current);
+			for (const [key, descriptor] of Object.entries(descriptors)) {
+				if (key === "length" || /^(?:0|[1-9]\d*)$/.test(key)) continue;
+				if (descriptor.enumerable) return `${frame.path}.${key} is not a JSON array index`;
+			}
+			for (let index = current.length - 1; index >= 0; index -= 1) {
+				if (!Object.hasOwn(current, index)) return `${frame.path}[${index}] must not be an array hole`;
+				const descriptor = Object.getOwnPropertyDescriptor(current, String(index));
+				if (!descriptor || !("value" in descriptor)) return `${frame.path}[${index}] must be a data property`;
+				stack.push({ value: descriptor.value, path: `${frame.path}[${index}]` });
+			}
+			continue;
+		}
+
+		for (const symbol of Object.getOwnPropertySymbols(current)) {
+			if (Object.getOwnPropertyDescriptor(current, symbol)?.enumerable) {
+				return `${frame.path} must not contain symbol keys`;
+			}
+		}
+		const descriptors = Object.getOwnPropertyDescriptors(current);
+		const keys = Object.keys(descriptors);
+		for (let index = keys.length - 1; index >= 0; index -= 1) {
+			const key = keys[index];
+			if (key === undefined) continue;
+			const descriptor = descriptors[key];
+			if (!descriptor?.enumerable) continue;
+			if (!("value" in descriptor)) return `${frame.path}.${key} must be a data property`;
+			stack.push({ value: descriptor.value, path: `${frame.path}.${key}` });
+		}
+	}
+
+	return null;
+}
+
+function schemaSyntaxError(value: Record<string, unknown>): string | null {
+	const stack: Array<{ schema: Record<string, unknown>; path: string }> = [{ schema: value, path: "$" }];
+	while (stack.length > 0) {
+		const frame = stack.pop();
+		if (!frame) break;
+		const { schema, path } = frame;
+		for (const key of Object.keys(schema)) {
+			if (!SUPPORTED_SCHEMA_KEYS.has(key)) return `${path}.${key} is not supported by the llama.cpp schema subset`;
+		}
+		if (typeof schema.type !== "string" || !SUPPORTED_SCHEMA_TYPES.has(schema.type)) {
+			return `${path}.type must be one of ${[...SUPPORTED_SCHEMA_TYPES].join(", ")}`;
+		}
+		if (schema.type === "object") {
+			if (schema.items !== undefined) return `${path}.items is only valid for array schemas`;
+			if (schema.properties !== undefined && !isPlainObject(schema.properties)) {
+				return `${path}.properties must be a plain object`;
+			}
+			const properties = (schema.properties ?? {}) as Record<string, unknown>;
+			for (const [name, child] of Object.entries(properties)) {
+				if (!isPlainObject(child)) return `${path}.properties.${name} must be a schema object`;
+				stack.push({ schema: child, path: `${path}.properties.${name}` });
+			}
+			if (schema.required !== undefined) {
+				if (!Array.isArray(schema.required) || !schema.required.every((item) => typeof item === "string")) {
+					return `${path}.required must be an array of strings`;
+				}
+				if (new Set(schema.required).size !== schema.required.length) {
+					return `${path}.required must not contain duplicates`;
+				}
+				for (const name of schema.required) {
+					if (!Object.hasOwn(properties, name)) return `${path}.required names unknown property '${name}'`;
+				}
+			}
+			if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
+				return `${path}.additionalProperties must be a boolean`;
+			}
+			continue;
+		}
+		if (schema.type === "array") {
+			if (!isPlainObject(schema.items)) return `${path}.items must be a schema object`;
+			if (schema.properties !== undefined || schema.required !== undefined || schema.additionalProperties !== undefined) {
+				return `${path} contains object-only keywords on an array schema`;
+			}
+			stack.push({ schema: schema.items, path: `${path}.items` });
+			continue;
+		}
+		if (
+			schema.properties !== undefined ||
+			schema.required !== undefined ||
+			schema.items !== undefined ||
+			schema.additionalProperties !== undefined
+		) {
+			return `${path} contains container keywords on a ${schema.type} schema`;
+		}
+	}
+	return null;
+}
+
+/** Return a user-facing reason when a response schema cannot safely cross the worker JSON boundary. */
+function responseSchemaValidationError(value: unknown, source = "responseSchema"): string | null {
+	try {
+		if (!isPlainObject(value)) return `${source} must be a plain object`;
+		const valueError = jsonDataError(value);
+		if (valueError) return `${source} must be JSON-serializable: ${valueError}`;
+		const syntaxError = schemaSyntaxError(value);
+		if (syntaxError) return `${source} is not an enforceable JSON schema: ${syntaxError}`;
+
+		const serialized = JSON.stringify(value);
+		const bytes = Buffer.byteLength(serialized, "utf8");
+		if (bytes > RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES) {
+			return `${source} must be at most ${RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES} serialized bytes`;
+		}
+		return null;
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		return `${source} could not be safely inspected: ${detail}`;
+	}
+}
+
+export function assertValidResponseSchema(
+	value: unknown,
+	source = "responseSchema",
+): asserts value is Record<string, unknown> {
+	const error = responseSchemaValidationError(value, source);
+	if (error) throw new Error(error);
+}
+
+/** Validate and detach a schema from caller-owned objects before any async dispatch work. */
+export function cloneValidatedResponseSchema(value: unknown, source = "responseSchema"): Record<string, unknown> {
+	assertValidResponseSchema(value, source);
+	try {
+		const serialized = JSON.stringify(value);
+		if (Buffer.byteLength(serialized, "utf8") > RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES) {
+			throw new Error(`${source} changed while being validated`);
+		}
+		const cloned: unknown = JSON.parse(serialized);
+		const cloneError = responseSchemaValidationError(cloned, source);
+		if (cloneError) throw new Error(cloneError);
+		return cloned as Record<string, unknown>;
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith(source)) throw error;
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`${source} could not be canonically cloned: ${detail}`);
+	}
+}

package/src/core/run-overrides.ts

@@ -0,0 +1,77 @@
+/**
+ * Run-scoped option overrides: one-run settings a CLI invocation carries into
+ * deep engine code (context-window override, KV-cache mode, sampling params).
+ *
+ * These ride a single JSON env var, `CLIO_CODER_RUN_OVERRIDES`, instead of one env
+ * var per option. The env var is internal plumbing, not an operator surface:
+ * operators set the CLI flags (`clio-coder run --max-context-tokens`, sampling
+ * flags) or durable settings.yaml keys, and the CLI writes this var for the
+ * scope of the run via {@link withRunOverrides}. Env is the transport, rather
+ * than an in-process store, because dispatched worker subprocesses inherit
+ * `process.env` and must see the same overrides. Keeping it to ONE var means
+ * new run-scoped options extend the typed interface here instead of minting
+ * another `CLIO_CODER_*` variable with its own ad-hoc parse/save/restore code.
+ */
+
+export const RUN_OVERRIDES_ENV = "CLIO_CODER_RUN_OVERRIDES";
+
+export interface RunOverrides {
+	/** One-run context-window override for supported local runtimes. */
+	maxContextTokens?: number;
+	/** One-run KV-cache quantization mode; the consuming runtime validates it. */
+	kvCacheMode?: string;
+	/**
+	 * One-run sampling parameter overrides. Kept as a loose numeric record
+	 * here (undefined fields are dropped at serialization);
+	 * engine/apis/sampling-overrides.ts narrows it to the known keys.
+	 */
+	sampling?: Record<string, number | undefined>;
+}
+
+/** Parse the current overrides. Malformed JSON or fields are dropped, never thrown. */
+export function runOverrides(env: NodeJS.ProcessEnv = process.env): RunOverrides {
+	const raw = env[RUN_OVERRIDES_ENV]?.trim();
+	if (!raw) return {};
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return {};
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+	const record = parsed as Record<string, unknown>;
+	const out: RunOverrides = {};
+	const maxContextTokens = record.maxContextTokens;
+	if (typeof maxContextTokens === "number" && Number.isInteger(maxContextTokens) && maxContextTokens > 0) {
+		out.maxContextTokens = maxContextTokens;
+	}
+	if (typeof record.kvCacheMode === "string" && record.kvCacheMode.length > 0) {
+		out.kvCacheMode = record.kvCacheMode;
+	}
+	const sampling = record.sampling;
+	if (sampling !== null && typeof sampling === "object" && !Array.isArray(sampling)) {
+		const numeric: Record<string, number> = {};
+		for (const [key, value] of Object.entries(sampling as Record<string, unknown>)) {
+			if (typeof value === "number" && Number.isFinite(value)) numeric[key] = value;
+		}
+		if (Object.keys(numeric).length > 0) out.sampling = numeric;
+	}
+	return out;
+}
+
+/**
+ * Apply overrides for the duration of `fn`, merged over any overrides already
+ * in scope, and restore the previous state afterwards even on throw.
+ */
+export async function withRunOverrides<T>(overrides: RunOverrides, fn: () => Promise<T>): Promise<T> {
+	const entries = Object.entries(overrides).filter(([, value]) => value !== undefined);
+	if (entries.length === 0) return fn();
+	const previous = process.env[RUN_OVERRIDES_ENV];
+	process.env[RUN_OVERRIDES_ENV] = JSON.stringify({ ...runOverrides(), ...Object.fromEntries(entries) });
+	try {
+		return await fn();
+	} finally {
+		if (previous === undefined) delete process.env[RUN_OVERRIDES_ENV];
+		else process.env[RUN_OVERRIDES_ENV] = previous;
+	}
+}