pi-omlx-picker 0.2.0

package/.biomeignore

@@ -0,0 +1 @@
+references/

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PeachlifeAB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# Pi OMLX Picker
+
+Pi extension that discovers models from a local [OMLX](https://github.com/Open-Model-Lookup-Exchange) server and registers them as a native Pi provider. Switch models with Pi's built-in `/model` command.
+
+## Install
+
+```sh
+pi install npm:pi-omlx-picker
+```
+
+## Configure
+
+Set these env vars (or copy `.env-example` to `.env`):
+
+```sh
+export OMLX_BASE_URL="http://127.0.0.1:8008/v1"
+export OMLX_API_KEY="omlx-..."
+```
+
+If either is missing, the provider is skipped and Pi logs a message on startup.
+
+Optionally override the model metadata path (default: `~/.omlx/model_settings.json`):
+
+```sh
+export OMLX_MODEL_SETTINGS_PATH="/path/to/model_settings.json"
+```
+
+## How it works
+
+On startup, the extension fetches available models from OMLX, merges local `model_settings.json` metadata, and registers an `omlx` provider in Pi. Thinking controls are applied per-request based on each model's `thinkingDefault`.
+
+## Debugging
+
+```sh
+mise run debug:omlx        # OMLX config, model path, template, cache
+mise run debug:pi          # Pi install, config, session, log, cache
+mise run verify            # Biome + typecheck + unit tests
+mise run smoke:omlx        # Live smoke test against a running OMLX server
+```
+
+See [docs/DEBUG.md](docs/DEBUG.md) for triage order.

package/index.ts

@@ -0,0 +1,94 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { fetchModels, resolveLocalModelSettingsPath, type OmlxModel } from "./src/catalog.ts";
+import { loadConfig, MissingEnvError, type OmlxConfig } from "./src/config.ts";
+import { toProviderConfig } from "./src/provider.ts";
+import { applyOmlxThinkingControls } from "./src/thinking.ts";
+
+const PROVIDER = "omlx";
+const EXTENSION_SINGLETON_KEY = Symbol.for("pi-omlx-picker/loaded");
+
+interface State {
+	config: OmlxConfig | undefined;
+	catalog: OmlxModel[];
+	registered: boolean;
+	lastError: string | undefined;
+	lastRefreshAt: string | undefined;
+	modelSettingsPath: string | undefined;
+}
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+	const globalState = globalThis as Record<PropertyKey, unknown>;
+	if (globalState[EXTENSION_SINGLETON_KEY]) return;
+	globalState[EXTENSION_SINGLETON_KEY] = true;
+
+	const state: State = {
+		config: undefined,
+		catalog: [],
+		registered: false,
+		lastError: undefined,
+		lastRefreshAt: undefined,
+		modelSettingsPath: undefined,
+	};
+
+	await refreshProvider(pi, state);
+
+	pi.on("before_provider_request", (event, ctx) => {
+		if (ctx.model?.provider !== PROVIDER) return;
+		const activeModel = findCatalogModel(state, ctx.model.id);
+		return applyOmlxThinkingControls(event.payload, pi.getThinkingLevel(), activeModel?.thinkingDefault);
+	});
+}
+
+function clearRegisteredProvider(pi: ExtensionAPI, state: State): void {
+	if (state.registered) {
+		pi.unregisterProvider(PROVIDER);
+	}
+	state.catalog = [];
+	state.registered = false;
+	state.config = undefined;
+	state.modelSettingsPath = undefined;
+}
+
+async function refreshProvider(pi: ExtensionAPI, state: State): Promise<void> {
+	let config: OmlxConfig;
+	try {
+		config = loadConfig();
+	} catch (err) {
+		state.lastError =
+			err instanceof MissingEnvError
+				? `${err.varName} is not set`
+				: err instanceof Error
+					? err.message
+					: String(err);
+		clearRegisteredProvider(pi, state);
+		return;
+	}
+
+	const modelSettingsPath = resolveLocalModelSettingsPath(process.env.OMLX_MODEL_SETTINGS_PATH);
+
+	let models: OmlxModel[];
+	try {
+		models = await fetchModels(config.apiRoot, process.env.OMLX_API_KEY!, { modelSettingsPath });
+	} catch (err) {
+		state.lastError = err instanceof Error ? err.message : String(err);
+		return;
+	}
+
+	if (models.length === 0) {
+		state.lastError = "OMLX returned 0 models";
+		clearRegisteredProvider(pi, state);
+		return;
+	}
+
+	pi.registerProvider(PROVIDER, toProviderConfig(config.apiRoot, config.apiKeyEnvVar, models));
+	state.config = config;
+	state.catalog = models;
+	state.registered = true;
+	state.lastError = undefined;
+	state.lastRefreshAt = new Date().toISOString();
+	state.modelSettingsPath = modelSettingsPath;
+}
+
+function findCatalogModel(state: State, id: string | undefined): OmlxModel | undefined {
+	return id ? state.catalog.find((model) => model.id === id) : undefined;
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "pi-omlx-picker",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Pi extension that maps OMLX model settings into native Pi model metadata.",
+  "license": "MIT",
+  "scripts": {
+    "test": "node --import tsx --test 'test/*.test.ts'",
+    "debug:omlx": "tsx scripts/debug-omlx.ts",
+    "debug:pi": "tsx scripts/debug-pi.ts",
+    "smoke:omlx": "tsx scripts/smoke-live-omlx.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@mariozechner/pi-ai": "^0.73.1",
+    "@mariozechner/pi-coding-agent": "*",
+    "tsx": "^4.7.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,548 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface OmlxModel {
+	id: string;
+	displayName?: string;
+	description?: string;
+	modelAlias?: string;
+	contextWindow?: number;
+	maxTokens?: number;
+	thinkingDefault?: boolean | null;
+	taskBudgetTokens?: number;
+	maxToolResultTokens?: number;
+	thinkingBudgetTokens?: number;
+	thinkingBudgetEnabled?: boolean;
+	preserveThinking?: boolean;
+	chatTemplateKwargs?: Record<string, unknown>;
+	forcedCtKwargs?: string[];
+	isDefault?: boolean;
+	isPinned?: boolean;
+	trustRemoteCode?: boolean;
+	ttlSeconds?: number;
+	indexCacheFreq?: number;
+	reasoningParser?: string;
+	activeProfileName?: string;
+	modelType?: string | null;
+	settingsSummary?: Record<string, unknown>;
+}
+
+export interface CatalogDebugEvent {
+	kind: string;
+	details: Record<string, unknown>;
+}
+
+interface OpenAIModelsResponse {
+	object: string;
+	data: Array<{ id: string; object?: string }>;
+}
+
+interface OmlxModelsStatusResponse {
+	models: Array<{
+		id: string;
+		display_name?: string | null;
+		description?: string | null;
+		model_alias?: string | null;
+		max_context_window?: number;
+		max_tokens?: number;
+		thinking_default?: boolean | null;
+		enable_thinking?: boolean | null;
+		max_tool_result_tokens?: number;
+		thinking_budget_tokens?: number;
+		thinking_budget_enabled?: boolean;
+		preserve_thinking?: boolean | null;
+		chat_template_kwargs?: Record<string, unknown> | null;
+		forced_ct_kwargs?: string[];
+		is_default?: boolean;
+		is_pinned?: boolean;
+		pinned?: boolean;
+		trust_remote_code?: boolean;
+		ttl_seconds?: number;
+		index_cache_freq?: number;
+		reasoning_parser?: string | null;
+		active_profile_name?: string | null;
+		model_type?: string | null;
+		engine_type?: string | null;
+		model_type_override?: string | null;
+	}>;
+}
+
+export function parseModelsResponse(json: unknown): OmlxModel[] {
+	const r = json as OpenAIModelsResponse | undefined;
+	if (!r || !Array.isArray(r.data)) {
+		throw new Error("OMLX /models response is missing `data` array");
+	}
+	const seen = new Set<string>();
+	const out: OmlxModel[] = [];
+	for (const entry of r.data) {
+		if (!entry || typeof entry.id !== "string" || !entry.id) continue;
+		if (seen.has(entry.id)) continue;
+		seen.add(entry.id);
+		out.push({ id: entry.id });
+	}
+	return out;
+}
+
+export function parseModelsStatusResponse(json: unknown): OmlxModel[] {
+	const r = json as OmlxModelsStatusResponse | undefined;
+	if (!r || !Array.isArray(r.models)) {
+		throw new Error("OMLX /models/status response is missing `models` array");
+	}
+	const seen = new Set<string>();
+	const out: OmlxModel[] = [];
+	for (const entry of r.models) {
+		if (!entry || typeof entry.id !== "string" || !entry.id) continue;
+		if (seen.has(entry.id)) continue;
+		seen.add(entry.id);
+		const m: OmlxModel = { id: entry.id };
+		if (typeof entry.display_name === "string" && entry.display_name.trim())
+			m.displayName = entry.display_name;
+		if (typeof entry.description === "string" && entry.description.trim())
+			m.description = entry.description;
+		if (typeof entry.model_alias === "string" && entry.model_alias.trim())
+			m.modelAlias = entry.model_alias;
+		if (typeof entry.max_context_window === "number")
+			m.contextWindow = entry.max_context_window;
+		if (typeof entry.max_tokens === "number") m.maxTokens = entry.max_tokens;
+		const chatTemplateKwargs = asRecord(entry.chat_template_kwargs);
+		if (chatTemplateKwargs) m.chatTemplateKwargs = chatTemplateKwargs;
+		if (typeof entry.enable_thinking === "boolean") {
+			m.thinkingDefault = entry.enable_thinking;
+		} else if (
+			chatTemplateKwargs &&
+			typeof chatTemplateKwargs.enable_thinking === "boolean"
+		) {
+			m.thinkingDefault = chatTemplateKwargs.enable_thinking;
+		} else if ("thinking_default" in entry) {
+			m.thinkingDefault = entry.thinking_default ?? null;
+		}
+		if (typeof entry.max_tool_result_tokens === "number")
+			m.maxToolResultTokens = entry.max_tool_result_tokens;
+		if (typeof entry.thinking_budget_tokens === "number")
+			m.thinkingBudgetTokens = entry.thinking_budget_tokens;
+		if (typeof entry.thinking_budget_enabled === "boolean")
+			m.thinkingBudgetEnabled = entry.thinking_budget_enabled;
+		if (typeof entry.preserve_thinking === "boolean")
+			m.preserveThinking = entry.preserve_thinking;
+		else if (typeof chatTemplateKwargs?.preserve_thinking === "boolean")
+			m.preserveThinking = chatTemplateKwargs.preserve_thinking;
+		if (Array.isArray(entry.forced_ct_kwargs)) {
+			m.forcedCtKwargs = entry.forced_ct_kwargs.filter(
+				(item): item is string => typeof item === "string",
+			);
+		}
+		if (typeof entry.is_default === "boolean") m.isDefault = entry.is_default;
+		if (typeof entry.is_pinned === "boolean") m.isPinned = entry.is_pinned;
+		else if (typeof entry.pinned === "boolean") m.isPinned = entry.pinned;
+		if (typeof entry.trust_remote_code === "boolean")
+			m.trustRemoteCode = entry.trust_remote_code;
+		if (typeof entry.ttl_seconds === "number") m.ttlSeconds = entry.ttl_seconds;
+		if (typeof entry.index_cache_freq === "number")
+			m.indexCacheFreq = entry.index_cache_freq;
+		if (
+			typeof entry.reasoning_parser === "string" &&
+			entry.reasoning_parser.trim()
+		)
+			m.reasoningParser = entry.reasoning_parser;
+		if (
+			typeof entry.active_profile_name === "string" &&
+			entry.active_profile_name.trim()
+		)
+			m.activeProfileName = entry.active_profile_name;
+		const type =
+			entry.model_type_override ?? entry.model_type ?? entry.engine_type;
+		if (typeof type === "string") m.modelType = type.toLowerCase();
+		out.push(m);
+	}
+	return out;
+}
+
+export const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
+
+export async function fetchModels(
+	apiRoot: string,
+	apiKey: string,
+	opts: {
+		signal?: AbortSignal;
+		timeoutMs?: number;
+		modelSettingsPath?: string;
+		onDebug?: (event: CatalogDebugEvent) => void;
+	} = {},
+): Promise<OmlxModel[]> {
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+	let models: OmlxModel[];
+
+	try {
+		const json = await getJson(
+			`${apiRoot}/models/status`,
+			apiKey,
+			opts.signal,
+			timeoutMs,
+		);
+		models = parseModelsStatusResponse(json);
+		opts.onDebug?.({
+			kind: "catalog_status_loaded",
+			details: {
+				apiRoot,
+				count: models.length,
+				documenter: models.find((m) => m.id === "qwen3.6-8b-documenter"),
+			},
+		});
+		return applyLocalModelSettings(
+			models,
+			apiRoot,
+			opts.modelSettingsPath,
+			opts.onDebug,
+		);
+	} catch (err) {
+		if (err instanceof Error && err.name === "AbortError") throw err;
+		opts.onDebug?.({
+			kind: "catalog_status_failed",
+			details: {
+				apiRoot,
+				error: err instanceof Error ? err.message : String(err),
+			},
+		});
+		// Fall through to /models for servers without /models/status.
+	}
+
+	const json = await getJson(
+		`${apiRoot}/models`,
+		apiKey,
+		opts.signal,
+		timeoutMs,
+	);
+	models = parseModelsResponse(json);
+	opts.onDebug?.({
+		kind: "catalog_models_loaded",
+		details: { apiRoot, count: models.length },
+	});
+	return applyLocalModelSettings(
+		models,
+		apiRoot,
+		opts.modelSettingsPath,
+		opts.onDebug,
+	);
+}
+
+async function getJson(
+	url: string,
+	apiKey: string,
+	parent: AbortSignal | undefined,
+	timeoutMs: number,
+): Promise<unknown> {
+	const signal = withTimeout(parent, timeoutMs);
+	const res = await fetch(url, {
+		headers: { Authorization: `Bearer ${apiKey}` },
+		signal,
+	}).catch((err) => {
+		if (err instanceof Error && err.name === "AbortError") {
+			throw new Error(`GET ${url} timed out after ${timeoutMs}ms`);
+		}
+		throw err;
+	});
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(
+			`GET ${url} -> ${res.status} ${res.statusText}${body ? `: ${body}` : ""}`,
+		);
+	}
+	return res.json();
+}
+
+function withTimeout(
+	parent: AbortSignal | undefined,
+	timeoutMs: number,
+): AbortSignal {
+	const ctl = new AbortController();
+	const timer = setTimeout(() => ctl.abort(), timeoutMs);
+	if (parent) {
+		if (parent.aborted) ctl.abort();
+		else parent.addEventListener("abort", () => ctl.abort(), { once: true });
+	}
+	ctl.signal.addEventListener("abort", () => clearTimeout(timer), {
+		once: true,
+	});
+	return ctl.signal;
+}
+
+export function applyLocalModelSettings(
+	models: OmlxModel[],
+	apiRoot: string,
+	modelSettingsPath = process.env.OMLX_MODEL_SETTINGS_PATH,
+	onDebug?: (event: CatalogDebugEvent) => void,
+): OmlxModel[] {
+	const path = resolveLocalModelSettingsPath(modelSettingsPath);
+	onDebug?.({
+		kind: "catalog_local_settings_considered",
+		details: {
+			apiRoot,
+			path,
+			explicitPath: !!modelSettingsPath,
+			exists: path ? existsSync(path) : false,
+		},
+	});
+	if (!path || !existsSync(path)) return models;
+
+	let settings: Record<string, unknown>;
+	try {
+		settings = JSON.parse(readFileSync(path, "utf8")) as Record<
+			string,
+			unknown
+		>;
+	} catch {
+		onDebug?.({
+			kind: "catalog_local_settings_read_failed",
+			details: { path },
+		});
+		return models;
+	}
+
+	const byModel = settings.models;
+	if (!byModel || typeof byModel !== "object" || Array.isArray(byModel)) {
+		onDebug?.({
+			kind: "catalog_local_settings_invalid",
+			details: { path, reason: "models object missing" },
+		});
+		return models;
+	}
+
+	return models.map((model) => {
+		const entry = (byModel as Record<string, unknown>)[model.id];
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+			if (model.id === "qwen3.6-8b-documenter") {
+				onDebug?.({
+					kind: "catalog_local_model_settings_missing",
+					details: { path, modelId: model.id },
+				});
+			}
+			return model;
+		}
+		const next = applyModelSettingsEntry(
+			model,
+			entry as Record<string, unknown>,
+		);
+		if (
+			next.thinkingDefault !== model.thinkingDefault ||
+			next.contextWindow !== model.contextWindow ||
+			next.maxTokens !== model.maxTokens ||
+			next.displayName !== model.displayName ||
+			next.description !== model.description ||
+			next.modelAlias !== model.modelAlias ||
+			next.taskBudgetTokens !== model.taskBudgetTokens ||
+			next.maxToolResultTokens !== model.maxToolResultTokens ||
+			next.thinkingBudgetTokens !== model.thinkingBudgetTokens ||
+			next.thinkingBudgetEnabled !== model.thinkingBudgetEnabled ||
+			next.preserveThinking !== model.preserveThinking ||
+			JSON.stringify(next.chatTemplateKwargs) !==
+				JSON.stringify(model.chatTemplateKwargs) ||
+			JSON.stringify(next.forcedCtKwargs) !==
+				JSON.stringify(model.forcedCtKwargs) ||
+			next.isDefault !== model.isDefault ||
+			next.isPinned !== model.isPinned ||
+			next.trustRemoteCode !== model.trustRemoteCode ||
+			next.ttlSeconds !== model.ttlSeconds ||
+			next.indexCacheFreq !== model.indexCacheFreq ||
+			next.reasoningParser !== model.reasoningParser ||
+			next.activeProfileName !== model.activeProfileName ||
+			next.modelType !== model.modelType ||
+			JSON.stringify(next.settingsSummary) !==
+				JSON.stringify(model.settingsSummary)
+		) {
+			onDebug?.({
+				kind: "catalog_local_model_settings_applied",
+				details: {
+					path,
+					modelId: model.id,
+					before: model,
+					after: next,
+					entrySummary: summarizeModelSettingsEntry(
+						entry as Record<string, unknown>,
+					),
+				},
+			});
+		}
+		return next;
+	});
+}
+
+function applyModelSettingsEntry(
+	model: OmlxModel,
+	entry: Record<string, unknown>,
+): OmlxModel {
+	const next: OmlxModel = { ...model };
+	const chatTemplateKwargs = asRecord(entry.chat_template_kwargs);
+
+	if (typeof entry.display_name === "string" && entry.display_name.trim())
+		next.displayName = entry.display_name;
+	if (typeof entry.description === "string" && entry.description.trim())
+		next.description = entry.description;
+	if (typeof entry.model_alias === "string" && entry.model_alias.trim())
+		next.modelAlias = entry.model_alias;
+	if (typeof entry.enable_thinking === "boolean") {
+		next.thinkingDefault = entry.enable_thinking;
+	}
+	if (chatTemplateKwargs) {
+		next.chatTemplateKwargs = chatTemplateKwargs;
+		const enableThinking = chatTemplateKwargs.enable_thinking;
+		if (
+			typeof enableThinking === "boolean" &&
+			typeof entry.enable_thinking !== "boolean"
+		) {
+			next.thinkingDefault = enableThinking;
+		}
+	}
+	if (typeof entry.max_context_window === "number")
+		next.contextWindow = entry.max_context_window;
+	if (typeof entry.max_tokens === "number") next.maxTokens = entry.max_tokens;
+	if (typeof entry.task_budget_tokens === "number")
+		next.taskBudgetTokens = entry.task_budget_tokens;
+	if (typeof entry.max_tool_result_tokens === "number")
+		next.maxToolResultTokens = entry.max_tool_result_tokens;
+	if (typeof entry.thinking_budget_tokens === "number")
+		next.thinkingBudgetTokens = entry.thinking_budget_tokens;
+	if (typeof entry.thinking_budget_enabled === "boolean")
+		next.thinkingBudgetEnabled = entry.thinking_budget_enabled;
+	// preserve_thinking: top branch handles OmlxModelsStatusResponse (server path).
+	// Local model_settings.json always places this inside chat_template_kwargs,
+	// so the else-if branch is the active path for local files.
+	if (typeof entry.preserve_thinking === "boolean") {
+		next.preserveThinking = entry.preserve_thinking;
+	} else if (typeof chatTemplateKwargs?.preserve_thinking === "boolean") {
+		next.preserveThinking = chatTemplateKwargs.preserve_thinking;
+	}
+	if (Array.isArray(entry.forced_ct_kwargs)) {
+		next.forcedCtKwargs = entry.forced_ct_kwargs.filter(
+			(item): item is string => typeof item === "string",
+		);
+	}
+	if (typeof entry.is_default === "boolean") next.isDefault = entry.is_default;
+	if (typeof entry.is_pinned === "boolean") next.isPinned = entry.is_pinned;
+	if (typeof entry.trust_remote_code === "boolean")
+		next.trustRemoteCode = entry.trust_remote_code;
+	if (typeof entry.ttl_seconds === "number")
+		next.ttlSeconds = entry.ttl_seconds;
+	if (typeof entry.index_cache_freq === "number")
+		next.indexCacheFreq = entry.index_cache_freq;
+	if (
+		typeof entry.reasoning_parser === "string" &&
+		entry.reasoning_parser.trim()
+	)
+		next.reasoningParser = entry.reasoning_parser;
+	if (
+		typeof entry.active_profile_name === "string" &&
+		entry.active_profile_name.trim()
+	)
+		next.activeProfileName = entry.active_profile_name;
+	if (typeof entry.model_type_override === "string")
+		next.modelType = entry.model_type_override.toLowerCase();
+	next.settingsSummary = summarizeModelSettingsEntry(entry);
+	return next;
+}
+
+export function resolveLocalModelSettingsPath(
+	modelSettingsPath: string | undefined,
+): string | undefined {
+	if (modelSettingsPath) return modelSettingsPath;
+	return join(homedir(), ".omlx", "model_settings.json");
+}
+
+function summarizeModelSettingsEntry(
+	entry: Record<string, unknown>,
+): Record<string, unknown> {
+	const chatTemplateKwargs = asRecord(entry.chat_template_kwargs);
+	return (
+		compactObject({
+			identity: compactObject({
+				displayName: entry.display_name,
+				description: entry.description,
+				modelAlias: entry.model_alias,
+				modelTypeOverride: entry.model_type_override,
+			}),
+			thinking: compactObject({
+				enabled: entry.enable_thinking ?? chatTemplateKwargs?.enable_thinking,
+				budgetEnabled: entry.thinking_budget_enabled,
+				budgetTokens: entry.thinking_budget_tokens,
+				preserve:
+					entry.preserve_thinking ?? chatTemplateKwargs?.preserve_thinking,
+				reasoningEffort: chatTemplateKwargs?.reasoning_effort,
+				parser: entry.reasoning_parser,
+				forcedCtKwargs: entry.forced_ct_kwargs,
+			}),
+			chatTemplate: compactObject({
+				kwargs: chatTemplateKwargs,
+				forcedKeys: entry.forced_ct_kwargs,
+			}),
+			limits: compactObject({
+				contextWindow: entry.max_context_window,
+				maxTokens: entry.max_tokens,
+				maxToolResultTokens: entry.max_tool_result_tokens,
+			}),
+			sampling: compactObject({
+				temperature: entry.temperature,
+				topP: entry.top_p,
+				topK: entry.top_k,
+				minP: entry.min_p,
+				repetitionPenalty: entry.repetition_penalty,
+				presencePenalty: entry.presence_penalty,
+				forceSampling: entry.force_sampling,
+			}),
+			dflash: compactObject({
+				enabled: entry.dflash_enabled,
+				draftModel: entry.dflash_draft_model,
+				draftQuantBits: entry.dflash_draft_quant_bits,
+			}),
+			specprefill: compactObject({
+				enabled: entry.specprefill_enabled,
+				draftModel: entry.specprefill_draft_model,
+				keepPct: entry.specprefill_keep_pct,
+				threshold: entry.specprefill_threshold,
+			}),
+			turboquant: compactObject({
+				enabled: entry.turboquant_kv_enabled,
+				bits: entry.turboquant_kv_bits,
+				skipLast: entry.turboquant_skip_last,
+			}),
+			lifecycle: compactObject({
+				isDefault: entry.is_default,
+				isPinned: entry.is_pinned,
+				ttlSeconds: entry.ttl_seconds,
+				indexCacheFreq: entry.index_cache_freq,
+			}),
+			security: compactObject({
+				trustRemoteCode: entry.trust_remote_code,
+			}),
+			profile: compactObject({
+				activeProfileName: entry.active_profile_name,
+			}),
+			bridge: compactObject({
+				taskBudgetTokens: entry.task_budget_tokens,
+			}),
+		}) ?? {}
+	);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function compactObject(
+	record: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+	const entries = Object.entries(record).filter(([, value]) => {
+		if (value === undefined) return false;
+		if (
+			value &&
+			typeof value === "object" &&
+			!Array.isArray(value) &&
+			Object.keys(value).length === 0
+		)
+			return false;
+		return true;
+	});
+	return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+

package/src/config.ts

@@ -0,0 +1,27 @@
+export interface OmlxConfig {
+	apiRoot: string;
+	apiKeyEnvVar: string;
+}
+
+export class MissingEnvError extends Error {
+	constructor(public readonly varName: string) {
+		super(`${varName} is not set`);
+		this.name = "MissingEnvError";
+	}
+}
+
+export function normalizeBaseUrl(raw: string): string {
+	const trimmed = raw.trim().replace(/\/+$/, "");
+	if (!trimmed) throw new Error("OMLX_BASE_URL is empty");
+	return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): OmlxConfig {
+	const baseUrl = env.OMLX_BASE_URL;
+	if (!baseUrl) throw new MissingEnvError("OMLX_BASE_URL");
+	if (!env.OMLX_API_KEY) throw new MissingEnvError("OMLX_API_KEY");
+	return {
+		apiRoot: normalizeBaseUrl(baseUrl),
+		apiKeyEnvVar: "OMLX_API_KEY",
+	};
+}

package/src/provider.ts

@@ -0,0 +1,254 @@
+import {
+	type Api,
+	type AssistantMessage,
+	type AssistantMessageEvent,
+	type AssistantMessageEventStream,
+	type Context,
+	createAssistantMessageEventStream,
+	type Model,
+	type SimpleStreamOptions,
+	streamSimpleOpenAICompletions,
+} from "@mariozechner/pi-ai";
+import type {
+	ProviderConfig,
+	ProviderModelConfig,
+} from "@mariozechner/pi-coding-agent";
+import type { OmlxModel } from "./catalog.ts";
+
+// Pi's documented defaults when the server doesn't report per-model values.
+// Users can override these via modelOverrides in ~/.pi/config.json.
+const DEFAULT_CONTEXT_WINDOW = 128000;
+const DEFAULT_MAX_TOKENS = 16384;
+const DEFAULT_FIRST_DELTA_TIMEOUT_MS = 120_000;
+const FIRST_DELTA_MAX_ATTEMPTS = 2;
+type StreamTimeoutEvent = {
+	model: string;
+	timeoutMs: number;
+	attempt: number;
+	maxAttempts: number;
+	final: boolean;
+};
+
+export function toProviderConfig(
+	apiRoot: string,
+	apiKeyEnvVar: string,
+	models: OmlxModel[],
+	onStreamTimeout?: (event: StreamTimeoutEvent) => void,
+): ProviderConfig {
+	return {
+		baseUrl: apiRoot,
+		apiKey: apiKeyEnvVar,
+		api: "openai-completions",
+		authHeader: true,
+		streamSimple: (model, context, options) =>
+			streamOmlxOpenAICompletions(
+				model,
+				context,
+				options,
+				resolveFirstDeltaTimeoutMs(),
+				onStreamTimeout,
+			),
+		models: models.map(toProviderModel),
+	};
+}
+
+function toProviderModel(m: OmlxModel): ProviderModelConfig {
+	const input: ("text" | "image")[] =
+		m.modelType === "vlm" ? ["text", "image"] : ["text"];
+	const reasoning = m.thinkingDefault === true;
+	const compat = {
+		supportsDeveloperRole: false,
+		supportsReasoningEffort: false,
+		supportsLongCacheRetention: true,
+		maxTokensField: "max_tokens" as const,
+		...(reasoning ? { thinkingFormat: "qwen-chat-template" as const } : {}),
+	};
+	return {
+		id: m.id,
+		name: m.displayName ?? m.id,
+		reasoning,
+		input,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: m.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+		maxTokens: m.maxTokens ?? DEFAULT_MAX_TOKENS,
+		compat,
+	};
+}
+
+function streamOmlxOpenAICompletions(
+	model: Model<Api>,
+	context: Context,
+	options: SimpleStreamOptions | undefined,
+	firstDeltaTimeoutMs: number,
+	onStreamTimeout: ((event: StreamTimeoutEvent) => void) | undefined,
+): AssistantMessageEventStream {
+	const stream = createAssistantMessageEventStream();
+	let closed = false;
+	let startEvent: AssistantMessageEvent | undefined;
+	let startPushed = false;
+
+	const pushWithStart = (event: AssistantMessageEvent) => {
+		if (!startPushed) {
+			stream.push(
+				startEvent ?? { type: "start", partial: eventPartial(event, model) },
+			);
+			startPushed = true;
+		}
+		stream.push(event);
+	};
+
+	(async () => {
+		try {
+			for (let attempt = 1; attempt <= FIRST_DELTA_MAX_ATTEMPTS; attempt++) {
+				const controller = new AbortController();
+				const signal = mergeAbortSignals(options?.signal, controller.signal);
+				let attemptTimedOut = false;
+				let firstMeaningfulEvent = false;
+				const timeout = setTimeout(() => {
+					if (closed || firstMeaningfulEvent) return;
+					attemptTimedOut = true;
+					onStreamTimeout?.({
+						model: model.id,
+						timeoutMs: firstDeltaTimeoutMs,
+						attempt,
+						maxAttempts: FIRST_DELTA_MAX_ATTEMPTS,
+						final: attempt >= FIRST_DELTA_MAX_ATTEMPTS,
+					});
+					controller.abort();
+				}, firstDeltaTimeoutMs);
+
+				const inner = streamSimpleOpenAICompletions(
+					model as Model<"openai-completions">,
+					context,
+					{
+						...options,
+						signal,
+					},
+				);
+				for await (const event of inner) {
+					if (closed || attemptTimedOut) break;
+					if (event.type === "start") {
+						startEvent ??= event;
+						continue;
+					}
+					if (isMeaningfulBodyEvent(event)) {
+						firstMeaningfulEvent = true;
+						clearTimeout(timeout);
+					}
+					if (event.type === "done" || event.type === "error") {
+						closed = true;
+						clearTimeout(timeout);
+					}
+					pushWithStart(event);
+				}
+				clearTimeout(timeout);
+				if (closed) return;
+				if (!attemptTimedOut) {
+					closed = true;
+					stream.end();
+					return;
+				}
+				if (attempt < FIRST_DELTA_MAX_ATTEMPTS) continue;
+				closed = true;
+				pushWithStart({
+					type: "error",
+					reason: "error",
+					error: errorAssistantMessage(
+						model,
+						`OMLX stream timed out: no text, thinking, or tool delta arrived within ${firstDeltaTimeoutMs}ms after response headers on ${FIRST_DELTA_MAX_ATTEMPTS} attempts.`,
+					),
+				});
+				stream.end();
+				return;
+			}
+		} catch (error) {
+			if (closed) return;
+			closed = true;
+			pushWithStart({
+				type: "error",
+				reason: options?.signal?.aborted ? "aborted" : "error",
+				error: errorAssistantMessage(
+					model,
+					error instanceof Error ? error.message : String(error),
+					options?.signal?.aborted ? "aborted" : "error",
+				),
+			});
+			stream.end();
+		}
+	})();
+
+	return stream;
+}
+
+function isMeaningfulBodyEvent(event: AssistantMessageEvent): boolean {
+	return [
+		"text_start",
+		"text_delta",
+		"thinking_start",
+		"thinking_delta",
+		"toolcall_start",
+		"toolcall_delta",
+		"done",
+		"error",
+	].includes(event.type);
+}
+
+function mergeAbortSignals(
+	parent: AbortSignal | undefined,
+	child: AbortSignal,
+): AbortSignal {
+	if (!parent) return child;
+	if (parent.aborted) return parent;
+	const controller = new AbortController();
+	const abort = () => controller.abort();
+	parent.addEventListener("abort", abort, { once: true });
+	child.addEventListener("abort", abort, { once: true });
+	return controller.signal;
+}
+
+function eventPartial(
+	event: AssistantMessageEvent,
+	model: Model<Api>,
+): AssistantMessage {
+	if ("partial" in event) return event.partial;
+	if ("message" in event) return event.message;
+	if ("error" in event) return event.error;
+	return errorAssistantMessage(
+		model,
+		"OMLX stream started without a start event",
+	);
+}
+
+function errorAssistantMessage(
+	model: Model<Api>,
+	errorMessage: string,
+	stopReason: "error" | "aborted" = "error",
+): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason,
+		errorMessage,
+		timestamp: Date.now(),
+	};
+}
+
+function resolveFirstDeltaTimeoutMs(): number {
+	const raw = process.env.OMLX_STREAM_FIRST_DELTA_TIMEOUT_MS;
+	if (!raw) return DEFAULT_FIRST_DELTA_TIMEOUT_MS;
+	const value = Number(raw);
+	return Number.isFinite(value) && value > 0
+		? value
+		: DEFAULT_FIRST_DELTA_TIMEOUT_MS;
+}

