pi-omlx-picker 0.2.1 → 0.2.3

package/README.md

@@ -1,19 +1,40 @@
 # 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.
+> Seamlessly integrate your local [oMLX](https://github.com/jundot/omlx) models into Pi.
 
-## Install
+This extension discovers models from a local OMLX server and registers them as native Pi providers. Switch between your local and remote models effortlessly using Pi's built-in `/model` command.
+
+![Pi OMLX Picker Demo](./.assets/demo.gif)
+
+## ✨ Features
+
+* Auto discovery: fetches and registers available OMLX models without blocking Pi startup.
+* Native integration: login uses Pi's standard `/login`, and models use Pi's standard `/model` menu.
+* Smart overrides: applies per-request thinking controls based on each model's `thinkingDefault` metadata.
+
+## 📦 Installation
 
 ```sh
 pi install npm:pi-omlx-picker
 ```
 
-## Configure
+## 🛠️ Development
 
-Run `/omlx-login` in Pi and paste your OMLX base URL and API key. That's it. Re-run `/omlx-login` to change credentials.
+- `npm install`
+- `npm run check`
+- `npm run format`
+- `npm test`
+- `npm run test:watch`
 
-Env-var overrides, model metadata overlay, and stream timeout knobs are documented in [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
+## 🚀 Quick Start
+
+1. Start your local OMLX server.
+2. Run `/login` in Pi, choose **API key**, then choose **OMLX**.
+3. Enter your OMLX API key.
+4. Type `/model` to see and select your OMLX models.
 
-## How it works
+The default base URL is `http://127.0.0.1:8000/v1`. Set `OMLX_BASE_URL` before starting Pi if your OMLX server uses a different URL.
 
-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`.
+## ⚙️ Configuration
+
+Env-var overrides, model metadata overlay, and stream timeout knobs are documented in [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).

package/index.ts

@@ -1,23 +1,52 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { PROVIDER_KEY, saveOmlxCredential } from "./src/auth-storage.ts";
-import { fetchModels, resolveLocalModelSettingsPath, type OmlxModel } from "./src/catalog.ts";
-import { applyStoredCredentialToEnv, loadConfig, MissingEnvError, normalizeBaseUrl, type OmlxConfig } from "./src/config.ts";
+import {
+	type Api,
+	type AssistantMessage,
+	createAssistantMessageEventStream,
+	type Model,
+} from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { PROVIDER_KEY } from "./src/auth-storage.ts";
+import {
+	fetchModels,
+	type OmlxModel,
+	readCatalogCache,
+	readLastCatalogCache,
+	resolveLocalModelSettingsPath,
+	writeCatalogCache,
+} from "./src/catalog.ts";
+import {
+	DEFAULT_OMLX_BASE_URL,
+	loadConfig,
+	type OmlxConfig,
+	resolveConfiguredApiKey,
+} from "./src/config.ts";
 import { toProviderConfig } from "./src/provider.ts";
 import { applyOmlxThinkingControls } from "./src/thinking.ts";
 
 const PROVIDER = PROVIDER_KEY;
 const EXTENSION_SINGLETON_KEY = Symbol.for("pi-omlx-picker/loaded");
 
+const STARTUP_TIMEOUT_MS = 2_000;
+const POLL_INTERVAL_MS = 10 * 60 * 1000;
+const BACKOFF_BASE_MS = 2_000;
+const BACKOFF_MAX_MS = 60_000;
+
+const SETUP_MODEL: OmlxModel = {
+	id: "setup",
+	displayName: "OMLX (run /login)",
+};
+
 interface State {
 	config: OmlxConfig | undefined;
 	catalog: OmlxModel[];
 	registered: boolean;
+	stopped: boolean;
 	lastError: string | undefined;
 	lastRefreshAt: string | undefined;
 	modelSettingsPath: string | undefined;
 }
 
-export default async function (pi: ExtensionAPI): Promise<void> {
+export default function (pi: ExtensionAPI): void {
 	const globalState = globalThis as Record<PropertyKey, unknown>;
 	if (globalState[EXTENSION_SINGLETON_KEY]) return;
 	globalState[EXTENSION_SINGLETON_KEY] = true;
@@ -26,108 +55,192 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		config: undefined,
 		catalog: [],
 		registered: false,
+		stopped: false,
 		lastError: undefined,
 		lastRefreshAt: undefined,
 		modelSettingsPath: undefined,
 	};
 
-	applyStoredCredentialToEnv();
-	await refreshProvider(pi, state);
+	registerCachedOrSetupModels(pi, state);
+	void startPolling(pi, state).catch((err) => {
+		state.lastError = err instanceof Error ? err.message : String(err);
+	});
 
 	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);
+		return applyOmlxThinkingControls(
+			event.payload,
+			pi.getThinkingLevel(),
+			activeModel?.thinkingDefault,
+		);
 	});
 
-	pi.registerCommand("omlx-login", {
-		description: "Sign in to OMLX (set base URL and API key)",
-		handler: async (_args, ctx) => {
-			const baseUrlInput = await ctx.ui.input("OMLX base URL", "http://127.0.0.1:8000/v1");
-			if (!baseUrlInput) return;
-			const apiKey = await ctx.ui.input("OMLX API key", "omlx-...");
-			if (!apiKey) return;
-
-			let baseUrl: string;
-			try {
-				baseUrl = normalizeBaseUrl(baseUrlInput);
-			} catch (err) {
-				ctx.ui.notify(`Invalid base URL: ${err instanceof Error ? err.message : String(err)}`, "error");
-				return;
-			}
-
-			ctx.ui.notify("Validating OMLX credentials…", "info");
-			try {
-				await fetchModels(baseUrl, apiKey, { timeoutMs: VALIDATE_TIMEOUT_MS });
-			} catch (err) {
-				ctx.ui.notify(`OMLX login failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-				return;
-			}
-
-			saveOmlxCredential(baseUrl, apiKey);
-			process.env.OMLX_BASE_URL = baseUrl;
-			process.env.OMLX_API_KEY = apiKey;
-			await refreshProvider(pi, state);
-			const message = state.registered
-				? `OMLX connected — ${state.catalog.length} models available`
-				: `OMLX login saved but provider failed: ${state.lastError ?? "unknown error"}`;
-			ctx.ui.notify(message, state.registered ? "info" : "warning");
-		},
+	pi.on("session_shutdown", () => {
+		state.stopped = true;
+		delete globalState[EXTENSION_SINGLETON_KEY];
 	});
 }
 
