@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/providers/models/local-models/clio-local-coding-targets.yaml

@@ -1,6 +1,7 @@
 # Sources:
 # https://huggingface.co/Qwen/Qwen3.6-35B-A3B
 # https://huggingface.co/Qwen/Qwen3.6-27B
+# https://huggingface.co/Qwen/Qwen3.8-27B
 # https://huggingface.co/google/gemma-4-26B-A4B
 # https://huggingface.co/LilaRest/gemma-4-31B-it-NVFP4-turbo
 # https://huggingface.co/Jackrong/Gemopus-4-31B-it-GGUF
@@ -17,13 +18,12 @@
 #
 # Thinking semantics for these local families: the chain-of-thought is emitted
 # by the model's chat template (Qwen-style <think> blocks, Gemma 4 thinking
-# template, Nemotron reasoning template). LM Studio's SDK and llama.cpp's
-# OpenAI-compatible surface do not expose a reliable "no thinking" flag, so
-# Clio cannot disable template-driven reasoning at the API layer. With
-# `--thinking off` Clio simply does not request reasoning; if the model emits
-# it anyway, the chain-of-thought is captured into a ThinkingContent block,
-# counted as reasoning tokens (separate from output tokens) on the receipt
-# and TUI footer, and surfaced to the user truthfully rather than hidden.
+# template, Nemotron reasoning template). LM Studio's OpenAI-compatible HTTP
+# surface uses reasoning_effort as its sole thinking control; llama.cpp support
+# depends on the active template and reasoning parser. If a model emits thought
+# despite the requested level, Clio captures it in a ThinkingContent block,
+# counts it separately on receipts and the TUI footer, and surfaces it rather
+# than hiding what the server returned.
 - family: openai-gpt-oss
   matchPatterns:
     - openai/gpt-oss
@@ -164,8 +164,8 @@
       "24gb": "Use a 4-bit quant with reduced load context for evaluation. Prefer the 32GB tier for sustained Clio writes."
       "32gb": "Primary strong local model for multimodal main-agent work. Keep openai-compat available for tool-call fallback."
     runtimePreference:
-      lmstudioNative: "Use only when the target's server lifecycle is Clio-managed or the model is already loaded at the requested context."
-      openaiCompat: "Preferred fallback for LM Studio gateway tool-call extraction."
+      lmstudio: "Use LM Studio per-model load settings unless this target carries explicit lmstudio.load overrides."
+      openaiCompat: "Use for a generic gateway that fronts the same OpenAI-compatible chat surface."
       llamaCpp: "OpenAI-compatible chat completions with --jinja."
     llamaCpp:
       ctxSize: 819200
@@ -184,7 +184,7 @@
         Reasoning is template-driven; thinking blocks emit through the qwen
         chat template. Preserve thinking across coding-task turns when the
         chain matters; otherwise let the budget cap output growth.
-    serving: "Use qwen3_coder tool parsing when served through OpenAI-compatible HTTP. LM Studio native uses SDK rawTools, but openai-compat remains the fallback for template-specific tool extraction issues."
+    serving: "Use qwen3_coder tool parsing when served through OpenAI-compatible HTTP. LM Studio uses the same OpenAI-compatible tool surface."
 
 - family: qwen3.6-35b-a3b
   matchPatterns:
@@ -224,7 +224,7 @@
     gpuTiers:
       "32gb": "Main-agent candidate on 32GB targets when Nemotron Omni is unavailable or tool behavior is better for text-only work."
     runtimePreference:
-      lmstudioNative: "Usable for text and vision when loaded in LM Studio. Keep openai-compat available for tool fallback."
+      lmstudio: "Usable for text and vision through LM Studio's OpenAI-compatible chat surface."
       openaiCompat: "Preferred local gateway path for tool-call stress tests."
       llamaCpp: "OpenAI-compatible chat completions with --jinja. Local llama.cpp profile emits reasoning_content without a separate --reasoning flag."
     llamaCpp:
