pi-mtplx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KrossKinetic
+
+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,166 @@
+# pi-mtplx
+
+Zero-config [MTPLX](https://github.com/youssofal/MTPLX) integration for the [Pi](https://pi.dev) coding agent. Install it, switch to a `mtplx` model, and pi-mtplx handles the rest: discovering installed MTPLX models, booting a local MTPLX OpenAI-compatible server on demand, switching models transparently, live fan-curve control, and clean shutdown when Pi exits — without ever touching MTPLX processes that Pi doesn't own.
+
+```
+pi install npm:pi-mtplx
+```
+
+Or from GitHub:
+
+```
+pi install git:github.com/KrossKinetic/pi-mtplx
+```
+
+## Features
+
+- **Zero-config model discovery** — `/mtplx → Models` lists every model in your MTPLX cache and registers the one you pick into Pi's catalog (`~/.pi/agent/models.json`), no manual provider setup.
+- **On-demand autostart** — the first time you run an agent with a `mtplx` model, the local MTPLX server boots itself and waits until `/health` confirms it's serving exactly that model.
+- **Transparent model switching** — switch from model A to model B with `/model`; pi-mtplx stops A and starts B before the next request proceeds.
+- **Process ownership** — pi-mtplx only ever stops servers it can positively identify as its own (see [Automatic MTPLX Lifecycle](#automatic-mtplx-lifecycle)). Manually started MTPLX servers are left alone.
+- **Fan-curve controls** — pick `default`, `smart`, or `max` fan modes; applied at boot and live-updated over the MTPLX thermal endpoint while the server runs.
+- **Clean shutdown** — `/quit` stops the MTPLX server this Pi session owns; no orphaned processes.
+- **tk/s footer** — a companion extension reports the token generation rate of the last assistant turn (`⚡NN.N tk/s`) in the footer.
+
+## Requirements
+
+- macOS on Apple Silicon (MTPLX requirement)
+- The `mtplx` CLI on your `PATH` (pi-mtplx shells out to `mtplx quickstart/stop/list` and reads `GET /health` / `POST /v1/mtplx/thermal/fan_mode`)
+- Node.js ≥ 20 (Pi requirement)
+- At least one MTPLX model installed (`mtplx install <repo>` or `mtplx models --update`)
+
+## Installation
+
+```
+pi install npm:pi-mtplx
+```
+
+or:
+
+```
+pi install git:github.com/KrossKinetic/pi-mtplx
+```
+
+After installing, make sure `mtplx` is on the PATH that Pi runs under, then restart Pi (or `/reload`).
+
+## Quick Start
+
+1. Ensure a model is installed: `mtplx models` (or `mtplx install <repo-id>`).
+2. In Pi, run `/mtplx` → **Models (register)** and pick your model. This maps your Pi model id to the MTPLX artifact and adds the `mtplx` provider to `~/.pi/agent/models.json`.
+3. `/reload` (or restart Pi), then switch to the model with `/model`.
+4. Send a message. On the first request pi-mtplx boots the MTPLX server and waits for it to be ready.
+5. `/mtplx` → **Toggle (off)** to stop it, or just `/quit` — the server shuts down with Pi.
+
+## How It Works
+
+pi-mtplx runs an OpenAI-compatible MTPLX server at `http://127.0.0.1:8000` and registers a `mtplx` provider in Pi's model catalog pointing at it. Every time an agent turn starts on a `mtplx` model, the extension checks the server's `/health` endpoint; if the right model isn't being served, it fixes that before the request is admitted (see [Automatic MTPLX Lifecycle](#automatic-mtplx-lifecycle)). Model ids are stable: the server is started with `mtplx quickstart --model <ref> --model-id <pi-model-id>`, so `/health` and `/v1/models` report Pi's id and the extension can always tell which model a healthy server is serving.
+
+## `/mtplx` Commands
+
+`/mtplx` opens a menu:
+
+| Choice | What it does |
+| --- | --- |
+| **Toggle (on/off)** | Starts or stops the MTPLX server. Stopping only affects servers pi-mtplx owns (see below). Starting with a `mtplx` model active boots that model. |
+| **Fan Curves** | Choose `default`, `smart`, or `max`. Persisted to `~/.pi/agent/mtplx-fanmode.json`, applied at next boot, and pushed live to a running server via `POST /v1/mtplx/thermal/fan_mode`. |
+| **Models (register)** | Lists models from your MTPLX cache (`mtplx list --json`), marks which are already registered in Pi, and registers your pick: saved to `~/.pi/agent/mtplx-models.json` and added to the `mtplx` provider in `~/.pi/agent/models.json`. |
+| **Uninstall** | Removes the `mtplx` provider (and only that provider) from `~/.pi/agent/models.json` after a confirmation. The registry file and installed MTPLX models are untouched. |
+
+## Model Discovery
+
+`/mtplx → Models` shells out to `mtplx list --json`, which reports every artifact in the local MTPLX model cache (`~/.mtplx/models`). Each entry's `repo_id` (or path) is mapped to a Pi model id with the scheme `mtplx-<slug>`, e.g. `Youssofal/Qwen3.8-27B-MTPLX-Optimized-Quality` → `mtplx-qwen38-27b-optimized-quality`.
+
+Two files back this:
+
+- `~/.pi/agent/mtplx-models.json` — Pi model id → MTPLX artifact ref. This is pi-mtplx's own registry; new registrations are appended here. (A built-in fallback map ships in the package for `mtplx-qwen38-27b-optimized-quality`.)
+- `~/.pi/agent/models.json` — Pi's model catalog. pi-mtplx only ever adds to or removes its own `mtplx` provider entry there; it never rewrites other providers.
+
+Registered models are OpenAI-completions models with a 262144 context window, 65536 max output tokens, zero cost (local), and reasoning enabled.
+
+## Automatic MTPLX Lifecycle
+
+- **Boot**: on the first `before_agent_start` for a `mtplx` model, if nothing healthy is on port 8000, pi-mtplx runs `mtplx quickstart --model <ref> --model-id <id> --profile sustained --fan-mode <mode> --host 127.0.0.1 --port 8000 --ssd-session-cache off`, detached and unref'd, then polls `/health` (500 ms) until it reports the requested model id, up to 3 minutes.
+- **Switching**: if `/health` reports a *different* model, pi-mtplx stops it first, then starts the requested one. Requests are serialized: a model is never swapped out while an agent already admitted on the current model is still running.
+- **Stopping**: goes through `mtplx stop --host 127.0.0.1 --port 8000 --json` (MTPLX's own graceful stop: SIGTERM → grace period → SIGKILL), then polls `/health` until the port stops answering.
+- **Shutdown**: on `/quit` (`session_shutdown` with reason `quit`), pi-mtplx stops the server it can identify as its own. If nothing is running, this is a no-op.
+
+### Process ownership
+
+pi-mtplx distinguishes *its* MTPLX process from one you started manually, and cleanup only touches the former:
+
+1. **Session handle** — when pi-mtplx spawns the server, it keeps the child handle. A server it spawned in this session is always owned.
+2. **Health fingerprint** — pi-mtplx always starts its server with `--model-id <pi-model-id>`, and only model ids from its own registry qualify. If `/health` reports a model id that is in pi-mtplx's registry, the server is treated as Pi-owned even across Pi restarts (the process handle doesn't survive a restart, the fingerprint does).
+
+What this means in practice:
+
+- A **manually started** MTPLX server (e.g. `mtplx quickstart` with its own flags, or no `--model-id` matching a pi-mtplx registry id) is **never killed** by pi-mtplx — neither on model switch, `/mtplx → Toggle` stop, nor `/quit`. You'll get a console note telling you to use `/mtplx → Toggle` if you want it stopped. If you rely on a manual server, keep its `--model-id` out of pi-mtplx's registry ids, or just run `/mtplx → Toggle` manually.
+- A **non-MTPLX** service on port 8000 is never touched; pi-mtplx refuses to start and tells you the port is occupied.
+- If MTPLX ever changes what `/health` reports, ownership may degrade to the session handle only — in that case pi-mtplx is conservative and will not stop cross-session servers.
+
+## Model Switching
+
+Switch with `/model` as usual. Behind the scenes, on the next agent turn:
+
+1. `before_agent_start` acquires the model lease.
+2. `/health` is checked. If the running server serves a different `mtplx` model, pi-mtplx stops it (ownership rules above) and starts the new one.
+3. Only once `/health` confirms the requested model is served does the request proceed.
+4. On `agent_end` the lease is released; a different model can then be started for the next turn.
+
+Concurrent same-model requests share the in-flight start; different-model requests queue behind running agents instead of swapping the model out from under them.
+
+## Configuration
+
+There is no config file to write. The extension uses fixed, documented defaults:
+
+| Setting | Value |
+| --- | --- |
+| Server host:port | `127.0.0.1:8000` (MTPLX default) |
+| Quickstart profile | `sustained` |
+| SSD session cache | `off` |
+| Boot readiness timeout | 180 s |
+| Health poll interval | 500 ms |
+| Fan mode | `smart` (persisted choice wins; set via `/mtplx → Fan Curves`) |
+
+Persisted state (all under `~/.pi/agent/`):
+
+- `mtplx-fanmode.json` — chosen fan mode.
+- `mtplx-models.json` — model id → artifact ref registry.
+- `models.json` — Pi's catalog; pi-mtplx manages only the `mtplx` provider entry.
+
+To change the port or profile, edit `src/utils.ts` / `src/mtplx-process.ts` — these are the only two constants the whole package depends on.
+
+## Troubleshooting
+
+- **"MTPLX cannot use 127.0.0.1:8000: another, non-MTPLX service is listening there."** — something else owns the port. Stop it, or change `PORT` in `src/utils.ts`.
+- **"MTPLX startup failed … timed out after 180s"** — check `mtplx status --deep` for MTPLX-side diagnostics (model validation, memory, thermal).
+- **"MTPLX model … is not mapped to an installed MTPLX artifact"** — the model id isn't in `~/.pi/agent/mtplx-models.json`; register it via `/mtplx → Models`.
+- **Model registered but `/model` doesn't list it** — run `/reload` (or restart Pi) after registration; `models.json` is read at load time.
+- **Fan mode change didn't apply to a running server** — the MTPLX thermal endpoint requires the server to be healthy; if `/health` fails, the new fan mode applies at next boot.
+- **`mtplx: command not found`** — make sure the PATH Pi runs under includes the directory with `mtplx` (`which mtplx`).
+- **Uninstalling** — `/mtplx → Uninstall` removes the `mtplx` provider from `models.json`; the registry file and installed models stay. Then remove the package from Pi.
+
+## Development
+
+```bash
+git clone https://github.com/KrossKinetic/pi-mtplx
+cd pi-mtplx
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # node:test via tsx (tests for the pure helpers)
+```
+
+To load the extension locally without publishing, point Pi at it as a package in a test directory, or symlink `extensions/mtplx.ts` and `extensions/mtplx-tkps-footer.ts` into `~/.pi/agent/extensions/` and `/reload`.
+
+## Publishing
+
+```bash
+npm version <next>    # or edit package.json
+npm login
+npm publish           # name is unscoped, so no --access flag needed
+```
+
+For GitHub, push the `main` branch and users can `pi install git:github.com/KrossKinetic/pi-mtplx`. The package is tagged `pi-package` in `keywords`, so it shows up in the [package gallery](https://pi.dev/packages).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/extensions/mtplx-tkps-footer.ts

@@ -0,0 +1,40 @@
+/**
+ * tk/s Extension — MTPLX
+ *
+ * Reports the token generation rate of the LAST completed assistant turn as a
+ * status segment ("⚡NN.N tk/s"). pi-zentui's footer merges extension statuses
+ * (same mechanism pi-lens uses for "LSP Inactive"), so this shows up in the
+ * existing zentui footer without fighting setFooter ownership.
+ *
+ * tk/s = usage.output of the last assistant message / (message.timestamp -
+ * stream start), where stream start is captured on message_start (assistant).
+ */
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const STATUS_KEY = "tkps";
+
+let streamStartMs: number | undefined;
+
+export default function (pi: ExtensionAPI) {
+	pi.on("message_start", (event) => {
+		if (event.message.role === "assistant") {
+			streamStartMs = Date.now();
+		}
+	});
+
+	pi.on("message_end", (event, ctx) => {
+		const m = event.message;
+		if (m.role !== "assistant") return;
+		const msg = m as AssistantMessage;
+		if (streamStartMs !== undefined && msg.usage?.output > 0) {
+			// msg.timestamp is set by pi-ai at STREAM START, not end — the end time
+			// must be captured here. (Using msg.timestamp yields a clamped 0.01s
+			// duration and bogus tk/s.)
+			const durationSec = Math.max((Date.now() - streamStartMs) / 1000, 0.01);
+			const rate = msg.usage.output / durationSec;
+			ctx.ui.setStatus(STATUS_KEY, `⚡${rate.toFixed(1)} tk/s`);
+			streamStartMs = undefined;
+		}
+	});
+}

package/extensions/mtplx.ts

@@ -0,0 +1,90 @@
+/**
+ * pi-mtplx — zero-config MTPLX integration for the Pi coding agent.
+ *
+ * Pi package entry point: wires the MTPLX lifecycle (src/mtplx-process.ts),
+ * HTTP client (src/mtplx-client.ts), model registry (src/model-discovery.ts)
+ * and shared helpers (src/utils.ts) into Pi via before_agent_start,
+ * 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 { MTPLX_PROVIDER, listModels, removePiMtplxProvider } from "../src/model-discovery.ts";
+import { FAN_MODES, isMtplxModel, saveFanMode, type FanMode } from "../src/utils.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function mtplxAutostart(pi: ExtensionAPI): void {
+	pi.registerCommand("mtplx", {
+		description: "MTPLX — toggle the server, pick a fan curve, or register a model",
+		handler: async (_args, ctx) => {
+			const current = await health();
+			const status = current ? "on" : "off";
+			await ctx.ui.setStatus("mtplx", `MTPLX: ${status}`);
+			const topChoices = [`Toggle (${status})`, `Fan Curves (current: ${getFanMode()})`, `Models (register)`, "Uninstall (remove pi models.json entry)"];
+			const top = await ctx.ui.select("MTPLX", topChoices, undefined);
+			if (!top) return;
+			if (top.startsWith("Toggle")) {
+				if (current) {
+					await stopServer();
+					ctx.ui.notify("MTPLX server stopped", "info");
+				} else if (ctx.model && isMtplxModel(ctx.model)) {
+					await acquire(ctx.model.id);
+					ctx.ui.notify(`MTPLX server started (${ctx.model.id})`, "info");
+				} else {
+					ctx.ui.notify(`MTPLX not started — switch to an MTPLX (${MTPLX_PROVIDER}) model (active: ${ctx.model?.provider}/${ctx.model?.id})`, "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);
+				if (!picked) return;
+				const mode = picked.replace(" (current)", "") as FanMode;
+				if (!(FAN_MODES as readonly string[]).includes(mode)) return;
+				setFanModeValue(mode);
+				saveFanMode(mode);
+				if (current) {
+					await setFanMode();
+				}
+				ctx.ui.notify(`MTPLX fan mode set to ${getFanMode()}`, "info");
+			}
+			if (top.startsWith("Models")) {
+				await listModels(ctx);
+			}
+			if (top.startsWith("Uninstall")) {
+				const ok = await ctx.ui.confirm(
+					"pi-mtplx uninstall",
+					`Remove the ${MTPLX_PROVIDER} provider (and its models) from ~/.pi/agent/models.json? The model registry file (~/.pi/agent/mtplx-models.json) and installed MTPLX models are left in place.`,
+					undefined,
+				);
+				if (!ok) return;
+				if (removePiMtplxProvider()) {
+					ctx.ui.notify(`Removed ${MTPLX_PROVIDER} provider from models.json. Run /reload (or restart Pi), then remove the pi-mtplx package.`, "info");
+				} else {
+					ctx.ui.notify(`Nothing to remove — the ${MTPLX_PROVIDER} provider is not in models.json.`, "info");
+				}
+			}
+		},
+	});
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		if (!ctx.model || !isMtplxModel(ctx.model)) return;
+		try {
+			await acquire(ctx.model.id);
+		} catch (error) {
+			throw new Error(`MTPLX request blocked: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		if (ctx.model && isMtplxModel(ctx.model)) release();
+	});
+
+	pi.on("session_shutdown", async (event) => {
+		if (event.reason !== "quit") return;
+		try {
+			await stopServer();
+		} catch (error) {
+			console.error(`MTPLX cleanup on quit failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "pi-mtplx",
+	"version": "0.1.0",
+	"description": "Zero-config MTPLX integration for Pi coding agent",
+	"keywords": [
+		"pi-package",
+		"pi-agent",
+		"pi-coding-agent",
+		"mtplx",
+		"local-llm",
+		"local-inference"
+	],
+	"license": "MIT",
+	"type": "module",
+	"homepage": "https://github.com/KrossKinetic/pi-mtplx#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/KrossKinetic/pi-mtplx.git"
+	},
+	"bugs": {
+		"url": "https://github.com/KrossKinetic/pi-mtplx/issues"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/mtplx.ts",
+			"./extensions/mtplx-tkps-footer.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-ai": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "0.84.2",
+		"@earendil-works/pi-coding-agent": "0.84.2",
+		"@types/node": "^22",
+		"tsx": "^4",
+		"typescript": "^5"
+	},
+	"files": [
+		"extensions",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test test/*.test.ts"
+	}
+}

package/src/model-discovery.ts

@@ -0,0 +1,181 @@
+/**
+ * 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 built-in map is the fallback; registrations added from `/mtplx` are
+ * persisted next to it (~/.pi/agent/mtplx-models.json) and override it at load.
+ *
+ * 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.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+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, slugFromId } 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.
+export const MTPLX_PROVIDER = "mtplx";
+const MODELS_FILE = join(homedir(), ".pi", "agent", "mtplx-models.json");
+
+const BUILTIN_MODELS: Record<string, { ref: string }> = {
+	"mtplx-qwen38-27b-optimized-quality": {
+		ref: "Youssofal/Qwen3.8-27B-MTPLX-Optimized-Quality",
+	},
+};
+
+export function loadRegisteredModels(): Record<string, { ref: string }> {
+	try {
+		const parsed = JSON.parse(readFileSync(MODELS_FILE, "utf8")) as Record<string, { ref?: unknown }>;
+		const out: Record<string, { ref: string }> = {};
+		for (const [id, entry] of Object.entries(parsed)) {
+			if (entry && typeof entry.ref === "string") out[id] = { ref: entry.ref };
+		}
+		return out;
+	} catch {
+		// missing or corrupt file → fall back to the built-ins only
+	}
+	return {};
+}
+
+export const MTPLX_MODELS: Record<string, { ref: string }> = { ...BUILTIN_MODELS, ...loadRegisteredModels() };
+
+export function saveRegisteredModels(): void {
+	try {
+		mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
+		writeFileSync(MODELS_FILE, JSON.stringify(MTPLX_MODELS, null, 2) + "\n");
+	} catch (error) {
+		console.error(`MTPLX could not persist model registry: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+type MtplxListedModel = { repo_id?: unknown; path?: unknown; name?: unknown };
+
+export async function listMtplxModels(): Promise<MtplxListedModel[]> {
+	try {
+		const { stdout } = await execFileAsync("mtplx", ["list", "--json"], { timeout: 30_000 });
+		const parsed = JSON.parse(stdout) as { models?: unknown };
+		const models = parsed.models;
+		return Array.isArray(models) ? (models as MtplxListedModel[]) : [];
+	} catch {
+		return [];
+	}
+}
+
+export function listedIdentity(model: MtplxListedModel): string {
+	return typeof model.repo_id === "string" && model.repo_id ? model.repo_id : typeof model.path === "string" ? model.path : "";
+}
+
+/**
+ * Ask the user which MTPLX models are installed, then register the pick into
+ * the mapping file and into the `mtplx` provider of the user's models.json
+ * catalog. Every other provider is left untouched.
+ */
+export async function listModels(ctx: ExtensionContext): Promise<void> {
+	const installed = await listMtplxModels();
+	if (installed.length === 0) {
+		ctx.ui.notify("No MTPLX models found. Install one with `mtplx install`.", "warning");
+		return;
+	}
+	const choices = installed.map((model) => {
+		const ref = listedIdentity(model);
+		const refId = modelIdFromRef(ref);
+		const existingId = Object.keys(MTPLX_MODELS).find((id) => MTPLX_MODELS[id].ref === ref || slugFromId(id) === slugFromId(refId));
+		const id = existingId ?? refId;
+		const mark = existingId ? "✓" : "✗";
+		return `${mark} ${id} — ${ref}`;
+	});
+	choices.push("Cancel");
+	const picked = await ctx.ui.select("MTPLX models — ✓ registered in Pi · ✗ available in MTPLX — run /reload after making changes", choices, undefined);
+	if (!picked || picked === "Cancel") return;
+	const ref = picked.split(" — ").slice(1).join(" — ");
+	const modelId = Object.keys(MTPLX_MODELS).find((id) => MTPLX_MODELS[id].ref === ref) ?? modelIdFromRef(ref);
+	if (MTPLX_MODELS[modelId]) {
+		ctx.ui.notify(`${modelId} is already registered — run /reload, then switch with /model.`, "info");
+		return;
+	}
+
+	// 1) Persist the Pi id → artifact ref mapping (also used to resolve autostart model ids).
+	MTPLX_MODELS[modelId] = { ref };
+	saveRegisteredModels();
+
+	// 2) Register the model in the `mtplx` provider of Pi's catalog (models.json).
+	try {
+		const modelsJsonPath = join(homedir(), ".pi", "agent", "models.json");
+		const catalog = JSON.parse(readFileSync(modelsJsonPath, "utf8")) as { providers?: Record<string, unknown> };
+		const providers = (catalog.providers ??= {});
+		const provider = (providers[MTPLX_PROVIDER] ??= {
+			api: "openai-completions",
+			apiKey: "mtplx-local",
+			authHeader: true,
+			baseUrl: "http://127.0.0.1:8000/v1",
+			compat: {
+				maxTokensField: "max_tokens",
+				supportsDeveloperRole: false,
+				supportsReasoningEffort: true,
+			},
+			headers: {
+				"x-mtplx-client": "pi",
+			},
+		}) as { models?: unknown[] };
+		const models = Array.isArray(provider.models) ? (provider.models as unknown[]) : [];
+		if (models.some((entry) => (entry as { id?: unknown }).id === modelId)) {
+			ctx.ui.notify(`Already in models.json: ${modelId}`, "warning");
+			return;
+		}
+		models.push({
+			id: modelId,
+			name: displayNameFromId(modelId),
+			api: "openai-completions",
+			reasoning: true,
+			input: ["text", "image"],
+			contextWindow: 262144,
+			maxTokens: 65536,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			thinkingLevelMap: {
+				off: null,
+				minimal: null,
+				low: "low",
+				medium: "medium",
+				high: null,
+				xhigh: "xhigh",
+				max: null,
+			},
+		});
+		provider.models = models;
+		writeFileSync(modelsJsonPath, JSON.stringify(catalog, null, 2) + "\n");
+	} catch (error) {
+		ctx.ui.notify(`MTPLX model mapping saved, but models.json update failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+		return;
+	}
+	ctx.ui.notify(`Registered ${modelId} → ${ref}. Restart Pi, then switch to it with /model.`, "info");
+}
+
+/**
+ * Remove the `mtplx` provider from the user's models.json. Never touches any
+ * other provider. Silently succeeds when the file or provider is absent.
+ */
+export function removePiMtplxProvider(): boolean {
+	const modelsJsonPath = join(homedir(), ".pi", "agent", "models.json");
+	if (!existsSync(modelsJsonPath)) return false;
+	try {
+		const catalog = JSON.parse(readFileSync(modelsJsonPath, "utf8")) as { providers?: Record<string, unknown> };
+		if (!catalog.providers || !(MTPLX_PROVIDER in catalog.providers)) return false;
+		delete catalog.providers[MTPLX_PROVIDER];
+		writeFileSync(modelsJsonPath, JSON.stringify(catalog, null, 2) + "\n");
+		return true;
+	} catch (error) {
+		console.error(`pi-mtplx uninstall could not update models.json: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	}
+}

package/src/mtplx-client.ts

@@ -0,0 +1,63 @@
+/**
+ * Minimal HTTP client for the locally-running MTPLX server (OpenAI-compatible
+ * endpoint on 127.0.0.1:8000). Only touches endpoints that MTPLX exposes:
+ *   GET  /health
+ *   POST /v1/mtplx/thermal/fan_mode
+ */
+import { HOST, PORT, type FanMode, loadFanMode } from "./utils.ts";
+
+export type Health = { ok: true; model: string; model_path?: string; fan_mode?: string };
+
+// Current fan curve for autostart and live updates. Loaded from disk so the
+// choice survives Pi restarts (see FANMODE_FILE in utils.ts).
+let fanMode: FanMode = loadFanMode();
+
+export function getFanMode(): FanMode {
+	return fanMode;
+}
+
+export function setFanModeValue(mode: FanMode): void {
+	fanMode = mode;
+}
+
+export async function health(): Promise<Health | undefined> {
+	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 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;
+		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,
+		};
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+export async function setFanMode(): Promise<void> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), 10_000);
+	try {
+		const response = await fetch(`http://${HOST}:${PORT}/v1/mtplx/thermal/fan_mode`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ mode: fanMode }),
+			signal: controller.signal,
+		});
+		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"}`);
+		}
+	} catch (error) {
+		throw new Error(`MTPLX fan control failed: ${error instanceof Error ? error.message : String(error)}`);
+	} finally {
+		clearTimeout(timeout);
+	}
+}

