pi-mtplx 0.1.7 → 0.1.9

package/README.md

@@ -24,8 +24,8 @@ If you pick an MTPLX model that isn't installed, the server won't start — Pi w
 
 Once installed, Pi automatically manages your MTPLX workflow:
 
-- **Model discovery** — `/mtplx` → **Models** scans what you've downloaded (`mtplx list`) and registers any of them with Pi. No model is bundled or pre-hardcoded: each Pi model id and its capabilities (context window, vision, reasoning) are derived live from the installed artifact, so models beyond the MTPLX stock set work too.
-- **Auto-start** — The MTPLX server starts when you switch to an `mtplx` model and shuts down cleanly when Pi exits.
+- **Model discovery** — `/mtplx` → **Models** scans what you've downloaded (`mtplx list`) and registers any of them with Pi. Each Pi model ID comes from MTPLX's own `quickstart --dry-run` plan, while capabilities (context window, vision, reasoning) are read from the installed artifact. Models beyond the MTPLX stock set work too.
+- **Auto-start** — The MTPLX server starts when you switch to an `mtplx` model. Auto shutdown is on by default and can be changed in `/mtplx`.
 - **Token speed** — A `⚡N.N tk/s` indicator appears in the footer showing the generation speed of the last assistant turn.
 
 ## Commands
@@ -35,7 +35,9 @@ Run `/mtplx` to open an interactive menu:
 | Option | What it does |
 | -------- | ------------- |
 | **Toggle (on/off)** | Start or stop the MTPLX server |
+| **API Key** | View a masked identifier for, or replace, the API key Pi uses for the local MTPLX server |
 | **Fan Curves** | Set the thermal profile (`default`, `smart`, `max`) |
+| **Auto Shutdown** | Choose whether Pi stops MTPLX on `/quit` or a normal terminal-close shutdown (on by default) |
 | **SSD Session Cache** | Enable or disable MTPLX's SSD-backed session cache for subsequent server starts (on by default) |
 | **Models** | Register or unregister models — ✓ means registered (click to unregister), ✗ means available (click to register) |
 | **Uninstall** | Remove the `mtplx` provider from Pi's config |
@@ -46,17 +48,17 @@ Run `/mtplx` to open an interactive menu:
 
 ### Model registry
 
-Models are registered in `~/.pi/agent/mtplx-models.json`. Each entry maps a Pi model ID to an MTPLX artifact ref:
+Models are registered in `~/.pi/agent/mtplx-models.json`. Each entry maps MTPLX's canonical served model ID to an MTPLX artifact ref:
 
 ```json
 {
-  "mtplx-qwen3.8-27b-mtplx-optimized-quality": {
+  "mtplx-qwen38-27b-optimized-quality": {
     "ref": "Youssofal/Qwen3.8-27B-MTPLX-Optimized-Quality"
   }
 }
 ```
 
-Register new models via the `/mtplx` → **Models** menu, or add entries manually to this file. To activate a **newly added** model, restart Pi with `/quit` and relaunch it (`pi`), then open `/model` (or `/scoped-models`) — Pi reads this file at startup, so a brand-new model id won't show up in `/model` otherwise.
+Register new models via the `/mtplx` → **Models** menu; it asks MTPLX for the exact served ID. Opening this menu also migrates older ref-derived IDs to their canonical MTPLX names. Restart Pi after a migration or registration, then open `/model` (or `/scoped-models`) to activate the model.
 
 ### Fan mode
 