-const VALIDATE_TIMEOUT_MS = 10_000;
-
-function clearRegisteredProvider(pi: ExtensionAPI, state: State): void {
-	if (state.registered) {
-		pi.unregisterProvider(PROVIDER);
+async function startPolling(pi: ExtensionAPI, state: State): Promise<void> {
+	let backoffMs = BACKOFF_BASE_MS;
+
+	while (!state.stopped) {
+		const result = await refreshProvider(pi, state, {
+			timeoutMs: STARTUP_TIMEOUT_MS,
+		});
+
+		if (result === "registered") {
+			backoffMs = BACKOFF_BASE_MS;
+			await sleep(POLL_INTERVAL_MS);
+		} else {
+			registerCachedOrSetupModels(pi, state);
+			await sleep(backoffMs);
+			backoffMs = Math.min(backoffMs * 2, BACKOFF_MAX_MS);
+		}
 	}
-	state.catalog = [];
-	state.registered = false;
-	state.config = undefined;
-	state.modelSettingsPath = undefined;
 }
 
-async function refreshProvider(pi: ExtensionAPI, state: State): Promise<void> {
-	let config: OmlxConfig;
+function tryLoadConfig(): OmlxConfig | undefined {
 	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 loadConfig();
+	} catch {
+		return undefined;
+	}
+}
+
+function registerModels(
+	pi: ExtensionAPI,
+	state: State,
+	config: OmlxConfig,
+	models: OmlxModel[],
+	modelSettingsPath?: string,
+): void {
+	pi.registerProvider(PROVIDER, {
+		name: "OMLX",
+		...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 registerCachedOrSetupModels(pi: ExtensionAPI, state: State): void {
+	const config = tryLoadConfig() ?? {
+		apiRoot: DEFAULT_OMLX_BASE_URL,
+		apiKeyEnvVar: "OMLX_API_KEY",
+	};
+	const cached = readCatalogCache(config.apiRoot);
+	const fallbackCached = resolveConfiguredApiKey()
+		? undefined
+		: readLastCatalogCache();
+	const models =
+		cached && cached.length > 0
+			? cached
+			: fallbackCached && fallbackCached.length > 0
+				? fallbackCached
+				: [SETUP_MODEL];
+
+	if (resolveConfiguredApiKey()) {
+		registerModels(pi, state, config, models);
 		return;
 	}
 
-	const modelSettingsPath = resolveLocalModelSettingsPath(process.env.OMLX_MODEL_SETTINGS_PATH);
+	pi.registerProvider(PROVIDER, {
+		...toProviderConfig(config.apiRoot, config.apiKeyEnvVar, models),
+		name: "OMLX",
+		authHeader: false,
+		streamSimple: streamMissingCredentials,
+	});
+	state.config = config;
+	state.catalog = models;
+	state.registered = true;
+	state.lastError = "OMLX credentials are not set. Run /login and choose OMLX.";
+	state.lastRefreshAt = new Date().toISOString();
+	state.modelSettingsPath = undefined;
+}
+
+function streamMissingCredentials(model: Model<Api>) {
+	const stream = createAssistantMessageEventStream();
+	const message: AssistantMessage = {
+		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: "error",
+		errorMessage:
+			"OMLX credentials are not configured. Run /login, choose API key, select OMLX, then try the model again.",
+		timestamp: Date.now(),
+	};
+	queueMicrotask(() => {
+		stream.push({ type: "start", partial: message });
+		stream.push({ type: "error", reason: "error", error: message });
+		stream.end();
+	});
+	return stream;
+}
+
+type RefreshResult = "registered" | "not_configured" | "failed";
+
+async function refreshProvider(
+	pi: ExtensionAPI,
+	state: State,
+	opts: { timeoutMs?: number } = {},
+): Promise<RefreshResult> {
+	const config = loadConfig();
+	const apiKey = resolveConfiguredApiKey();
+	if (!apiKey) {
+		state.lastError = "OMLX credentials are not set";
+		return "not_configured";
+	}
+
+	const modelSettingsPath = resolveLocalModelSettingsPath(
+		process.env.OMLX_MODEL_SETTINGS_PATH,
+	);
 
 	let models: OmlxModel[];
 	try {
-		models = await fetchModels(config.apiRoot, process.env.OMLX_API_KEY!, { modelSettingsPath });
+		models = await fetchModels(config.apiRoot, apiKey, {
+			modelSettingsPath,
+			timeoutMs: opts.timeoutMs,
+		});
 	} catch (err) {
 		state.lastError = err instanceof Error ? err.message : String(err);
-		return;
+		return "failed";
 	}
 
 	if (models.length === 0) {
 		state.lastError = "OMLX returned 0 models";
-		clearRegisteredProvider(pi, state);
-		return;
+		return "failed";
 	}
 
-	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;
+	writeCatalogCache(config.apiRoot, models);
+	registerModels(pi, state, config, models, modelSettingsPath);
+	return "registered";
 }
 
-function findCatalogModel(state: State, id: string | undefined): OmlxModel | undefined {
+function findCatalogModel(
+	state: State,
+	id: string | undefined,
+): OmlxModel | undefined {
 	return id ? state.catalog.find((model) => model.id === id) : undefined;
 }
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		const timer = setTimeout(resolve, ms);
+		timer.unref?.();
+	});
+}

package/package.json

@@ -1,25 +1,39 @@
 {
-    "name": "pi-omlx-picker",
-    "version": "0.2.1",
-    "type": "module",
-    "description": "Pi extension that discovers models from a local OMLX server and registers them as a native Pi provider.",
-    "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"
-    }
+	"name": "pi-omlx-picker",
+	"version": "0.2.3",
+	"type": "module",
+	"description": "Pi extension that discovers models from a local OMLX server and registers them as a native Pi provider.",
+	"license": "MIT",
+	"keywords": [
+		"pi-package"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"scripts": {
+		"check": "biome check *.ts *.json src test scripts && tsc --noEmit && vitest run",
+		"format": "biome check --write *.ts *.json src test scripts",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"publish": "npm publish --access public"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.15",
+		"@earendil-works/pi-ai": "0.75.5",
+		"@earendil-works/pi-coding-agent": "0.75.5",
+		"@types/node": "^22.19.19",
+		"tsx": "^4.22.3",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.7"
+	}
 }

package/src/auth-storage.ts

@@ -1,16 +1,18 @@
 import {
 	type ApiKeyCredential,
 	AuthStorage,
-} from "@mariozechner/pi-coding-agent";
+	type OAuthCredential,
+} from "@earendil-works/pi-coding-agent";
 
 export const PROVIDER_KEY = "omlx";
 
 export interface OmlxStoredCredential {
-	baseUrl: string;
+	baseUrl?: string;
 	apiKey: string;
 }
 
 type OmlxApiKeyCredential = ApiKeyCredential & { baseUrl?: string };
+type OmlxOAuthCredential = OAuthCredential & { baseUrl?: string };
 
 let storage: AuthStorage | undefined;
 function getStorage(): AuthStorage {
@@ -25,10 +27,18 @@ export function _setStorageForTesting(s: AuthStorage | undefined): void {
 export function loadOmlxCredential(): OmlxStoredCredential | undefined {
 	const cred = getStorage().get(PROVIDER_KEY) as
 		| OmlxApiKeyCredential
+		| OmlxOAuthCredential
 		| undefined;
-	if (!cred || cred.type !== "api_key") return undefined;
-	if (!cred.baseUrl || !cred.key) return undefined;
-	return { baseUrl: cred.baseUrl, apiKey: cred.key };
+	if (!cred) return undefined;
+	if (cred.type === "api_key") {
+		if (!cred.key) return undefined;
+		return { baseUrl: cred.baseUrl, apiKey: cred.key };
+	}
+	if (cred.type === "oauth") {
+		if (!cred.access) return undefined;
+		return { baseUrl: cred.baseUrl, apiKey: cred.access };
+	}
+	return undefined;
 }
 
 export function saveOmlxCredential(baseUrl: string, apiKey: string): void {

package/src/catalog.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export interface OmlxModel {
 	id: string;
@@ -441,6 +442,45 @@ function applyModelSettingsEntry(
 	return next;
 }
 
+const CACHE_FILE = join(getAgentDir(), "cache", "omlx-models.json");
+
+interface CachedCatalog {
+	apiRoot: string;
+	models: OmlxModel[];
+	savedAt: number;
+}
+
+export function readCatalogCache(apiRoot: string): OmlxModel[] | undefined {
+	const data = readCatalogCacheFile();
+	if (!data || data.apiRoot !== apiRoot) return undefined;
+	return data.models;
+}
+
+export function readLastCatalogCache(): OmlxModel[] | undefined {
+	return readCatalogCacheFile()?.models;
+}
+
+function readCatalogCacheFile(): CachedCatalog | undefined {
+	try {
+		const raw = readFileSync(CACHE_FILE, "utf-8");
+		const data = JSON.parse(raw) as CachedCatalog;
+		if (!Array.isArray(data.models)) return undefined;
+		return data;
+	} catch {
+		return undefined;
+	}
+}
+
+export function writeCatalogCache(apiRoot: string, models: OmlxModel[]): void {
+	try {
+		mkdirSync(join(getAgentDir(), "cache"), { recursive: true });
+		const data: CachedCatalog = { apiRoot, models, savedAt: Date.now() };
+		writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+	} catch {
+		// Ignore write errors — cache is best-effort
+	}
+}
+
 export function resolveLocalModelSettingsPath(
 	modelSettingsPath: string | undefined,
 ): string | undefined {

package/src/config.ts

@@ -1,17 +1,12 @@
 import { loadOmlxCredential } from "./auth-storage.ts";
 
+export const DEFAULT_OMLX_BASE_URL = "http://127.0.0.1:8000/v1";
+
 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");
@@ -19,30 +14,35 @@ export function normalizeBaseUrl(raw: string): string {
 }
 
 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");
+	const stored = loadOmlxCredential();
+	const baseUrl = env.OMLX_BASE_URL
+		? env.OMLX_BASE_URL
+		: env.OMLX_API_KEY
+			? DEFAULT_OMLX_BASE_URL
+			: (stored?.baseUrl ?? DEFAULT_OMLX_BASE_URL);
 	return {
 		apiRoot: normalizeBaseUrl(baseUrl),
 		apiKeyEnvVar: "OMLX_API_KEY",
 	};
 }
 
-// Env vars win over stored creds so CI and per-shell overrides work.
+export function resolveConfiguredApiKey(
+	env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+	if (env.OMLX_API_KEY) return env.OMLX_API_KEY;
+	if (env.OMLX_BASE_URL) return undefined;
+	return loadOmlxCredential()?.apiKey;
+}
+
+// Legacy helper for older stored api_key credentials. Never fills only one side
+// of the env pair; partial shell overrides remain explicit shell state.
 export function applyStoredCredentialToEnv(
 	env: NodeJS.ProcessEnv = process.env,
 ): boolean {
-	if (env.OMLX_BASE_URL && env.OMLX_API_KEY) return false;
+	if (env.OMLX_BASE_URL || env.OMLX_API_KEY) return false;
 	const stored = loadOmlxCredential();
-	if (!stored) return false;
-	let applied = false;
-	if (!env.OMLX_BASE_URL) {
-		env.OMLX_BASE_URL = stored.baseUrl;
-		applied = true;
-	}
-	if (!env.OMLX_API_KEY) {
-		env.OMLX_API_KEY = stored.apiKey;
-		applied = true;
-	}
-	return applied;
+	if (!stored?.apiKey) return false;
+	env.OMLX_BASE_URL = stored.baseUrl ?? DEFAULT_OMLX_BASE_URL;
+	env.OMLX_API_KEY = stored.apiKey;
+	return true;
 }

package/src/provider.ts

@@ -8,11 +8,11 @@ import {
 	type Model,
 	type SimpleStreamOptions,
 	streamSimpleOpenAICompletions,
-} from "@mariozechner/pi-ai";
+} from "@earendil-works/pi-ai";
 import type {
 	ProviderConfig,
 	ProviderModelConfig,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 import type { OmlxModel } from "./catalog.ts";
 
 // Pi's documented defaults when the server doesn't report per-model values.

package/.biomeignore

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

package/.github/dependabot.yml

@@ -1,11 +0,0 @@
-# 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/CONTRIBUTING.md

@@ -1,52 +0,0 @@
-# Contributing
-
-Local development for `pi-omlx-picker`. User config: [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
-
-## Setup
-
-```sh
-npm install
-mise run verify
-```
-
-A live OMLX server is needed for `mise run smoke:omlx` and `mise run verify:live`.
-
-## Tasks
-
-Run via [`mise`](https://mise.jdx.dev/):
-
-- `mise run verify` — Biome, TypeScript type checking, unit tests.
-- `mise run smoke:omlx` — live OMLX probe: reasoning model, non-thinking model, tool-flow request.
-- `mise run verify:live` — typecheck, unit tests, and live smoke (skips Biome; run `mise run verify` first if you want lint coverage).
-- `mise run debug:omlx` — OMLX config, model path, template, log, and cache diagnostics. Pass model names after `--` to narrow, e.g. `mise run debug:omlx -- opus sonnet`.
-- `mise run debug:pi` — Pi install, config, session, log, and cache diagnostics. Pass `install`, `config`, `sessions`, `logs`, or `cache` after `--`.
-- `mise run debug:pi -- timeline <session-id|session-file|iso-time>` — Pi provider + OMLX server + changed-files window around a stuck turn. Use `--minutes=N` to set the window (default 3).
-
-## Triage order
-
-1. Read the latest provider events in `log/provider-debug.log` (or `~/.pi/packages/pi-omlx-picker/log/provider-debug.log` when installed via Pi). Look for `stream_first_delta_timeout`, `assistant_stop_diagnosis`, and the most recent `before_provider_request` / `after_provider_response` pair. The latest `mise run smoke:omlx` proof lives in `log/smoke-test/<iso-timestamp>.json`.
-2. Inspect Pi host state: `mise run debug:pi`.
-3. Inspect OMLX config and model files: `mise run debug:omlx`.
-4. Run live smoke: `mise run smoke:omlx`.
-5. Check upstream OMLX repo releases and issues before writing local workarounds.
-6. Only then change code.
-
-Most fixes are upstream (OMLX `model_settings.json`, `chat_template.jinja`), not in Pi-side code. New-session-OK plus takeover-broken means session state, not model capacity.
-
-## Failure families
-
-```text
-symptom
-  ├─ package didn't load, wrong install, stale session, compaction, takeover
-  │   └─ mise run debug:pi
-  ├─ model alias, model settings, template, rope config, OMLX/HF cache
-  │   └─ mise run debug:omlx
-  ├─ live model request behavior
-  │   └─ mise run smoke:omlx
-  ├─ new session good, takeover bad
-  │   └─ mise run debug:pi -- sessions, then compare model_settings.json and chat_template.jinja
-  ├─ local checks pass but live smoke fails
-  │   └─ check upstream OMLX repo, releases, and issues
-  └─ model not appearing in Pi /model list
-      └─ check OMLX_BASE_URL is reachable, then mise run debug:omlx
-```