package/src/mtplx-process.ts

@@ -0,0 +1,213 @@
+/**
+ * MTPLX process lifecycle: start / stop / ensure, with ownership tracking.
+ *
+ * Ownership model (important — see README):
+ *   - This module spawns the server itself (`mtplx quickstart ...`), keeps a
+ *     reference to the child, and passes `--model-id` so `/health` reports
+ *     Pi's model id — a positive fingerprint that a given healthy server on
+ *     the port is one this extension owns.
+ *   - Cleanup is therefore precise: a server only gets shut down if the
+ *     extension spawned it in this session, or if `/health` positively
+ *     identifies it as an MTPLX server serving one of the extension's model
+ *     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.
+ */
+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 { MTPLX_MODELS } from "./model-discovery.ts";
+import { HOST, PORT, READY_TIMEOUT_MS, POLL_MS, sleep, commandError, portIsOccupied } from "./utils.ts";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Child process handle of the server this Pi session spawned, if any.
+ * Kept in parallel with the /health fingerprint: the handle covers "we
+ * spawned it", the fingerprint covers "a previous Pi session spawned it".
+ */
+let ownedChild: ChildProcess | undefined;
+
+/** True when the extension spawned the currently-healthy server in this session. */
+export function isOwnedByThisSession(): boolean {
+	return ownedChild !== undefined;
+}
+
+export function startupError(cause: Error): Error {
+	return new Error(`MTPLX startup failed: ${cause.message}. Check \`mtplx status --deep\` for MTPLX diagnostics.`);
+}
+
+/**
+ * Shut down the server on HOST:PORT — but only if we can positively identify
+ * it as MTPLX (via /health). A healthy, non-MTPLX listener is an error, never
+ * a kill target.
+ */
+export async function stopServer(): Promise<void> {
+	const current = await health();
+	if (!current) {
+		if (await portIsOccupied()) {
+			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.
+		ownedChild = undefined;
+		return;
+	}
+
+	// /health says an MTPLX server is answering here.
+	if (!isOwnedByThisSession() && !currentModelIsOurs(current.model)) {
+		// An MTPLX server the extension does not own (e.g. started manually by
+		// the user). MTPLX exposes no reliable way to distinguish it from a
+		// Pi-managed one at the port level beyond --model-id, so do not kill
+		// it. If a Pi-owned one is still needed, the user can run /mtplx →
+		// Toggle.
+		console.warn(
+			`pi-mtplx: leaving MTPLX server on ${HOST}:${PORT} (model ${JSON.stringify(current.model)}) untouched — not owned by this Pi session. Use /mtplx → Toggle to stop it.`,
+		);
+		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)}`);
+	}
+	ownedChild = undefined;
+
+	const deadline = Date.now() + 20_000;
+	while (Date.now() < deadline) {
+		if (!(await health())) return;
+		await sleep(POLL_MS);
+	}
+	throw new Error(`MTPLX shutdown timed out; ${HOST}:${PORT} is still healthy.`);
+}
+
+/** Positive ownership fingerprint: /health model id belongs to this extension's registry. */
+function currentModelIsOurs(model: string): boolean {
+	return Object.keys(MTPLX_MODELS).includes(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
+ * outlives Pi's event-loop teardown, and unref'd so it never blocks Pi exit.
+ */
+export async function startServer(modelId: string): Promise<void> {
+	const configured = MTPLX_MODELS[modelId];
+	if (!configured) {
+		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.`);
+	}
+
+	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),
+			// Keep the KV-cache SSD cold tier off (CLI default is `on`). Do not remove.
+			"--ssd-session-cache",
+			"off",
+		],
+		{ detached: true, stdio: "ignore" },
+	);
+	ownedChild = child;
+	child.once("error", (error) => {
+		exited = new Error(`could not launch mtplx: ${error.message}`);
+	});
+	child.once("exit", (code, signal) => {
+		if (code !== 0) exited = new Error(`mtplx exited before becoming ready (code ${code ?? "none"}, signal ${signal ?? "none"})`);
+	});
+	child.unref();
+
+	const deadline = Date.now() + READY_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		if (exited) throw startupError(exited);
+		const current = await health();
+		if (current?.model === modelId) {
+			if (current.fan_mode !== getFanMode()) await setFanMode();
+			return;
+		}
+		if (current) throw new Error(`MTPLX became healthy with ${JSON.stringify(current.model)}, not the requested ${JSON.stringify(modelId)}.`);
+		await sleep(POLL_MS);
+	}
+	throw startupError(new Error(`timed out after ${READY_TIMEOUT_MS / 1000}s`));
+}
+
+/**
+ * Ensure the server on HOST:PORT serves `modelId`, transparently switching
+ * models: stop the current (identified) server, then start the requested one.
+ */
+export async function ensureServer(modelId: string): Promise<void> {
+	const current = await health();
+	if (current?.model === modelId) {
+		if (current.fan_mode !== getFanMode()) await setFanMode();
+		return;
+	}
+	if (current) await stopServer();
+	else if (await portIsOccupied()) {
+		throw new Error(`MTPLX cannot start because ${HOST}:${PORT} is occupied by a non-MTPLX service.`);
+	}
+	await startServer(modelId);
+	await setFanMode();
+}
+
+let transition: Promise<void> | undefined;
+let transitionModel: string | undefined;
+let activeModel: string | undefined;
+let activeAgents = 0;
+let idleWaiters: Array<() => void> = [];
+
+export function ensureOnce(modelId: string): Promise<void> {
+	if (transition) {
+		if (transitionModel === modelId) return transition;
+		return transition.then(() => ensureOnce(modelId));
+	}
+	transitionModel = modelId;
+	transition = ensureServer(modelId).finally(() => {
+		transition = undefined;
+		transitionModel = undefined;
+	});
+	return transition;
+}
+
+export async function acquire(modelId: string): Promise<void> {
+	// Never replace a model while an already-admitted MTPLX agent is running.
+	// Same-model requests share both this lease and any in-flight start Promise.
+	while (activeAgents > 0 && activeModel !== modelId) {
+		await new Promise<void>((resolve) => idleWaiters.push(resolve));
+	}
+	// Reserve the model before awaiting startup. This closes the gap where a
+	// different request could otherwise begin a replacement between readiness
+	// and this request entering Pi's provider path.
+	activeModel = modelId;
+	activeAgents += 1;
+	try {
+		await ensureOnce(modelId);
+	} catch (error) {
+		release();
+		throw error;
+	}
+}
+
+export function release(): void {
+	if (activeAgents === 0) return;
+	activeAgents -= 1;
+	if (activeAgents === 0) {
+		activeModel = undefined;
+		for (const resolve of idleWaiters.splice(0)) resolve();
+	}
+}