@@ -346,7 +346,7 @@
     gpuTiers:
       "32gb": "Fits at f16 KV with parallel=1 and ctx=262144 (Q4_K_XL weights ~19.5 GB plus ~32 GB KV)."
     runtimePreference:
-      lmstudioNative: "Primary path; standard <think> tagging works correctly with the SDK classifier."
+      lmstudio: "Primary LM Studio path through OpenAI-compatible chat and native REST model management."
       openaiCompat: "Verified parity for tool calls; reasoning_content surfaces and completion_tokens_details.reasoning_tokens is reported."
     thinking:
       mechanism: budget-tokens
@@ -360,6 +360,91 @@
         turns when the workflow is iterative; the budget caps runaway chains.
     serving: "Official Qwen card recommends max output 32768 tokens for standard queries (81920 only for math/code competitions). Coding sampler is the precise variant; preserve thinking blocks across turns for iterative workflows."
 
+- family: qwen3.8-27b
+  matchPatterns:
+    - qwen3.8-27b
+    - qwen3_8-27b
+    - qwen3-8-27b
+  capabilities:
+    chat: true
+    tools: true
+    toolCallFormat: qwen
+    reasoning: true
+    thinkingFormat: qwen-chat-template
+    structuredOutputs: json-schema
+    vision: true
+    audio: false
+    embeddings: false
+    rerank: false
+    fim: false
+    contextWindow: 262144
+    maxTokens: 131072
+  quirks:
+    kvCache:
+      kQuant: q8_0
+      vQuant: q8_0
+    sampling:
+      thinking:
+        temperature: 1.0
+        topP: 0.95
+        topK: 20
+        minP: 0.0
+        presencePenalty: 0.0
+        repetitionPenalty: 1.0
+        maxTokens: 32768
+      instruct:
+        temperature: 0.7
+        topP: 0.80
+        topK: 20
+        minP: 0.0
+        presencePenalty: 1.5
+        repetitionPenalty: 1.0
+        maxTokens: 32768
+    gpuTiers:
+      "24gb-rocm": "24 GB ROCm class: IQ4_NL uses about 17.3 GB and UD-Q4_K_XL uses about 19.5 GB. Serve ctx=131072 with q8_0/q8_0 KV, parallel=2, and draft-mtp speculative decoding."
+      "32gb-cuda": "32 GB CUDA class: Q6_K uses about 23.8 GB. Serve ctx=131072 with parallel=4 because the full 262144-token context is VRAM-bound."
+      "128gb-unified-vulkan": "128 GB unified-memory Vulkan class: IQ4_NL uses about 17.3 GB and fits ctx=262144 with parallel=4. Vulkan backends show much slower prefill than ROCm/CUDA on this family; prefer ROCm where available."
+    runtimePreference:
+      llamaCpp: "Primary verified path. OpenAI-compatible chat completions with --jinja, --reasoning on, --reasoning-effort medium as server defaults; reasoning_content and tool_calls both confirmed to parse correctly. A request can override to off with chat_template_kwargs.enable_thinking:false, or to a different active level with reasoning_effort in {low, medium, xhigh} (never minimal/high/max on the wire; the stock template raises a fatal jinja exception on those and Clio's landed capability resolver already clamps to this set)."
+      lmstudioOpenaiCompat: "Clio sends reasoning_effort over LM Studio's OpenAI-compatible HTTP port and omits chat_template_kwargs because LM Studio does not use that field for this model. With no override, LM Studio defaults this model to thinking off, unlike raw llama.cpp's template default of thinking on/xhigh. reasoning_effort:'none' explicitly disables it."
+      lmstudioNative: "Clio's LM Studio runtime uses the OpenAI-compatible HTTP chat adapter with native REST model discovery and residency management."
+    llamaCpp:
+      ctxSize: 131072
+      cacheTypeK: q8_0
+      cacheTypeV: q8_0
+      flashAttn: true
+      nGpuLayers: 99
+      parallel: 2
+      batchSize: 1024
+      ubatchSize: 256
+      mmproj: true
+      reasoning: "on"
+      reasoningEffort: medium
+      specType: draft-mtp
+      specDraftNMax: 1
+    thinking:
+      mechanism: effort-levels
+      effortByLevel:
+        low: low
+        medium: medium
+        high: xhigh
+        xhigh: xhigh
+      guidance: |
+        Official Qwen3.8-27B chat template (chat_template.jinja) validates
+        reasoning_effort against exactly {xhigh, medium, low} and raises a
+        fatal jinja exception (hard 500, not a graceful fallback) on anything
+        else, including minimal/high/max. The 27B card gives no /think or
+        /no_think soft switch for this model; unlike Qwen3, that idiom has no
+        effect here. Off must go through chat_template_kwargs.enable_thinking:
+        false, never through reasoning_effort. preserve_thinking should stay
+        on for an agentic harness (the template's own recommendation for
+        agent scenarios; improves KV cache reuse). llama.cpp's own
+        reasoning_effort:"none" also disables reasoning at the server layer
+        and is a separate mechanism from the template's enable_thinking flag;
+        both were verified independently on llama.cpp and on LM Studio's HTTP
+        port.
+    serving: "Qwen3.8-27B (unsloth/Qwen3.8-27B-GGUF), hybrid qwen3_5 architecture: 3 linear-attention (Gated DeltaNet) layers per 1 full-attention layer, so only 16 of 64 layers hold a conventional KV cache. Native ctx 262144, extensible to 1M via YaRN (out of scope for the hardware classes above; leave rope at default). Tool calls use an XML <tool_call><function=...> form in the stock template; llama.cpp's qwen3_coder parser converts this to standard tool_calls JSON, verified live on ROCm, CUDA, and Vulkan backends. Only messages[0] may be a system message and only system/user/assistant/tool roles are accepted; a second system message or a developer role raises a template error."
+
 - family: gemma-4-31b-it-nvfp4-turbo
   matchPatterns:
     - gemma-4-31b-it-nvfp4-turbo