@@ -68,12 +70,22 @@ Controls the thermal profile of your MTPLX server. Saved to `~/.pi/agent/mtplx-f
 | `smart` | Default — adaptive thermal management |
 | `max` | Maximum fan, fastest inference |
 
+### Server authentication
+
+pi-mtplx always uses an API key. It uses `providers.mtplx.apiKey` from `~/.pi/agent/models.json` when configured; otherwise it uses the local default `mtplx-local`. The resolved key is passed to Pi-managed MTPLX startup and sent with health, fan-control, and inference requests. If Pi already has a stored MTPLX API-key credential, pi-mtplx synchronizes it with this key at startup and whenever `/mtplx` → **API Key** saves a change. Restart Pi after changing the key so its in-memory inference provider reloads the configuration. The menu only shows a masked suffix for custom keys, never the full secret.
+
+### Auto shutdown
+
+Auto shutdown is on by default. When enabled, pi-mtplx stops the managed MTPLX server when Pi exits via `/quit` or a normal terminal-close shutdown. Turn it off in `/mtplx` → **Auto Shutdown** to leave the loaded server running after Pi exits. It cannot handle abrupt termination such as `SIGKILL` or a power loss.
+
 ## Troubleshooting
 
 | Problem | Fix |
 | --------- | ----- |
 | **"MTPLX not started"** — Pi warns when you ask an MTPLX model to respond | Run `/mtplx` → **Toggle** to start the server |
 | **"No MTPLX models registered"** | Run `/mtplx` → **Models** to discover and register one |
+| **"MTPLX is already running ... but Pi requested ..."** | A manually started MTPLX server is serving a different, unmanaged model. Stop it in the MTPLX app, or find it with `lsof -nP -iTCP:8000 -sTCP:LISTEN` and run `kill -TERM <PID>`, then retry so Pi can start and manage the selected model. |
+| **"MTPLX rejected the API key"** | The running server requires a different key. Use `/mtplx` → **API Key** to enter its current key, then retry. |
 | **MTPLX startup timed out after 180s** | Run `mtplx status --deep` for MTPLX-side diagnostics (model validation, memory, thermal) |
 
 ## License

package/extensions/mtplx.ts

@@ -7,22 +7,30 @@
  * agent_end and session_shutdown, plus the /mtplx command.
  */
 import { acquire, release, stopServer } from "../src/mtplx-process.ts";
-import { getFanMode, health, setFanMode, setFanModeValue } from "../src/mtplx-client.ts";
+import { authenticationFailureMessage, getFanMode, health, healthProbe, setFanMode, setFanModeValue } from "../src/mtplx-client.ts";
 import { MTPLX_PROVIDER, manageModels, removeModel, removePiMtplxProvider } from "../src/model-discovery.ts";
-import { FAN_MODES, isMtplxModel, loadSsdSessionCache, saveFanMode, saveSsdSessionCache, type FanMode } from "../src/utils.ts";
+import { FAN_MODES, isMtplxModel, loadAutoShutdown, loadMtplxApiKey, loadSsdSessionCache, maskMtplxApiKey, saveAutoShutdown, saveFanMode, saveMtplxApiKey, saveSsdSessionCache, syncMtplxStoredCredential, type FanMode } from "../src/utils.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export default function mtplxAutostart(pi: ExtensionAPI): void {
+	// Pi's runtime may already have loaded auth.json for this process, but
+	// syncing here ensures its next launch uses the same key as models.json.
+	syncMtplxStoredCredential();
+
 	pi.registerCommand("mtplx", {
-		description: "MTPLX — toggle the server, configure fan and SSD cache, manage models, or uninstall",
+		description: "MTPLX — toggle the server, configure API key, fan, shutdown, and SSD cache, manage models, or uninstall",
 		handler: async (_args, ctx) => {
 			const current = await health();
 			const status = current ? "on" : "off";
 			await ctx.ui.setStatus("mtplx", `MTPLX: ${status}`);
 			const ssdSessionCache = loadSsdSessionCache();
+			const autoShutdown = loadAutoShutdown();
+			const apiKeyLabel = maskMtplxApiKey(loadMtplxApiKey());
 			const topChoices = [
 				`Toggle (${status})`,
+				`API Key (current: ${apiKeyLabel})`,
 				`Fan Curves (current: ${getFanMode()})`,
+				`Auto Shutdown (current: ${autoShutdown ? "on" : "off"})`,
 				`SSD Session Cache (current: ${ssdSessionCache ? "on" : "off"})`,
 				"Models",
 				"Uninstall (remove provider)",
@@ -41,6 +49,23 @@ export default function mtplxAutostart(pi: ExtensionAPI): void {
 				}
 				return;
 			}
+			if (top.startsWith("API Key")) {
+				const apiKey = await ctx.ui.input(`MTPLX API Key — current: ${apiKeyLabel}`, "Paste a custom key, or leave blank for the default (visible while typing)");
+				if (apiKey === undefined) return;
+				if (!saveMtplxApiKey(apiKey)) {
+					ctx.ui.notify("MTPLX API key was not updated. Check that models.json is valid.", "error");
+					return;
+				}
+				const probe = await healthProbe();
+				if (probe.health) {
+					ctx.ui.notify("MTPLX API key updated and verified against the running server. Restart Pi before inference requests use the new key.", "info");
+				} else if (probe.authenticationRejected) {
+					ctx.ui.notify(`MTPLX API key was saved, but verification failed: ${authenticationFailureMessage()} Restart Pi after correcting it.`, "error");
+				} else {
+					ctx.ui.notify("MTPLX API key updated. No running server was available to verify it. Restart Pi before inference requests use the new key.", "warning");
+				}
+				return;
+			}
 			if (top.startsWith("Fan Curves")) {
 				const choices = FAN_MODES.map((mode) => (mode === getFanMode() ? `${mode} (current)` : mode));
 				const picked = await ctx.ui.select("MTPLX — fan mode for autostart", choices, undefined);
@@ -54,6 +79,17 @@ export default function mtplxAutostart(pi: ExtensionAPI): void {
 				}
 				ctx.ui.notify(`MTPLX fan mode set to ${getFanMode()}`, "info");
 			}
+			if (top.startsWith("Auto Shutdown")) {
+				const choices = [
+					autoShutdown ? "Off" : "Off (current)",
+					autoShutdown ? "On (current)" : "On",
+				];
+				const picked = await ctx.ui.select("MTPLX — stop the server when Pi exits", choices, undefined);
+				if (!picked) return;
+				const enabled = picked.startsWith("On");
+				saveAutoShutdown(enabled);
+				ctx.ui.notify(`MTPLX will ${enabled ? "stop automatically" : "keep running"} when Pi exits.`, "info");
+			}
 			if (top.startsWith("SSD Session Cache")) {
 				const choices = [
 					ssdSessionCache ? "Off" : "Off (current)",
@@ -98,11 +134,11 @@ export default function mtplxAutostart(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_shutdown", async (event) => {
-		if (event.reason !== "quit") return;
+		if (event.reason !== "quit" || !loadAutoShutdown()) return;
 		try {
 			await stopServer();
 		} catch (error) {
-			console.error(`MTPLX cleanup on quit failed: ${error instanceof Error ? error.message : String(error)}`);
+			console.error(`MTPLX auto-shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-mtplx",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"description": "Zero-config MTPLX integration for Pi coding agent",
 	"keywords": [
 		"pi-package",

package/src/model-discovery.ts

@@ -1,20 +1,18 @@
 /**
  * MTPLX model registry: Pi model id → installed MTPLX artifact ref.
  *
- * The refs are the artifact identifiers reported by `mtplx models --json`;
- * `--model-id` makes /health and /v1/models report Pi's id.
+ * The refs are the artifact identifiers reported by `mtplx list --json`.
+ * MTPLX's `quickstart --dry-run --json` supplies the canonical served id used
+ * by Pi, /health, and /v1/models.
  *
  * The extension ships no model weights and hard-codes no model. The registry
  * holds only models registered through `/mtplx`, persisted to
- * ~/.pi/agent/mtplx-models.json; each Pi model id is derived live from the
- * artifact's ref (see modelIdFromRef) so models.json, enabledModels and this
- * registry always agree on the id.
+ * ~/.pi/agent/mtplx-models.json; models.json, enabledModels and this registry
+ * use the same MTPLX-supplied id.
  *
- * Pi's model catalog is the USER's own ~/.pi/agent/models.json — a provider
- * config that pre-existed this package (created by `mtplx start pi` / the
- * /mtplx UI). The canonical provider name is MTPLX's own `mtplx`
- * (PI_PROVIDER_ID in MTPLX's mtplx/pi.py); this extension reads and writes
- * only that provider entry and leaves every other provider untouched.
+ * Pi's model catalog lives in ~/.pi/agent/models.json. The canonical provider
+ * name is `mtplx`; this extension reads and writes only that provider entry
+ * and leaves every other provider untouched.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
@@ -22,12 +20,11 @@ import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { modelIdFromRef, displayNameFromId } from "./utils.ts";
+import { displayNameFromId } from "./utils.ts";
 
 const execFileAsync = promisify(execFile);
 
-// Matches MTPLX's own PI_PROVIDER_ID ("mtplx") so the extension operates on
-// the exact provider block that `mtplx start pi` creates.
+// Keep the provider name consistent across model registration and lifecycle handling.
 export const MTPLX_PROVIDER = "mtplx";
 const MODELS_FILE = join(homedir(), ".pi", "agent", "mtplx-models.json");
 const SETTINGS_FILE = join(homedir(), ".pi", "agent", "settings.json");
@@ -101,6 +98,9 @@ export function disableModelInSettings(modelId: string): boolean {
 	}
 }
 type MtplxListedModel = { repo_id?: unknown; path?: unknown; name?: unknown };
+type ResolvedMtplxModel = { model: MtplxListedModel; ref: string; id: string };
+
+const servedIdCache = new Map<string, string>();
 
 export async function listMtplxModels(): Promise<MtplxListedModel[]> {
 	try {
@@ -117,6 +117,28 @@ export function listedIdentity(model: MtplxListedModel): string {
 	return typeof model.repo_id === "string" && model.repo_id ? model.repo_id : typeof model.path === "string" ? model.path : "";
 }
 
+/**
+ * MTPLX itself chooses the default served id. `mtplx list` reports artifact
+ * refs, not that id, so ask quickstart for its dry-run plan rather than trying
+ * to reproduce its naming rules in Pi.
+ */
+export async function servedModelId(ref: string): Promise<string> {
+	const cached = servedIdCache.get(ref);
+	if (cached) return cached;
+	const { stdout } = await execFileAsync("mtplx", ["quickstart", "--model", ref, "--dry-run", "--json"], { timeout: 30_000 });
+	const id = servedModelIdFromDryRun(JSON.parse(stdout) as unknown);
+	servedIdCache.set(ref, id);
+	return id;
+}
+
+/** Parse the model id from MTPLX's machine-readable quickstart plan. */
+export function servedModelIdFromDryRun(plan: unknown): string {
+	if (typeof plan !== "object" || plan === null || typeof (plan as { model_id?: unknown }).model_id !== "string" || !(plan as { model_id: string }).model_id) {
+		throw new Error("MTPLX did not return a served model id");
+	}
+	return (plan as { model_id: string }).model_id;
+}
+
 /**
  * Model ids currently present in the `mtplx` provider of Pi's catalog
  * (models.json). This is the source of truth for whether a model is actually
@@ -135,6 +157,68 @@ function catalogModelIds(): string[] {
 	}
 }
 
+/**
+ * Replace legacy ref-derived ids with MTPLX's own served ids. This runs only
+ * from the explicit Models menu, where the resulting Pi restart is expected.
+ */
+function migrateRegisteredModelIds(models: readonly ResolvedMtplxModel[]): string[] {
+	const servedIds = new Map(models.map(({ ref, id }) => [ref, id]));
+	const changes = new Map<string, string>();
+	for (const [oldId, entry] of Object.entries(MTPLX_MODELS)) {
+		const newId = servedIds.get(entry.ref);
+		if (!newId || newId === oldId) continue;
+		const collision = MTPLX_MODELS[newId];
+		if (collision && collision.ref !== entry.ref) {
+			console.warn(`pi-mtplx: cannot migrate ${oldId} to ${newId}; that id is already assigned to a different artifact.`);
+			continue;
+		}
+		changes.set(oldId, newId);
+	}
+	if (changes.size === 0) return [];
+
+	try {
+		const modelsJsonPath = join(homedir(), ".pi", "agent", "models.json");
+		const catalog = JSON.parse(readFileSync(modelsJsonPath, "utf8")) as { providers?: Record<string, unknown> };
+		const provider = catalog.providers?.[MTPLX_PROVIDER] as { models?: Record<string, unknown>[] } | undefined;
+		if (provider && Array.isArray(provider.models)) {
+			const seen = new Set<string>();
+			provider.models = provider.models.flatMap((model) => {
+				const id = typeof model.id === "string" ? model.id : undefined;
+				const replacement = id ? changes.get(id) : undefined;
+				const nextId = replacement ?? id;
+				if (!nextId || seen.has(nextId)) return [];
+				seen.add(nextId);
+				return [{ ...model, id: nextId, ...(replacement ? { name: displayNameFromId(nextId) } : {}) }];
+			});
+		}
+		writeFileSync(modelsJsonPath, JSON.stringify(catalog, null, 2) + "\n");
+
+		if (existsSync(SETTINGS_FILE)) {
+			const settings = JSON.parse(readFileSync(SETTINGS_FILE, "utf8")) as { enabledModels?: unknown };
+			if (Array.isArray(settings.enabledModels)) {
+				settings.enabledModels = [...new Set(settings.enabledModels.map((entry) => {
+					if (typeof entry !== "string") return entry;
+					const id = entry.startsWith(`${MTPLX_PROVIDER}/`) ? entry.slice(MTPLX_PROVIDER.length + 1) : undefined;
+					return id && changes.has(id) ? `${MTPLX_PROVIDER}/${changes.get(id)}` : entry;
+				}))];
+				writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+			}
+		}
+
+		for (const [oldId, newId] of changes) {
+			const entry = MTPLX_MODELS[oldId];
+			if (!entry) continue;
+			MTPLX_MODELS[newId] = entry;
+			delete MTPLX_MODELS[oldId];
+		}
+		saveRegisteredModels();
+		return [...changes].map(([oldId, newId]) => `${oldId} → ${newId}`);
+	} catch (error) {
+		console.error(`pi-mtplx could not migrate MTPLX model ids: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}
+
 type ModelProfile = {
 	contextWindow: number;
 	maxTokens: number;
@@ -197,13 +281,23 @@ export async function manageModels(ctx: ExtensionContext): Promise<boolean> {
 		ctx.ui.notify("No MTPLX models found. Install one with `mtplx install`.", "warning");
 		return false;
 	}
+	let resolved: ResolvedMtplxModel[];
+	try {
+		resolved = [];
+		for (const model of installed) {
+			const ref = listedIdentity(model);
+			if (ref) resolved.push({ model, ref, id: await servedModelId(ref) });
+		}
+	} catch (error) {
+		ctx.ui.notify(`Could not read MTPLX's served model id: ${error instanceof Error ? error.message : String(error)}`, "error");
+		return false;
+	}
+	const migrated = migrateRegisteredModelIds(resolved);
+	if (migrated.length > 0) {
+		ctx.ui.notify(`Updated registered model IDs to MTPLX's canonical names. Restart Pi before selecting them.`, "info");
+	}
 	const catalog = new Set(catalogModelIds());
-	const choices = installed.map((model) => {
-		const ref = listedIdentity(model);
-		// Each artifact maps to exactly one Pi model id, derived live from its ref.
-		// No hard-coded ids — the same id is written to models.json, enabledModels and
-		// the registry so the three never drift apart.
-		const id = modelIdFromRef(ref);
+	const choices = resolved.map(({ ref, id }) => {
 		// ✓ means registered in Pi's catalog (models.json); ✗ means just installed in MTPLX.
 		const mark = catalog.has(id) ? "✓" : "✗";
 		return `${mark} ${id} — ${ref}`;
@@ -212,9 +306,10 @@ export async function manageModels(ctx: ExtensionContext): Promise<boolean> {
 	const picked = await ctx.ui.select("MTPLX models — ✓ registered in Pi · ✗ available in MTPLX — registering a new model needs a Pi restart (/quit → pi) to show up in /model", choices, undefined);
 	if (!picked || picked === "Cancel") return false;
 	const ref = picked.split(" — ").slice(1).join(" — ");
-	const modelId = modelIdFromRef(ref);
 	// The installed-model record for the chosen artifact (used to read its live metadata).
-	const chosen = installed.find((m) => listedIdentity(m) === ref);
+	const selected = resolved.find((entry) => entry.ref === ref);
+	if (!selected) return false;
+	const { model: chosen, id: modelId } = selected;
 
 	if (catalog.has(modelId)) {
 		// Unregister: remove from models.json, enabledModels, and the id→ref registry.
@@ -349,4 +444,4 @@ export function removePiMtplxProvider(): boolean {
 		console.error(`pi-mtplx uninstall could not update models.json: ${error instanceof Error ? error.message : String(error)}`);
 		return false;
 	}
-}
+}

package/src/mtplx-client.ts

@@ -4,9 +4,10 @@
  *   GET  /health
  *   POST /v1/mtplx/thermal/fan_mode
  */
-import { HOST, PORT, type FanMode, loadFanMode } from "./utils.ts";
+import { HOST, PORT, type FanMode, loadFanMode, loadResolvedMtplxApiKey } from "./utils.ts";
 
 export type Health = { ok: true; model: string; model_path?: string; fan_mode?: string };
+export type HealthProbe = { health: Health | undefined; authenticationRejected?: true };
 
 // Current fan curve for autostart and live updates. Loaded from disk so the
 // choice survives Pi restarts (see FANMODE_FILE in utils.ts).
@@ -20,37 +21,66 @@ export function setFanModeValue(mode: FanMode): void {
 	fanMode = mode;
 }
 
-export async function health(): Promise<Health | undefined> {
+/**
+ * Pi's own model requests use the configured key, or pi-mtplx's deterministic
+ * local fallback. Mirror that header for every lifecycle endpoint.
+ */
+function authRequest(): { headers: Record<string, string> } {
+	return { headers: { authorization: `Bearer ${loadResolvedMtplxApiKey()}` } };
+}
+
+export function authenticationFailureMessage(): string {
+	return "MTPLX rejected Pi's API key. Update it via /mtplx → API Key.";
+}
+
+export async function healthProbe(): Promise<HealthProbe> {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), 1_500);
 	try {
-		const response = await fetch(`http://${HOST}:${PORT}/health`, { signal: controller.signal });
-		if (!response.ok) return undefined;
+		const auth = authRequest();
+		const response = await fetch(`http://${HOST}:${PORT}/health`, {
+			headers: auth.headers,
+			signal: controller.signal,
+		});
+		if (response.status === 401 || response.status === 403) {
+			return { health: undefined, authenticationRejected: true };
+		}
+		if (!response.ok) return { health: undefined };
 		const body = (await response.json()) as { ok?: unknown; model?: unknown; model_path?: unknown; fan_mode?: unknown };
-		if (body.ok !== true || typeof body.model !== "string") return undefined;
+		if (body.ok !== true || typeof body.model !== "string") return { health: undefined };
 		return {
-			ok: true,
-			model: body.model,
-			model_path: typeof body.model_path === "string" ? body.model_path : undefined,
-			fan_mode: typeof body.fan_mode === "string" ? body.fan_mode : undefined,
+			health: {
+				ok: true,
+				model: body.model,
+				model_path: typeof body.model_path === "string" ? body.model_path : undefined,
+				fan_mode: typeof body.fan_mode === "string" ? body.fan_mode : undefined,
+			},
 		};
 	} catch {
-		return undefined;
+		return { health: undefined };
 	} finally {
 		clearTimeout(timeout);
 	}
 }
 
+export async function health(): Promise<Health | undefined> {
+	return (await healthProbe()).health;
+}
+
 export async function setFanMode(): Promise<void> {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), 10_000);
 	try {
+		const auth = authRequest();
 		const response = await fetch(`http://${HOST}:${PORT}/v1/mtplx/thermal/fan_mode`, {
 			method: "POST",
-			headers: { "content-type": "application/json" },
+			headers: { "content-type": "application/json", ...auth.headers },
 			body: JSON.stringify({ mode: fanMode }),
 			signal: controller.signal,
 		});
+		if (response.status === 401 || response.status === 403) {
+			throw new Error(authenticationFailureMessage());
+		}
 		const body = (await response.json()) as { verified?: unknown; current_mode?: unknown; error?: unknown };
 		if (!response.ok || body.verified !== true || body.current_mode !== fanMode) {
 			throw new Error(`MTPLX fan mode could not be set to ${fanMode}: ${typeof body.error === "string" ? body.error : "unverified response"}`);
@@ -60,4 +90,4 @@ export async function setFanMode(): Promise<void> {
 	} finally {
 		clearTimeout(timeout);
 	}
-}
+}

package/src/mtplx-process.ts

@@ -12,16 +12,17 @@
  *     ids. A foreign service on the port is never touched, and a manually
  *     started MTPLX server (no matching --model-id fingerprint) is never
  *     killed — it is simply served from as-is.
- *   - Stop goes through `mtplx stop --host --port --json` (MTPLX's own
- *     graceful-stop mechanism: SIGTERM → grace → SIGKILL), which targets the
- *     server answering on that exact host:port, not arbitrary processes.
+ *   - A server launched by this Pi session is stopped through its own detached
+ *     process group. This avoids relying on a second `mtplx` CLI invocation
+ *     during shutdown. A positively identified server from an earlier Pi
+ *     session still uses MTPLX's host-and-port stop command.
  */
 import { spawn, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import type { ChildProcess } from "node:child_process";
-import { getFanMode, health, setFanMode, type Health } from "./mtplx-client.ts";
+import { authenticationFailureMessage, getFanMode, health, healthProbe, setFanMode } from "./mtplx-client.ts";
 import { MTPLX_MODELS } from "./model-discovery.ts";
-import { HOST, PORT, READY_TIMEOUT_MS, POLL_MS, loadSsdSessionCache, sleep, commandError, portIsOccupied } from "./utils.ts";
+import { HOST, PORT, READY_TIMEOUT_MS, POLL_MS, loadResolvedMtplxApiKey, loadSsdSessionCache, sleep, commandError, portIsOccupied } from "./utils.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -47,9 +48,11 @@ export function startupError(cause: Error): Error {
  * a kill target.
  */
 export async function stopServer(): Promise<void> {
-	const current = await health();
+	const probe = await healthProbe();
+	const current = probe.health;
 	if (!current) {
 		if (await portIsOccupied()) {
+			if (probe.authenticationRejected) throw new Error(authenticationFailureMessage());
 			throw new Error(`MTPLX cannot use ${HOST}:${PORT}: another, non-MTPLX service is listening there.`);
 		}
 		// Nothing listening (or not MTPLX): nothing to stop. Drop any stale handle.
@@ -70,19 +73,52 @@ export async function stopServer(): Promise<void> {
 		return;
 	}
 
-	try {
-		await execFileAsync("mtplx", ["stop", "--host", HOST, "--port", String(PORT), "--json"], { timeout: 20_000 });
-	} catch (error) {
-		throw new Error(`MTPLX shutdown failed: ${commandError(error)}`);
+	let stopError: unknown;
+	const childPid = ownedChild?.pid;
+	let signalledOwnedProcess = false;
+	if (isOwnedByThisSession() && childPid) {
+		try {
+			// `detached: true` gives this child its own POSIX process group. Signal
+			// that group so a quickstart wrapper and its server are stopped together.
+			process.kill(-childPid, "SIGTERM");
+			signalledOwnedProcess = true;
+		} catch (error) {
+			// The child may have already exited while its server survived. In that
+			// case, fall through to MTPLX's host-and-port stop command below.
+			if (!(error && typeof error === "object" && "code" in error && error.code === "ESRCH")) {
+				stopError = error;
+			}
+		}
+	}
+
+	if (!isOwnedByThisSession() && await signalMtplxListener()) {
+		signalledOwnedProcess = true;
+	}
+
+	if (!signalledOwnedProcess) {
+		try {
+			await execFileAsync("mtplx", ["stop", "--host", HOST, "--port", String(PORT), "--json"], { timeout: 20_000 });
+			stopError = undefined;
+		} catch (error) {
+			// Some MTPLX CLI failures occur after it has already signalled the server.
+			// Confirm the listener state before reporting shutdown as failed.
+			stopError = error;
+		}
 	}
-	ownedChild = undefined;
 
 	const deadline = Date.now() + 20_000;
 	while (Date.now() < deadline) {
-		if (!(await health())) return;
+		if (!(await portIsOccupied())) {
+			ownedChild = undefined;
+			return;
+		}
 		await sleep(POLL_MS);
 	}
-	throw new Error(`MTPLX shutdown timed out; ${HOST}:${PORT} is still healthy.`);
+	if (stopError) throw new Error(`MTPLX shutdown failed: ${commandError(stopError)}`);
+	if (signalledOwnedProcess) {
+		throw new Error(`MTPLX shutdown timed out after signalling Pi's server process; ${HOST}:${PORT} is still occupied.`);
+	}
+	throw new Error(`MTPLX shutdown timed out; ${HOST}:${PORT} is still occupied.`);
 }
 
 /** Positive ownership fingerprint: /health model id belongs to this extension's registry. */
@@ -90,6 +126,34 @@ function currentModelIsOurs(model: string): boolean {
 	return Object.keys(MTPLX_MODELS).includes(model);
 }
 
+/**
+ * Signal the process listening on the managed MTPLX port. This is used only
+ * after an authenticated health check and a pi-mtplx model fingerprint have
+ * proved the listener is one we are allowed to stop. It covers a server that
+ * a previous Pi session left running, which has no child handle in this one.
+ */
+async function signalMtplxListener(): Promise<boolean> {
+	try {
+		const { stdout } = await execFileAsync("lsof", ["-t", "-nP", `-iTCP:${PORT}`, "-sTCP:LISTEN"], { timeout: 5_000 });
+		const pids = stdout
+			.split(/\s+/)
+			.map(Number)
+			.filter((pid) => Number.isSafeInteger(pid) && pid > 0);
+		if (pids.length === 0) return false;
+		for (const pid of pids) process.kill(pid, "SIGTERM");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function unmanagedServerModelError(runningModel: string, requestedModel: string): Error {
+	return new Error(
+		`MTPLX is already running on ${HOST}:${PORT} with model ${JSON.stringify(runningModel)}, but Pi requested ${JSON.stringify(requestedModel)}. ` +
+		`Pi will not replace this server because it is not managed by pi-mtplx. Stop it from the MTPLX app, or identify its listener with \`lsof -nP -iTCP:${PORT} -sTCP:LISTEN\` and run \`kill -TERM <PID>\`; then retry so Pi can start and manage the requested model.`,
+	);
+}
+
 /**
  * Spawn the MTPLX server for a registered model and wait until /health
  * confirms it serves exactly that model. The child is spawned detached so it
@@ -101,27 +165,28 @@ export async function startServer(modelId: string): Promise<void> {
 		throw new Error(`MTPLX model ${JSON.stringify(modelId)} is not mapped to an installed MTPLX artifact. Update the pi-mtplx model registry after adding it to Pi.`);
 	}
 
+	const args = [
+		"quickstart",
+		"--model",
+		configured.ref,
+		"--model-id",
+		modelId,
+		"--fan-mode",
+		getFanMode(),
+		"--host",
+		HOST,
+		"--port",
+		String(PORT),
+		// Explicitly pass the user's persisted choice; this extension defaults it to on.
+		"--ssd-session-cache",
+		loadSsdSessionCache() ? "on" : "off",
+	];
+	args.push("--api-key", loadResolvedMtplxApiKey());
+
 	let exited: Error | undefined;
 	const child = spawn(
 		"mtplx",
-		[
-			"quickstart",
-			"--model",
-			configured.ref,
-			"--model-id",
-			modelId,
-			"--profile",
-			"sustained",
-			"--fan-mode",
-			getFanMode(),
-			"--host",
-			HOST,
-			"--port",
-			String(PORT),
-			// Explicitly pass the user's persisted choice; this extension defaults it to on.
-			"--ssd-session-cache",
-			loadSsdSessionCache() ? "on" : "off",
-		],
+		args,
 		{ detached: true, stdio: "ignore" },
 	);
 	ownedChild = child;
@@ -152,13 +217,20 @@ export async function startServer(modelId: string): Promise<void> {
  * models: stop the current (identified) server, then start the requested one.
  */
 export async function ensureServer(modelId: string): Promise<void> {
-	const current = await health();
+	const probe = await healthProbe();
+	const current = probe.health;
 	if (current?.model === modelId) {
 		if (current.fan_mode !== getFanMode()) await setFanMode();
 		return;
 	}
-	if (current) await stopServer();
+	if (current) {
+		if (!isOwnedByThisSession() && !currentModelIsOurs(current.model)) {
+			throw unmanagedServerModelError(current.model, modelId);
+		}
+		await stopServer();
+	}
 	else if (await portIsOccupied()) {
+		if (probe.authenticationRejected) throw new Error(authenticationFailureMessage());
 		throw new Error(`MTPLX cannot start because ${HOST}:${PORT} is occupied by a non-MTPLX service.`);
 	}
 	await startServer(modelId);

package/src/utils.ts

@@ -1,7 +1,7 @@
 /**
  * Shared constants and small helpers for the pi-mtplx extension.
  */
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -10,10 +10,14 @@ export const HOST = "127.0.0.1";
 export const PORT = 8000;
 export const READY_TIMEOUT_MS = 180_000;
 export const POLL_MS = 500;
+export const PI_MODELS_FILE = join(homedir(), ".pi", "agent", "models.json");
+export const PI_AUTH_FILE = join(homedir(), ".pi", "agent", "auth.json");
 
 export type FanMode = "default" | "smart" | "max";
 export const FAN_MODES: readonly FanMode[] = ["default", "smart", "max"];
 export const DEFAULT_SSD_SESSION_CACHE = true;
+export const DEFAULT_AUTO_SHUTDOWN = true;
+export const DEFAULT_MTPLX_API_KEY = "mtplx-local";
 
 // Fan mode ("fan curve") applied at autostart, live-updated from `/mtplx` while the
 // server runs. Persisted to disk so the choice survives Pi restarts: `fanMode` is a
@@ -66,17 +70,137 @@ export function saveSsdSessionCache(enabled: boolean): void {
 	}
 }
 
-// Derive Pi's model id from an artifact ref: "Youssofal/Qwen3.8-27B-MTPLX-Optimized-Quality"
-// → "mtplx-qwen38-27b-optimized-quality" (same scheme as the built-in entry).
-export function modelIdFromRef(ref: string): string {
-	const slug = ref
-		.split("/")
-		.pop() ?? ref
-		.replace(/^mtplx/i, "")
-		.replace(/[^a-zA-Z0-9]+/g, "-")
-		.replace(/-+/g, "-")
-		.replace(/^-|-$/g, "");
-	return `mtplx-${slug || "model"}`.toLowerCase();
+// Whether Pi should stop the server during a normal process shutdown. Kept
+// separate from the server's own settings so users can deliberately leave a
+// loaded model available after Pi exits.
+export const AUTO_SHUTDOWN_FILE = join(homedir(), ".pi", "agent", "mtplx-auto-shutdown.json");
+
+export function loadAutoShutdown(): boolean {
+	try {
+		const parsed = JSON.parse(readFileSync(AUTO_SHUTDOWN_FILE, "utf8")) as { enabled?: unknown };
+		if (typeof parsed.enabled === "boolean") return parsed.enabled;
+	} catch {
+		// missing or corrupt file → default to cleaning up the Pi-managed server
+	}
+	return DEFAULT_AUTO_SHUTDOWN;
+}
+
+export function saveAutoShutdown(enabled: boolean): void {
+	try {
+		mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
+		writeFileSync(AUTO_SHUTDOWN_FILE, JSON.stringify({ enabled }, null, 2) + "\n");
+	} catch (error) {
+		console.error(`MTPLX could not persist auto-shutdown preference: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** Read the provider-level key Pi uses for requests to the local MTPLX server. */
+export function mtplxApiKeyFromCatalog(catalog: unknown): string | undefined {
+	if (typeof catalog !== "object" || catalog === null) return undefined;
+	const providers = (catalog as { providers?: unknown }).providers;
+	if (typeof providers !== "object" || providers === null) return undefined;
+	const provider = (providers as { mtplx?: unknown }).mtplx;
+	if (typeof provider !== "object" || provider === null) return undefined;
+	const apiKey = (provider as { apiKey?: unknown }).apiKey;
+	return typeof apiKey === "string" && apiKey.trim() ? apiKey.trim() : undefined;
+}
+
+/**
+ * Lifecycle calls reread this on every request. Pi's inference provider has
+ * its own in-memory catalog, so a key changed here still requires a Pi restart
+ * before model requests use it.
+ */
+export function loadMtplxApiKey(): string | undefined {
+	try {
+		return mtplxApiKeyFromCatalog(JSON.parse(readFileSync(PI_MODELS_FILE, "utf8")) as unknown);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Every Pi-managed MTPLX connection has a deterministic key. */
+export function resolveMtplxApiKey(apiKey: string | undefined): string {
+	return apiKey ?? DEFAULT_MTPLX_API_KEY;
+}
+
+export function loadResolvedMtplxApiKey(): string {
+	return resolveMtplxApiKey(loadMtplxApiKey());
+}
+
+/** A stable, non-secret identifier suitable for the interactive menu. */
+export function maskMtplxApiKey(apiKey: string | undefined): string {
+	if (!apiKey) return `default (${DEFAULT_MTPLX_API_KEY})`;
+	return apiKey.length <= 4 ? "configured" : `••••${apiKey.slice(-4)}`;
+}
+
+/**
+ * Pi gives a stored `auth.json` API-key credential precedence over models.json.
+ * Keep an existing MTPLX credential in sync; do not create one, because the
+ * provider-level key is sufficient when no stored credential exists.
+ */
+function syncStoredMtplxCredential(apiKey: string): void {
+	if (!existsSync(PI_AUTH_FILE)) return;
+	const parsed = JSON.parse(readFileSync(PI_AUTH_FILE, "utf8")) as Record<string, unknown>;
+	// Current Pi stores credentials directly as { "mtplx": { ... } }. Accept
+	// the older nested shape too, without changing either file's structure.
+	const credentials = typeof parsed.auth === "object" && parsed.auth !== null && !Array.isArray(parsed.auth)
+		? parsed.auth as Record<string, unknown>
+		: parsed;
+	const credential = credentials.mtplx;
+	if (credential === undefined) return;
+	if (typeof credential !== "object" || credential === null || Array.isArray(credential) || (credential as { type?: unknown }).type !== "api_key") {
+		throw new Error("auth.json contains an MTPLX credential that is not an API key");
+	}
+	(credential as Record<string, unknown>).key = apiKey;
+	writeFileSync(PI_AUTH_FILE, JSON.stringify(parsed, null, 2) + "\n");
+}
+
+/** Reconcile Pi's stored MTPLX credential with the configured provider key. */
+export function syncMtplxStoredCredential(): void {
+	try {
+		syncStoredMtplxCredential(loadResolvedMtplxApiKey());
+	} catch (error) {
+		console.error(`MTPLX could not synchronize Pi's stored API key: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/** Update Pi's MTPLX provider and any stored MTPLX credential to the same key. */
+export function saveMtplxApiKey(apiKey: string): boolean {
+	const normalized = apiKey.trim();
+	const resolved = resolveMtplxApiKey(normalized || undefined);
+	try {
+		let catalog: Record<string, unknown> = {};
+		if (existsSync(PI_MODELS_FILE)) {
+			const parsed = JSON.parse(readFileSync(PI_MODELS_FILE, "utf8")) as unknown;
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("models.json is not an object");
+			catalog = parsed as Record<string, unknown>;
+		}
+		let providers = catalog.providers;
+		if (providers !== undefined && (typeof providers !== "object" || providers === null || Array.isArray(providers))) {
+			throw new Error("models.json providers is not an object");
+		}
+		const providerCatalog = (providers ??= {}) as Record<string, unknown>;
+		const existing = providerCatalog.mtplx;
+		if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+			throw new Error("models.json mtplx provider is not an object");
+		}
+		const provider = (existing ?? {
+			api: "openai-completions",
+			authHeader: true,
+			baseUrl: `http://${HOST}:${PORT}/v1`,
+		}) as Record<string, unknown>;
+		if (normalized) provider.apiKey = normalized;
+		else delete provider.apiKey;
+		providerCatalog.mtplx = provider;
+		catalog.providers = providerCatalog;
+		mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
+		writeFileSync(PI_MODELS_FILE, JSON.stringify(catalog, null, 2) + "\n");
+		syncStoredMtplxCredential(resolved);
+		return true;
+	} catch (error) {
+		console.error(`MTPLX could not update API key: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	}
 }
 
 export function displayNameFromId(id: string): string {
@@ -86,14 +210,6 @@ export function displayNameFromId(id: string): string {
 		.replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-export function slugFromId(id: string): string {
-	return id
-		.replace(/^mtplx-/, "")
-		.replace(/[^a-zA-Z0-9]+/g, "-")
-		.replace(/-+/g, "-")
-		.replace(/^-|-$/g, "");
-}
-
 export function isMtplxModel(model: { provider: string; id: string } | undefined): boolean {
 	// The provider name is MTPLX's own PI_PROVIDER_ID (`mtplx`), matching the
 	// provider block that `mtplx start pi` writes to models.json.