package/src/utils.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared constants and small helpers for the pi-mtplx extension.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const HOST = "127.0.0.1";
+export const PORT = 8000;
+export const READY_TIMEOUT_MS = 180_000;
+export const POLL_MS = 500;
+
+export type FanMode = "default" | "smart" | "max";
+export const FAN_MODES: readonly FanMode[] = ["default", "smart", "max"];
+
+// 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
+// module-level variable that would reset to "smart" on every fresh session, silently
+// overriding the previous `/mtplx` pick (and mislabelling "(current)" on the wrong mode).
+export const FANMODE_FILE = join(homedir(), ".pi", "agent", "mtplx-fanmode.json");
+
+export function loadFanMode(): FanMode {
+	try {
+		const parsed = JSON.parse(readFileSync(FANMODE_FILE, "utf8")) as { fanMode?: unknown };
+		if (typeof parsed.fanMode === "string" && (FAN_MODES as readonly string[]).includes(parsed.fanMode)) {
+			return parsed.fanMode as FanMode;
+		}
+	} catch {
+		// missing or corrupt file → fall back to the default
+	}
+	return "smart";
+}
+
+export function saveFanMode(fanMode: FanMode): void {
+	try {
+		mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
+		writeFileSync(FANMODE_FILE, JSON.stringify({ fanMode }, null, 2) + "\n");
+	} catch (error) {
+		console.error(`MTPLX could not persist fan mode: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+// 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();
+}
+
+export function displayNameFromId(id: string): string {
+	return id
+		.replace(/^mtplx-/, "")
+		.replace(/-+/g, " ")
+		.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.
+	return model?.provider === "mtplx";
+}
+
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function commandError(error: unknown): string {
+	if (typeof error !== "object" || error === null) return String(error);
+	const details = error as { stderr?: string | Buffer; message?: string };
+	const stderr = details.stderr?.toString().trim();
+	return stderr || details.message || "unknown command failure";
+}
+
+export function portIsOccupied(): Promise<boolean> {
+	return new Promise((resolve) => {
+		const socket = createConnection({ host: HOST, port: PORT });
+		const done = (occupied: boolean) => {
+			socket.destroy();
+			resolve(occupied);
+		};
+		socket.setTimeout(1_000);
+		socket.once("connect", () => done(true));
+		socket.once("timeout", () => done(false));
+		socket.once("error", () => done(false));
+	});
+}