@@ -404,25 +489,23 @@
     leakageNote: |
       LM Studio's gemma4 chat template emits chain-of-thought as plain text
       bracketed by literal '<|channel>thought\n' and '<channel|>' markers
-      rather than reasoningType=reasoning fragments. Clio's lmstudio-native
-      adapter buffers and re-classifies these regions into ThinkingContent
-      so the markers do not leak into the visible TUI text and reasoning
-      tokens are accounted via the chars/4 estimator.
+      rather than structured reasoning fragments. The OpenAI-compatible path
+      currently exposes those markers as the server streams them; filtering
+      this family remains a follow-up.
     gpuTiers:
       "48gb": "Fits at f16 KV when parallel=1 and ctx=122880; drop to q8_0 KV at parallel=4."
       "80gb": "Comfortable at f16 KV with parallel=1 and ctx=122880."
     runtimePreference:
-      lmstudioNative: "Verified path. Pin parallel=1 in the LM Studio per-model preset to give a single agent the full 122880 context."
-      openaiCompat: "Fallback path; the openai-compat surface does not expose the channel-marker classifier so visible text shows the raw markers."
+      lmstudio: "Pin parallel=1 in the LM Studio per-model preset to give a single agent the full 122880 context."
+      openaiCompat: "LM Studio chat uses this surface; visible text may contain the raw channel markers."
     thinking:
       mechanism: on-off
       guidance: |
         Gemma 4 chat template exposes thinking only as on or off; intermediate
         levels coerce to on. NVFP4 quantization can corrupt JSON tool-call
         output under aggressive sampling, so the instruct profile pins
-        temperature at 0.7. The lmstudio-native adapter re-classifies the
-        channel-marker thought region into ThinkingContent so markers do not
-        leak into visible text.
+        temperature at 0.7. LM Studio's OpenAI-compatible stream currently
+        exposes channel markers when the server does not classify them.
     serving: "LilaRest publishes no per-model sampler; values inherit the gemma family default per the official Google Gemma 4 31B card. KV cache budget at f16, ctx=122880 is roughly 57 GB on top of ~21 GB of NVFP4 weights."
 
 # The qat/UD-Q4_K_XL/MTP build is the long-context llama.cpp gemma profile and is a
