@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/engine/apis/lmstudio.ts

@@ -16,7 +16,7 @@ import { emitResidencyMutation, emitResidencyNotice, reconcileResidency, residen
 import { withResidencyLock } from "./residency-lock.js";
 
 interface LmStudioModelMetadata {
-	clio?: {
+	clioCoder?: {
 		targetId: string;
 		runtimeId: string;
 		lifecycle?: "user-managed" | "clio-coder-managed";
@@ -42,8 +42,8 @@ function responseInstanceId(data: unknown): string | undefined {
 	return typeof id === "string" && id.trim().length > 0 ? id.trim() : undefined;
 }
 
-function metadata(model: Model<Api>): NonNullable<LmStudioModelMetadata["clio"]> | undefined {
-	return (model as Model<Api> & LmStudioModelMetadata).clio;
+function metadata(model: Model<Api>): NonNullable<LmStudioModelMetadata["clioCoder"]> | undefined {
+	return (model as Model<Api> & LmStudioModelMetadata).clioCoder;
 }
 
 function targetForModel(model: Model<"openai-completions">): TargetDescriptor | null {

package/src/engine/apis/ollama-native.ts

@@ -32,7 +32,7 @@ import {
 } from "../../domains/providers/index.js";
 import type { LocalModelQuirks, SamplingProfile } from "../../domains/providers/types/local-model-quirks.js";
 import { calculateEngineCost } from "../ai.js";
-import { createGemmaChannelFilter } from "../gemma-channel-filter.js";
+import { createGemmaChannelFilter, usesGemmaChannelMarkers } from "../gemma-channel-filter.js";
 import { createSentinelStripper } from "../strip-tokenizer-sentinels.js";
 import { remainingContextMaxTokens } from "./output-budget.js";
 import { type ResidencyAdapter, reconcileResidency, residencyManagedFor } from "./residency.js";
@@ -43,7 +43,7 @@ import type { EngineApiProvider } from "./types.js";
 const REASONING_CHARS_PER_TOKEN = 4;
 
 interface ClioRuntimeMetadata {
-	clio?: {
+	clioCoder?: {
 		targetId: string;
 		runtimeId: string;
 		/** Present only when settings set the target lifecycle explicitly. */
@@ -55,11 +55,11 @@ interface ClioRuntimeMetadata {
 }
 
 function clioQuirks(model: Model<"ollama-native">): LocalModelQuirks | undefined {
-	return (model as Model<"ollama-native"> & ClioRuntimeMetadata).clio?.quirks;
+	return (model as Model<"ollama-native"> & ClioRuntimeMetadata).clioCoder?.quirks;
 }
 
 function ollamaTargetId(model: Model<"ollama-native">): string {
-	return (model as Model<"ollama-native"> & ClioRuntimeMetadata).clio?.targetId ?? model.provider;
+	return (model as Model<"ollama-native"> & ClioRuntimeMetadata).clioCoder?.targetId ?? model.provider;
 }
 
 /**
@@ -74,7 +74,7 @@ function ollamaTargetId(model: Model<"ollama-native">): string {
 async function reconcileOllamaResidency(model: Model<"ollama-native">, headers: Record<string, string>): Promise<void> {
 	const baseUrl = model.baseUrl;
 	if (!baseUrl) return;
-	const metadata = (model as Model<"ollama-native"> & ClioRuntimeMetadata).clio;
+	const metadata = (model as Model<"ollama-native"> & ClioRuntimeMetadata).clioCoder;
 	const adapter: ResidencyAdapter = {
 		targetKey: residencyTargetKey("ollama-native", baseUrl),
 		targetId: ollamaTargetId(model),
@@ -384,7 +384,7 @@ function runStream(
 			let doneReason: string | undefined;
 			const sentinelStripper = createSentinelStripper();
 			const resolved = resolveModelRuntimeCapabilitiesForModel(model, thinkingLevel);
-			const channelFilter = resolved.family === "gemma-4" ? createGemmaChannelFilter() : null;
+			const channelFilter = usesGemmaChannelMarkers(resolved.modelId) ? createGemmaChannelFilter() : null;
 			const closeActiveThinking = () => {
 				if (!activeThinking) return;
 				stream.push({

package/src/engine/apis/openai-completions.ts

@@ -17,6 +17,11 @@ import {
 } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import type { BackendCompletionTimings, BackendTimingsSource } from "../../core/cache-telemetry.js";
+import {
+	type GatewayRoutingObservation,
+	liteLLMGatewayRoutingFromHeaders,
+	liteLLMRouteFailureMessage,
+} from "../../core/gateway-routing.js";
 import type { ResponseModelIdObservation } from "../../core/response-model-id.js";
 import {
 	type AppliedThinking,
@@ -27,13 +32,13 @@ import {
 import { lmStudioReasoningEffort } from "../../domains/providers/runtimes/common/lmstudio-http.js";
 import type { ThinkingLevel } from "../../domains/providers/types/capability-flags.js";
 import type { LocalModelQuirks, SamplingProfile } from "../../domains/providers/types/local-model-quirks.js";
-import type { LmStudioTargetSettings } from "../../domains/providers/types/target-descriptor.js";
-import { filterGemmaChannelStream } from "../gemma-channel-filter.js";
+import type { LiteLLMTargetSettings, LmStudioTargetSettings } from "../../domains/providers/types/target-descriptor.js";
+import { filterGemmaChannelStream, usesGemmaChannelMarkers } from "../gemma-channel-filter.js";
 import { HarmonyResponseParser } from "../harmony-response.js";
 import { createSentinelStripper, stripTokenizerSentinels } from "../strip-tokenizer-sentinels.js";
 import { ensureLlamaCppResidency } from "./llamacpp-residency.js";
 import { ensureLmStudioResidency } from "./lmstudio.js";
-import { LOCAL_TOOL_TURN_MAX_OUTPUT_TOKENS, remainingContextMaxTokens } from "./output-budget.js";
+import { remainingContextMaxTokens } from "./output-budget.js";
 import { residencyManagedFor } from "./residency.js";
 import { mergeSamplingOverride } from "./sampling-overrides.js";
 import type { EngineApiProvider } from "./types.js";
@@ -42,6 +47,8 @@ declare module "@earendil-works/pi-ai" {
 	interface AssistantMessage {
 		/** Direct observation of model-id presence in an OpenAI-compatible response. */
 		responseModelIdObservation?: ResponseModelIdObservation;
+		/** Route, fallback, retry, and proxy timing facts reported by LiteLLM. */
+		gatewayRouting?: GatewayRoutingObservation;
 		/** Backend-reported prefill and prediction timings when available. */
 		backendTimings?: BackendCompletionTimings;
 	}
@@ -60,7 +67,7 @@ const REASONING_CHARS_PER_TOKEN = 4;
 export { estimateInputTokensFromContext, remainingContextMaxTokens } from "./output-budget.js";
 
 interface ClioRuntimeMetadata {
-	clio?: {
+	clioCoder?: {
 		targetId: string;
 		runtimeId: string;
 		/** Present only when settings set the target lifecycle explicitly. */
@@ -69,17 +76,18 @@ interface ClioRuntimeMetadata {
 		quirks?: LocalModelQuirks;
 		chatTemplateKwargsUnsupported?: boolean;
 		lmstudio?: LmStudioTargetSettings;
+		litellm?: LiteLLMTargetSettings;
 		lmstudioReasoningOptions?: ReadonlyArray<string>;
 		lmstudioDefaultModel?: string;
 	};
 }
 
 function chatTemplateKwargsUnsupported(model: Model<Api>): boolean {
-	return (model as Model<Api> & ClioRuntimeMetadata).clio?.chatTemplateKwargsUnsupported === true;
+	return (model as Model<Api> & ClioRuntimeMetadata).clioCoder?.chatTemplateKwargsUnsupported === true;
 }
 
 function clioQuirks(model: Model<"openai-completions">): LocalModelQuirks | undefined {
-	return (model as Model<"openai-completions"> & ClioRuntimeMetadata).clio?.quirks;
+	return (model as Model<"openai-completions"> & ClioRuntimeMetadata).clioCoder?.quirks;
 }
 
 function pickSamplingProfile(
@@ -101,6 +109,7 @@ interface ResponseModelIdCapture {
 	modelIdDone: boolean;
 	backendTimings: BackendCompletionTimings | null;
 	backendTimingsSource: BackendTimingsSource | null;
+	gatewayRouting: GatewayRoutingObservation | null;
 	buffer: string;
 	decoder: TextDecoder | null;
 }
@@ -138,7 +147,7 @@ function backendCompletionTimings(value: unknown, source: BackendTimingsSource):
 }
 
 function backendTimingsSourceForModel(model: Model<Api>): BackendTimingsSource | null {
-	const metadata = (model as Model<Api> & ClioRuntimeMetadata).clio;
+	const metadata = (model as Model<Api> & ClioRuntimeMetadata).clioCoder;
 	if (model.provider === "llamacpp" && metadata?.runtimeId === "llamacpp") return "llamacpp-timings";
 	if (model.provider === "lmstudio" && metadata?.runtimeId === "lmstudio") return "lmstudio-timings";
 	return null;
@@ -199,7 +208,10 @@ function observeResponseModelIdBytes(
 	if (captureCanStopEarly(capture) || flush) capture.decoder = null;
 }
 
-function captureResponseModelId(response: Response, capture: ResponseModelIdCapture): Response {
+function captureResponseModelId(response: Response, capture: ResponseModelIdCapture, model: Model<Api>): Response {
+	if (runtimeMetadata(model)?.runtimeId === "litellm") {
+		capture.gatewayRouting = liteLLMGatewayRoutingFromHeaders(response.headers);
+	}
 	if (!response.body || !response.headers.get("content-type")?.toLowerCase().includes("text/event-stream")) {
 		return response;
 	}
@@ -234,6 +246,7 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 		modelIdDone: false,
 		backendTimings: null,
 		backendTimingsSource: backendTimingsSourceForModel(model),
+		gatewayRouting: null,
 		buffer: "",
 		decoder: new TextDecoder(),
 	};
@@ -241,7 +254,7 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 		options.fetch ?? ((input, init) => globalThis.fetch(input, init));
 	const capturedOptions = {
 		...options,
-		fetch: async (input, init) => captureResponseModelId(await fetchImpl(input, init), capture),
+		fetch: async (input, init) => captureResponseModelId(await fetchImpl(input, init), capture, model),
 	} as TOptions;
 	const source = sourceFactory(capturedOptions);
 	const annotated = createAssistantMessageEventStream();
@@ -255,9 +268,11 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 					: { state: "not-observed" };
 				if (event.type === "done") {
 					event.message.responseModelIdObservation = observation;
+					if (capture.gatewayRouting !== null) event.message.gatewayRouting = capture.gatewayRouting;
 					if (capture.backendTimings !== null) event.message.backendTimings = capture.backendTimings;
 				} else if (event.type === "error") {
 					event.error.responseModelIdObservation = observation;
+					if (capture.gatewayRouting !== null) event.error.gatewayRouting = capture.gatewayRouting;
 					if (capture.backendTimings !== null) event.error.backendTimings = capture.backendTimings;
 				}
 				annotated.push(event as AssistantMessageEvent);
@@ -271,6 +286,31 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 	return annotated;
 }
 
+/** Make a failed physical gateway route final and useful to an operator. */
+function withLiteLLMRouteFailureAdvice(
+	model: Model<"openai-completions">,
+	source: AssistantMessageEventStream,
+): AssistantMessageEventStream {
+	const metadata = runtimeMetadata(model);
+	if (metadata?.runtimeId !== "litellm") return source;
+	const advised = createAssistantMessageEventStream();
+	(async () => {
+		try {
+			for await (const event of source) {
+				if (event.type === "error") {
+					event.error.errorMessage = liteLLMRouteFailureMessage(event.error.errorMessage, metadata.targetId, model.id);
+				}
+				advised.push(event as AssistantMessageEvent);
+			}
+			advised.end();
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new Error(liteLLMRouteFailureMessage(message, metadata.targetId, model.id));
+		}
+	})();
+	return advised;
+}
+
 function samplingParamsFromProfile(profile: SamplingProfile): Record<string, unknown> {
 	return {
 		...(profile.topP !== undefined ? { top_p: profile.topP } : {}),
@@ -371,8 +411,23 @@ function applyThinkingPayload(
 	resolved: ResolvedModelRuntimeCapabilities,
 	model: Model<Api>,
 ): Record<string, unknown> {
-	if (applied.mechanism === "none") return stripThinkingRequestFields(payload);
-	if (applied.mechanism === "always-on") return payload;
+	if (applied.mechanism === "none") {
+		const next = stripThinkingRequestFields(payload);
+		if (resolved.request.chatTemplateKwargs && !chatTemplateKwargsUnsupported(model)) {
+			const existing = isPlainRecord(next.chat_template_kwargs) ? next.chat_template_kwargs : {};
+			next.chat_template_kwargs = { ...existing, ...resolved.request.chatTemplateKwargs };
+		}
+		return next;
+	}
+	if (applied.mechanism === "always-on") {
+		if (resolved.request.chatTemplateKwargs && !chatTemplateKwargsUnsupported(model)) {
+			const next: Record<string, unknown> = { ...payload };
+			const existing = isPlainRecord(next.chat_template_kwargs) ? next.chat_template_kwargs : {};
+			next.chat_template_kwargs = { ...existing, ...resolved.request.chatTemplateKwargs };
+			return next;
+		}
+		return payload;
+	}
 	const next: Record<string, unknown> = { ...payload };
 	if (
 		resolved.request.reasoningEffort &&
@@ -380,6 +435,17 @@ function applyThinkingPayload(
 	) {
 		next.reasoning_effort = resolved.request.reasoningEffort;
 	}
+	// LiteLLM generic openai/<local model> routes otherwise drop this standard
+	// parameter. Allow only the effort this model/runtime actually resolved;
+	// unknown off controls and unrelated caller parameters gain no allowance.
+	if (
+		resolved.runtimeId === "litellm" &&
+		resolved.request.reasoningEffort &&
+		next.reasoning_effort === resolved.request.reasoningEffort
+	) {
+		const allowed = Array.isArray(next.allowed_openai_params) ? next.allowed_openai_params : [];
+		next.allowed_openai_params = [...new Set([...allowed, "reasoning_effort"])];
+	}
 	if (resolved.request.chatTemplateKwargs && !chatTemplateKwargsUnsupported(model)) {
 		const existing = isPlainRecord(next.chat_template_kwargs) ? next.chat_template_kwargs : {};
 		next.chat_template_kwargs = { ...existing, ...resolved.request.chatTemplateKwargs };
@@ -418,15 +484,15 @@ function applyLmStudioPayload(
 	if (request?.ttlSeconds !== undefined) next.ttl = request.ttlSeconds;
 	if (request?.draftModel !== undefined) next.draft_model = request.draftModel;
 	if (resolved.thinking.mechanism === "none" || resolved.thinking.mechanism === "always-on") return next;
-	const resolvedEffort =
-		resolved.request.reasoningEffort ??
-		lmStudioReasoningEffort(resolved.thinking.effectiveLevel, runtimeMetadata(model)?.lmstudioReasoningOptions);
+	const resolvedEffort = runtimeMetadata(model)?.lmstudioReasoningOptions
+		? lmStudioReasoningEffort(resolved.thinking.effectiveLevel, runtimeMetadata(model)?.lmstudioReasoningOptions)
+		: (resolved.request.reasoningEffort ?? lmStudioReasoningEffort(resolved.thinking.effectiveLevel));
 	switch (request?.reasoning) {
 		case "off":
-			next.reasoning_effort = "none";
+			next.reasoning_effort = lmStudioReasoningEffort("off", runtimeMetadata(model)?.lmstudioReasoningOptions);
 			break;
 		case "on":
-			next.reasoning_effort = "low";
+			next.reasoning_effort = lmStudioReasoningEffort("low", runtimeMetadata(model)?.lmstudioReasoningOptions);
 			break;
 		case "low":
 		case "medium":
@@ -563,21 +629,53 @@ function withRemainingContextBudget<TOptions extends StreamOptions>(
 	context: Context,
 	options: TOptions | undefined,
 ): TOptions {
-	const metadata = runtimeMetadata(model);
-	const localToolOutputLimit =
-		options?.maxTokens === undefined &&
-		(context.tools?.length ?? 0) > 0 &&
-		(model.provider === "llamacpp" || metadata?.runtimeId === "llamacpp")
-			? LOCAL_TOOL_TURN_MAX_OUTPUT_TOKENS
-			: undefined;
 	return {
 		...(options ?? {}),
-		maxTokens: remainingContextMaxTokens(
-			model,
-			context,
-			options,
-			localToolOutputLimit === undefined ? undefined : { maxOutputTokens: localToolOutputLimit },
-		),
+		maxTokens: remainingContextMaxTokens(model, context, options),
+	} as TOptions;
+}
+
+function hasHeader(headers: Readonly<Record<string, unknown>> | undefined, name: string): boolean {
+	if (!headers) return false;
+	const wanted = name.toLowerCase();
+	return Object.keys(headers).some((key) => key.toLowerCase() === wanted);
+}
+
+/**
+ * Apply LiteLLM's request-control headers at the final transport boundary.
+ *
+ * The OpenAI SDK otherwise retries twice below Clio's visible recovery loop and
+ * below LiteLLM's own router, multiplying a single failure into several hidden
+ * attempts. Gateway requests use zero client retries by default; optional
+ * `numRetries` controls the proxy router itself, where any configured attempts
+ * remain observable. A physical-routing gateway should leave it at zero.
+ */
+function withLiteLLMRequestOptions<TOptions extends StreamOptions>(
+	model: Model<"openai-completions">,
+	options: TOptions,
+): TOptions {
+	const metadata = runtimeMetadata(model);
+	if (metadata?.runtimeId !== "litellm") return options;
+	const request = metadata.litellm?.request;
+	const modelHeaders = model.headers as Readonly<Record<string, unknown>> | undefined;
+	const optionHeaders = options.headers as Readonly<Record<string, unknown>> | undefined;
+	const headers: Record<string, string | null> = { ...(options.headers ?? {}) };
+	const setDefault = (name: string, value: string | undefined): void => {
+		if (value === undefined || hasHeader(modelHeaders, name) || hasHeader(optionHeaders, name)) return;
+		headers[name] = value;
+	};
+	setDefault("x-litellm-tags", ["clio-coder", ...(request?.tags ?? [])].join(","));
+	if (request?.sendSessionId !== false) setDefault("x-litellm-session-id", options.sessionId);
+	setDefault("x-litellm-timeout", request?.timeoutSeconds?.toString());
+	setDefault("x-litellm-stream-timeout", request?.streamTimeoutSeconds?.toString());
+	setDefault("x-litellm-num-retries", request?.numRetries?.toString());
+	return {
+		...options,
+		headers,
+		// Never hide duplicate attempts inside the OpenAI SDK beneath Clio's
+		// operator-visible failure. The gateway may still be configured to retry,
+		// but physical-routing deployments should keep that policy at zero too.
+		maxRetries: options.maxRetries ?? 0,
 	} as TOptions;
 }
 
@@ -593,8 +691,8 @@ function hasEmptyArguments(args: Record<string, unknown>): boolean {
 	return Object.keys(args).length === 0;
 }
 
-function runtimeMetadata(model: Model<Api>): NonNullable<ClioRuntimeMetadata["clio"]> | undefined {
-	return (model as Model<Api> & ClioRuntimeMetadata).clio;
+function runtimeMetadata(model: Model<Api>): NonNullable<ClioRuntimeMetadata["clioCoder"]> | undefined {
+	return (model as Model<Api> & ClioRuntimeMetadata).clioCoder;
 }
 
 function emptyErrorMessage(model: Model<"openai-completions">, message: string): AssistantMessage {
@@ -918,15 +1016,18 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 		const resolved = resolvedCapabilitiesForModel(model, defaultLevel);
 		const effectiveContext = stripsThinking(resolved) ? stripThinkingFromContext(context) : context;
 		const withSamplers = withSamplingOverrides(model, options, resolved);
+		const withGatewayOptions = withLiteLLMRequestOptions(
+			model,
+			withRemainingContextBudget(model, effectiveContext, withSamplers),
+		);
 		return guardMalformedToolCalls(
 			withReasoningTokenEstimate(
 				stripSentinelsFromStream(
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
-							withResponseModelIdCapture(
+							withLiteLLMRouteFailureAdvice(
 								model,
-								withRemainingContextBudget(model, effectiveContext, withSamplers),
-								(capturedOptions) =>
+								withResponseModelIdCapture(model, withGatewayOptions, (capturedOptions) =>
 									withLocalResidency(
 										model,
 										{
@@ -935,8 +1036,9 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 										},
 										(requestModel) => piOpenAICompletions.stream(requestModel, effectiveContext, capturedOptions),
 									),
+								),
 							),
-							resolved.family === "gemma-4",
+							usesGemmaChannelMarkers(resolved.modelId),
 						),
 						resolved,
 					),
@@ -951,15 +1053,18 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 		const resolved = resolvedCapabilitiesForModel(model, thinkingLevelFromSimple(options));
 		const effectiveContext = stripsThinking(resolved) ? stripThinkingFromContext(context) : context;
 		const withSamplers = withSamplingOverrides(model, options, resolved);
+		const withGatewayOptions = withLiteLLMRequestOptions(
+			model,
+			withRemainingContextBudget(model, effectiveContext, withSamplers),
+		);
 		return guardMalformedToolCalls(
 			withReasoningTokenEstimate(
 				stripSentinelsFromStream(
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
-							withResponseModelIdCapture(
+							withLiteLLMRouteFailureAdvice(
 								model,
-								withRemainingContextBudget(model, effectiveContext, withSamplers),
-								(capturedOptions) =>
+								withResponseModelIdCapture(model, withGatewayOptions, (capturedOptions) =>
 									withLocalResidency(
 										model,
 										{
@@ -968,8 +1073,9 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 										},
 										(requestModel) => piOpenAICompletions.streamSimple(requestModel, effectiveContext, capturedOptions),
 									),
+								),
 							),
-							resolved.family === "gemma-4",
+							usesGemmaChannelMarkers(resolved.modelId),
 						),
 						resolved,
 					),

package/src/engine/apis/output-budget.ts

@@ -13,7 +13,7 @@ const DEFAULT_MAX_OUTPUT_TOKENS = CLIO_MIN_MAX_OUTPUT_TOKENS;
 
 /**
  * Process-wide default output budget requested per turn, sourced from
- * settings.defaults.maxTokens at session start (see
+ * chat.maxOutputTokens at session start (see
  * {@link setGlobalDefaultMaxOutputTokens}). 0 means unset: callers fall back to
  * the model's advertised cap as before.
  */
@@ -30,19 +30,6 @@ export function setGlobalDefaultMaxOutputTokens(value: number): void {
 	globalDefaultMaxOutputTokens = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }
 
-/**
- * Output ceiling applied to a llama.cpp tool-bearing turn when the caller did
- * not request an explicit limit. It bounds a genuinely runaway local
- * generation without muzzling real work: a single tool call that writes a
- * sizable file (a full HTML page, a multi-function source module) needs far
- * more than a few thousand tokens of argument, and the tool-call argument
- * counts against this same response budget. Narration loops where a local
- * model keeps saying it will call a tool without emitting one are caught
- * separately by assessToolProseLoop, so this number only has to be large
- * enough to let legitimate large outputs through.
- */
-export const LOCAL_TOOL_TURN_MAX_OUTPUT_TOKENS = CLIO_MIN_MAX_OUTPUT_TOKENS;
-
 /**
  * Tokens a preflight context check should hold back for the response: the
  * smaller of the model's advertised output limit and the default output
@@ -84,15 +71,18 @@ export function remainingContextMaxTokens(
 	const modelLimit = model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY;
 	// Precedence for the requested ceiling when the caller gave no explicit
 	// maxTokens: a more-specific tool-turn limit, then the global default, then
-	// the model's advertised cap. Math.min below clamps the result down to the
-	// model cap and the remaining context budget regardless, so the global
-	// default never lets a small model overshoot what it supports.
+	// the model's advertised cap. A model that advertises no cap uses the product
+	// floor instead of requesting its entire remaining context window. Math.min
+	// below clamps the result down to every known boundary, so frontier providers
+	// with a known cap never receive a larger max_tokens value.
 	const defaultLimit =
 		limits?.maxOutputTokens !== undefined && limits.maxOutputTokens > 0
 			? limits.maxOutputTokens
 			: globalDefaultMaxOutputTokens > 0
 				? globalDefaultMaxOutputTokens
-				: modelLimit;
+				: model.maxTokens > 0
+					? modelLimit
+					: DEFAULT_MAX_OUTPUT_TOKENS;
 	const requested = options?.maxTokens ?? defaultLimit;
 	const resolved = Math.min(requested, modelLimit, budget);
 	return Number.isFinite(resolved) ? resolved : DEFAULT_MAX_OUTPUT_TOKENS;

package/src/engine/apis/residency.ts

@@ -26,8 +26,8 @@
  *
  * The reconciler is best-effort and non-blocking. A slow or unreachable
  * server, or a malformed resident listing, degrades to observe-only and never
- * crashes a turn. `CLIO_CODER_RESIDENCY=observe` and an explicit target
- * `lifecycle: user-managed` both force observe-only on every runtime path.
+ * crashes a turn. An explicit target `lifecycle: user-managed` forces
+ * observe-only on every runtime path.
  * Every collision or stress case emits a notice over the event bus instead of
  * a thrown error. One reconcile decision holds per (target, model) within a
  * TTL, and mutations for a target are serialized across processes through a
@@ -280,7 +280,7 @@ function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): Resid
 		facts,
 		"swap",
 		"warning",
-		`swapping resident '${entry.modelId}' for requested '${facts.keepModelId}' on '${facts.targetId}' (Clio did not load it; recorded transition instead of a silent unload; set CLIO_CODER_RESIDENCY=observe or lifecycle: user-managed to forbid swaps).`,
+		`swapping resident '${entry.modelId}' for requested '${facts.keepModelId}' on '${facts.targetId}' (Clio did not load it; recorded transition instead of a silent unload; set lifecycle: user-managed to forbid swaps).`,
 		{
 			...(entry.sizeVramBytes !== undefined ? { freedVramBytes: entry.sizeVramBytes } : {}),
 			swappedOut: entry.modelId,
@@ -775,29 +775,10 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 }
 
 /**
- * The env-level residency opt-out. Clio manages residency for every
- * manageable runtime by default; `CLIO_CODER_RESIDENCY=observe` (or off/0/false/
- * user) flips the whole process to observe-only. Per-target opt-out goes
- * through {@link residencyManagedFor}.
+ * Residency policy for one target. An absent lifecycle means the operator made
+ * no choice and Clio manages by default; runtime synthesis only sets the
+ * metadata field when settings carry an explicit value.
  */
-export function residencyManaged(env: NodeJS.ProcessEnv = process.env): boolean {
-	const opt = (env.CLIO_CODER_RESIDENCY ?? "").trim().toLowerCase();
-	if (opt === "observe" || opt === "off" || opt === "0" || opt === "false" || opt === "user" || opt === "user-managed") {
-		return false;
-	}
-	return true;
-}
-
-/**
- * Combined residency opt-out for one target: the process-wide env switch plus
- * the target's explicit `lifecycle: user-managed`. An absent lifecycle means
- * the operator made no choice, and Clio manages by default; runtime synthesis
- * only sets the metadata field when settings carry an explicit value.
- */
-export function residencyManagedFor(
-	lifecycle: "user-managed" | "clio-coder-managed" | undefined,
-	env: NodeJS.ProcessEnv = process.env,
-): boolean {
-	if (lifecycle === "user-managed") return false;
-	return residencyManaged(env);
+export function residencyManagedFor(lifecycle: "user-managed" | "clio-coder-managed" | undefined): boolean {
+	return lifecycle !== "user-managed";
 }