package/src/smoke-model-selection.ts

@@ -0,0 +1,59 @@
+export type SmokeStatusModel = {
+	id?: string;
+	thinking_default?: boolean | null;
+	loaded?: boolean;
+	engine_type?: string | null;
+	model_type?: string | null;
+	estimated_size?: number;
+	forced_ct_kwargs?: string[];
+};
+
+export function selectNonThinkingSmokeModel(
+	models: SmokeStatusModel[],
+): string | undefined {
+	const nonThinkingModels = models.filter(
+		(model) =>
+			model.thinking_default === false || model.thinking_default === null,
+	);
+	return (
+		selectBestSmokeModel(nonThinkingModels.filter(isChatSmokeModel)) ??
+		selectFirstSmokeModel(nonThinkingModels)
+	);
+}
+
+function isChatSmokeModel(model: SmokeStatusModel): boolean {
+	return model.engine_type === "batched" || model.model_type === "llm";
+}
+
+function selectFirstSmokeModel(models: SmokeStatusModel[]): string | undefined {
+	return models.find(
+		(model): model is SmokeStatusModel & { id: string } =>
+			typeof model.id === "string",
+	)?.id;
+}
+
+function selectBestSmokeModel(models: SmokeStatusModel[]): string | undefined {
+	return models
+		.filter(
+			(model): model is SmokeStatusModel & { id: string } =>
+				typeof model.id === "string",
+		)
+		.slice()
+		.sort((a, b) => {
+			const loadedA = a.loaded === true ? 0 : 1;
+			const loadedB = b.loaded === true ? 0 : 1;
+			if (loadedA !== loadedB) return loadedA - loadedB;
+
+			const sizeA =
+				typeof a.estimated_size === "number"
+					? a.estimated_size
+					: Number.POSITIVE_INFINITY;
+			const sizeB =
+				typeof b.estimated_size === "number"
+					? b.estimated_size
+					: Number.POSITIVE_INFINITY;
+			if (sizeA !== sizeB) return sizeA - sizeB;
+
+			return a.id.localeCompare(b.id);
+		})[0]?.id;
+}

package/src/thinking.ts

@@ -0,0 +1,29 @@
+export function applyOmlxThinkingControls(
+	payload: unknown,
+	level: string,
+	modelThinkingDefault?: boolean | null,
+): unknown {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload))
+		return payload;
+
+	const current = payload as Record<string, unknown>;
+	const enabled = modelThinkingDefault === true && level !== "off";
+	const chatTemplateKwargs = current.chat_template_kwargs;
+	const existingChatTemplateKwargs =
+		chatTemplateKwargs &&
+		typeof chatTemplateKwargs === "object" &&
+		!Array.isArray(chatTemplateKwargs)
+			? (chatTemplateKwargs as Record<string, unknown>)
+			: {};
+
+	if (enabled) return current;
+
+	return {
+		...current,
+		thinking_budget: 0,
+		chat_template_kwargs: {
+			...existingChatTemplateKwargs,
+			enable_thinking: false,
+		},
+	};
+}