@@ -547,15 +630,15 @@
       "48gb": "Fits at f16 KV with parallel=1; q8_0 KV recommended at parallel=4."
       "80gb": "Comfortable at f16 KV with parallel=1 and ctx=122880."
     runtimePreference:
-      lmstudioNative: "Verified path. Channel-marker handler in clio's adapter recovers reasoning tokens that the SDK classifier drops."
+      lmstudio: "LM Studio's OpenAI-compatible stream may expose this family's channel markers as visible text."
       openaiCompat: "Fallback; reasoning_content is absent from the openai-compat reasoning probe for this family."
     thinking:
       mechanism: always-on
       guidance: |
         Distilled traces emit unconditionally. The thinking level setting is
         ignored at the API surface; chain-of-thought arrives whether or not
-        Clio asks for it. Reasoning tokens are accounted via the channel-marker
-        re-classifier in lmstudio-native.
+        Clio asks for it. Channel-marker filtering remains a follow-up for the
+        OpenAI-compatible LM Studio path.
     serving: "Distilled from Claude 4.6 Opus reasoning traces onto Google Gemma 4 31B; sampler matches the gemopus card values."
 
 - family: qwopus3.6-27b-v1-preview
@@ -598,7 +681,7 @@
     gpuTiers:
       "32gb": "Fits at f16 KV with parallel=1 and ctx=262144 thanks to the Q4_K_M weights (~16.5 GB)."
     runtimePreference:
-      lmstudioNative: "Primary path; thinking is emitted via standard <think> tags so the SDK classifier accounts reasoning correctly."
+      lmstudio: "Primary LM Studio path; thinking is read from the OpenAI-compatible reasoning stream."
       openaiCompat: "Verified for tool-call extraction parity; reasoning_content surfaces."
     thinking:
       mechanism: budget-tokens
@@ -729,8 +812,8 @@
         presencePenalty: 1.5
         maxTokens: 32768
     runtimePreference:
-      llamaCpp: "Mini router serves it with --jinja and enable_thinking false; coder sampler temperature 0.2, top_p 0.9, top_k 20."
-      lmstudioNative: "Dense 27B Coder-MTP; the creator's template ships thinking-off, and no per-request field re-enables it."
+      llamaCpp: "A local llama.cpp router serves it with --jinja and enable_thinking false; coder sampler temperature 0.2, top_p 0.9, top_k 20."
+      lmstudio: "Dense 27B Coder-MTP; configure MTP in LM Studio's per-model load settings."
     thinking:
       mechanism: none
       guidance: |
@@ -766,7 +849,7 @@
         repeatPenalty: 1.05
         maxTokens: 32768
     runtimePreference:
-      llamaCpp: "Mini router serves it with --jinja and enable_thinking false; coder sampler temperature 0.2, top_p 0.9, top_k 20."
+      llamaCpp: "A local llama.cpp router serves it with --jinja and enable_thinking false; coder sampler temperature 0.2, top_p 0.9, top_k 20."
     thinking:
       mechanism: none
       guidance: |
@@ -812,8 +895,8 @@
     gpuTiers:
       "32gb": "Main-agent candidate for 32 GB and larger local systems when Gemma behavior is preferred."
     runtimePreference:
-      lmstudioNative: "Use for already-loaded LM Studio sessions and multimodal checks."
-      openaiCompat: "Preferred fallback when SDK rawTools do not match the template."
+      lmstudio: "Use for already-loaded LM Studio sessions and multimodal checks."
+      openaiCompat: "LM Studio chat uses this OpenAI-compatible surface."
       llamaCpp: "OpenAI-compatible chat completions with --jinja, --reasoning on, and the matching mmproj."
     llamaCpp:
       ctxSize: 262144
@@ -862,8 +945,8 @@
     gpuTiers:
       "32gb": "Preferred local worker model when a text-only worker is enough."
     runtimePreference:
-      lmstudioNative: "Use when LM Studio SDK tool extraction is verified for the loaded template."
-      openaiCompat: "Preferred fallback for LM Studio gateway tool calls."
+      lmstudio: "Use when LM Studio's OpenAI-compatible tool extraction is verified for the loaded template."
+      openaiCompat: "Use for a generic gateway that fronts the same OpenAI-compatible chat surface."
       anthropicCompat: "Do not select for the current llama.cpp target profile; /v1/messages returned 404 while /v1/models and OpenAI-compatible chat worked."
       llamaCpp: "OpenAI-compatible chat completions with --jinja. Recommended local profile disables thinking in chat_template_kwargs."
     llamaCpp:
@@ -922,8 +1005,8 @@
     gpuTiers:
       "32gb": "Distilled Opus-style reasoning at Qwen3.5 35B A3B scale. Use as a strong local main agent when GPU room is available."
     runtimePreference:
-      lmstudioNative: "Verified usable on LM Studio when loaded with the Qwen-style preset."
-      openaiCompat: "Preferred fallback when SDK rawTools yield empty arguments for the distilled template."
+      lmstudio: "Verified usable on LM Studio when loaded with the Qwen-style preset."
+      openaiCompat: "LM Studio chat uses this OpenAI-compatible surface."
       llamaCpp: "OpenAI-compatible chat completions with --jinja. Match qwen3 reasoning parser flags upstream."
     thinking:
       mechanism: budget-tokens
@@ -973,8 +1056,8 @@
     gpuTiers:
       "16gb": "Use this as the local 16GB emulation target. It keeps the output cap below the 32GB-class MoE defaults."
     runtimePreference:
-      lmstudioNative: "Primary local laptop path. Verified through LM Studio /api/v1/models with 262144 loaded context, flash attention, GPU KV offload, and trained_for_tool_use."
-      openaiCompat: "Verified through the LM Studio gateway for read and artifact tool calls; use when the native SDK produces thinking-only length stops or malformed tools."
+      lmstudio: "Primary local laptop path. Verified through LM Studio /api/v1/models with 262144 loaded context, flash attention, GPU KV offload, and trained_for_tool_use."
+      openaiCompat: "LM Studio chat uses this surface for reasoning and tool calls."
       anthropicCompat: "LM Studio's Anthropic Messages surface streams simple text with the server root URL as baseUrl; keep as a protocol fallback until tool and reasoning behavior are proven."
     thinking:
       # Measured 2026-08-11 against LM Studio on this exact model: baseline 56
@@ -990,4 +1073,4 @@
         Clio shows the level as forced. Output cap is tighter than the
         32GB-class MoE families because this is the 16GB emulation target;
         budget for a reasoning preamble ahead of every answer.
-    serving: "LM Studio reports trained_for_tool_use for the local qwopus3.5-9b-v3 target. Native model override successfully switched residency to granite-4.0-h-350m through the SDK."
+    serving: "LM Studio reports trained_for_tool_use for the local qwopus3.5-9b-v3 target. Configure residency through LM Studio or explicit lmstudio.load settings."

package/src/domains/providers/plugins.ts

@@ -0,0 +1,61 @@
+/**
+ * Loads out-of-tree runtime descriptors into the registry. Two surfaces:
+ *
+ *   1. `~/.config/clio-coder/runtimes/`: any `.js` file whose default export is a valid
+ *      RuntimeDescriptor. Resolved from `clioConfigDir()` so CLIO_CODER_HOME /
+ *      CLIO_CODER_CONFIG_DIR overrides flow through.
+ *   2. npm packages listed under `settings.runtimePlugins` (optional field).
+ *      Each package must export a `clioRuntimes: RuntimeDescriptor[]` array.
+ *
+ * Missing directories, import failures, and descriptor conflicts are logged
+ * to stderr but never throw. The providers domain still boots with whatever
+ * subset loaded cleanly.
+ */
+
+import { join } from "node:path";
+
+import { clioConfigDir } from "../../core/xdg.js";
+import { activateExternalPluginApiBridge } from "../../engine/api-registry.js";
+import type { RuntimeRegistry } from "./registry.js";
+
+interface PluginSettings {
+	runtimePlugins?: unknown;
+}
+
+function extractPluginPackages(settings: unknown): string[] {
+	if (!settings || typeof settings !== "object") return [];
+	const raw = (settings as PluginSettings).runtimePlugins;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((entry): entry is string => typeof entry === "string" && entry.length > 0);
+}
+
+export async function loadPluginRuntimes(
+	registry: RuntimeRegistry,
+	settings?: unknown,
+): Promise<ReadonlyArray<string>> {
+	const loaded: string[] = [];
+
+	const pluginDir = join(clioConfigDir(), "runtimes");
+	const packages = extractPluginPackages(settings);
+	try {
+		const ids = await registry.loadFromDir(pluginDir, activateExternalPluginApiBridge);
+		loaded.push(...ids);
+	} catch (err) {
+		process.stderr.write(
+			`[providers] loadFromDir ${pluginDir} failed: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+	}
+
+	for (const packageName of packages) {
+		try {
+			const ids = await registry.loadFromPackage(packageName, activateExternalPluginApiBridge);
+			loaded.push(...ids);
+		} catch (err) {
+			process.stderr.write(
+				`[providers] loadFromPackage ${packageName} failed: ${err instanceof Error ? err.message : String(err)}\n`,
+			);
+		}
+	}
+
+	return loaded;
+}

package/src/domains/providers/probe/fingerprint.ts

@@ -0,0 +1,64 @@
+export interface NativeRuntimeFingerprint {
+	runtimeId: "lmstudio" | "ollama-native";
+	displayName: string;
+}
+
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response | null> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(url, { signal: controller.signal });
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Probes a URL for known native local-server fingerprints. Returns the
+ * matching runtime id when LM Studio (`/api/v1/models`, falling back to
+ * `/api/v0/models`) or Ollama (`/api/version`) responds, null otherwise. Used
+ * by doctor + configure wizard to steer users onto native runtimes for
+ * resident-model lifecycle.
+ */
+export async function fingerprintNativeRuntime(baseUrl: string): Promise<NativeRuntimeFingerprint | null> {
+	const normalized = baseUrl.replace(/^ws:/u, "http:").replace(/^wss:/u, "https:");
+	const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+	const greeting = await fetchWithTimeout(`${trimmed}/lmstudio-greeting`, 750);
+	if (greeting?.ok) {
+		try {
+			const data = (await greeting.json()) as { lmstudio?: unknown };
+			if (data.lmstudio === true) return { runtimeId: "lmstudio", displayName: "LM Studio" };
+		} catch {
+			// The exact JSON body is the fingerprint.
+		}
+	}
+	const lmStudioV0 = await fetchWithTimeout(`${trimmed}/api/v0/models`, 750);
+	if (lmStudioV0?.ok) {
+		try {
+			const data = (await lmStudioV0.json()) as { data?: unknown };
+			if (
+				Array.isArray(data.data) &&
+				data.data.some((entry) => typeof entry === "object" && entry !== null && "compatibility_type" in entry)
+			) {
+				return { runtimeId: "lmstudio", displayName: "LM Studio" };
+			}
+		} catch {
+			// A malformed v0 body is not an LM Studio fingerprint.
+		}
+	}
+	const ollama = await fetchWithTimeout(`${trimmed}/api/version`, 750);
+	if (ollama?.ok) {
+		try {
+			const data = (await ollama.json()) as { version?: unknown };
+			if (typeof data.version === "string") {
+				return { runtimeId: "ollama-native", displayName: "Ollama" };
+			}
+		} catch {
+			// A reachable endpoint with a non-JSON version reply fingerprints as
+			// unknown; the caller treats null as "no native runtime detected".
+		}
+	}
+	return null;
+}

package/src/domains/providers/probe/http.ts

@@ -0,0 +1,114 @@
+import { performance } from "node:perf_hooks";
+
+import type { ProbeResult } from "../types/runtime-descriptor.js";
+
+export interface HttpProbeOptions {
+	url: string;
+	method?: "GET" | "HEAD" | "POST";
+	headers?: Record<string, string>;
+	body?: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+}
+
+export type JsonProbeOptions = HttpProbeOptions;
+
+export interface JsonProbeResult<T = unknown> extends ProbeResult {
+	data?: T;
+}
+
+export async function probeHttp(opts: HttpProbeOptions): Promise<ProbeResult> {
+	const { response, latencyMs, error } = await runFetch(opts);
+	if (response === null) return { ok: false, error: error ?? "unknown transport error", latencyMs };
+	const method = opts.method ?? "GET";
+	if (response.ok) return { ok: true, latencyMs };
+	// Some servers reject HEAD with 405 even though the endpoint is reachable.
+	if (method === "HEAD" && response.status === 405) return { ok: true, latencyMs };
+	return {
+		ok: false,
+		latencyMs,
+		error: `HTTP ${response.status}: ${response.statusText}`,
+	};
+}
+
+export async function probeJson<T = unknown>(opts: JsonProbeOptions): Promise<JsonProbeResult<T>> {
+	const { response, latencyMs, error } = await runFetch(opts);
+	if (response === null) return { ok: false, error: error ?? "unknown transport error", latencyMs };
+	const method = opts.method ?? "GET";
+	if (!response.ok && !(method === "HEAD" && response.status === 405)) {
+		return {
+			ok: false,
+			latencyMs,
+			error: `HTTP ${response.status}: ${response.statusText}`,
+		};
+	}
+	let data: T;
+	try {
+		data = (await response.json()) as T;
+	} catch (err) {
+		return { ok: false, latencyMs, error: `JSON parse: ${describeError(err)}` };
+	}
+	return { ok: true, latencyMs, data };
+}
+
+interface FetchOutcome {
+	response: Response | null;
+	latencyMs: number;
+	error?: string;
+}
+
+async function runFetch(opts: HttpProbeOptions): Promise<FetchOutcome> {
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, opts.timeoutMs);
+	const onExternalAbort = () => controller.abort();
+	if (opts.signal) {
+		if (opts.signal.aborted) controller.abort();
+		else opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+	}
+	const init: RequestInit = {
+		method: opts.method ?? "GET",
+		signal: controller.signal,
+	};
+	if (opts.headers) init.headers = opts.headers;
+	if (opts.body !== undefined) init.body = opts.body;
+	const started = performance.now();
+	try {
+		const response = await fetch(opts.url, init);
+		return { response, latencyMs: Math.round(performance.now() - started) };
+	} catch (err) {
+		const latencyMs = Math.round(performance.now() - started);
+		if (timedOut) {
+			return { response: null, latencyMs, error: `timeout after ${opts.timeoutMs}ms` };
+		}
+		if (opts.signal?.aborted) {
+			return { response: null, latencyMs, error: "aborted by caller" };
+		}
+		return { response: null, latencyMs, error: describeError(err) };
+	} finally {
+		clearTimeout(timer);
+		if (opts.signal) opts.signal.removeEventListener("abort", onExternalAbort);
+	}
+}
+
+/**
+ * The actionable half of a transport failure.
+ *
+ * undici reports every one of them as the same two words, `fetch failed`, and
+ * puts the part a user can act on onto `cause`: ECONNREFUSED, ENOTFOUND,
+ * ECONNRESET, and the TLS errors all arrive that way. Surfacing only the
+ * wrapper tells someone that something failed and nothing whatsoever about
+ * what, which is the difference between a wrong port and a wrong hostname.
+ */
+function describeError(err: unknown): string {
+	if (!(err instanceof Error)) return String(err);
+	const cause = (err as { cause?: unknown }).cause;
+	if (cause instanceof Error && cause.message.length > 0) {
+		const code = (cause as { code?: unknown }).code;
+		return typeof code === "string" && !cause.message.includes(code) ? `${cause.message} (${code})` : cause.message;
+	}
+	return err.message;
+}

package/src/domains/providers/probe/reasoning.ts

@@ -0,0 +1,111 @@
+/**
+ * Reasoning-capability probe for OpenAI-compatible HTTP endpoints.
+ *
+ * Local servers (LM Studio, llama.cpp, sglang, vllm, ...) advertise themselves
+ * through an OpenAI-compatible surface regardless of whether the loaded model supports thinking.
+ * Defaulting `caps.reasoning = false` means `/thinking` only ever surfaces
+ * `["off"]` for these targets. Probing with a one-shot priming request reveals
+ * the truth: a thinking-capable model emits a non-empty `reasoning_content`
+ * (llama.cpp), `reasoning` (LM Studio + chat-templates), or `reasoning_text`
+ * field in the streamed response. Caching the result per (target, model)
+ * keeps the cost to a single round-trip per session.
+ */
+import { performance } from "node:perf_hooks";
+
+const PROMPT = "What is 2+2? Think briefly, then answer.";
+
+export interface ProbeReasoningOptions {
+	baseUrl: string;
+	modelId: string;
+	timeoutMs: number;
+	apiKey?: string;
+	signal?: AbortSignal;
+}
+
+export interface ProbeReasoningResult {
+	reasoning: boolean;
+	field?: "reasoning_content" | "reasoning" | "reasoning_text";
+	latencyMs: number;
+	error?: string;
+}
+
+interface ChatCompletionResponse {
+	choices?: Array<{
+		message?: {
+			content?: unknown;
+			reasoning_content?: unknown;
+			reasoning?: unknown;
+			reasoning_text?: unknown;
+		};
+	}>;
+}
+
+function nonEmptyString(value: unknown): boolean {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function detectReasoningField(data: ChatCompletionResponse): ProbeReasoningResult["field"] | null {
+	const message = data.choices?.[0]?.message;
+	if (!message) return null;
+	if (nonEmptyString(message.reasoning_content)) return "reasoning_content";
+	if (nonEmptyString(message.reasoning)) return "reasoning";
+	if (nonEmptyString(message.reasoning_text)) return "reasoning_text";
+	return null;
+}
+
+function trimTrailingSlash(url: string): string {
+	return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+export async function probeOpenAICompatReasoning(opts: ProbeReasoningOptions): Promise<ProbeReasoningResult> {
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, opts.timeoutMs);
+	const onExternalAbort = () => controller.abort();
+	if (opts.signal) {
+		if (opts.signal.aborted) controller.abort();
+		else opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+	}
+
+	const headers: Record<string, string> = { "content-type": "application/json" };
+	if (opts.apiKey && opts.apiKey.length > 0) headers.authorization = `Bearer ${opts.apiKey}`;
+
+	const body = JSON.stringify({
+		model: opts.modelId,
+		messages: [{ role: "user", content: PROMPT }],
+		max_tokens: 200,
+		temperature: 0,
+		stream: false,
+		reasoning_effort: "low",
+	});
+
+	const url = `${trimTrailingSlash(opts.baseUrl)}/v1/chat/completions`;
+	const started = performance.now();
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			headers,
+			body,
+			signal: controller.signal,
+		});
+		const latencyMs = Math.round(performance.now() - started);
+		if (!response.ok) {
+			return { reasoning: false, latencyMs, error: `HTTP ${response.status}: ${response.statusText}` };
+		}
+		const data = (await response.json()) as ChatCompletionResponse;
+		const field = detectReasoningField(data);
+		if (field) return { reasoning: true, field, latencyMs };
+		return { reasoning: false, latencyMs };
+	} catch (err) {
+		const latencyMs = Math.round(performance.now() - started);
+		if (timedOut) return { reasoning: false, latencyMs, error: `timeout after ${opts.timeoutMs}ms` };
+		if (opts.signal?.aborted) return { reasoning: false, latencyMs, error: "aborted by caller" };
+		return { reasoning: false, latencyMs, error: err instanceof Error ? err.message : String(err) };
+	} finally {
+		clearTimeout(timer);
+		if (opts.signal) opts.signal.removeEventListener("abort", onExternalAbort);
+	}
+}