pi-mtplx 0.1.0 → 0.1.2

package/README.md

@@ -1,166 +1,69 @@
 # 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.
+Run local MLX models with Pi — zero config, automatic model discovery, and live token-speed monitoring.
 
-```
-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
+## Install
 
-```
+```bash
 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
+Restart Pi after installation.
 
-`/mtplx` opens a menu:
+## What happens on first run
 
-| 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. |
+Once installed, Pi automatically manages your MTPLX workflow:
 
-## Model Discovery
+- **Model discovery** — A built-in model (`mtplx-qwen38-27b-optimized-quality`) is pre-registered. More are discoverable via `/mtplx`.
+- **Auto-start** — The MTPLX server starts when you switch to an `mtplx` model and shuts down cleanly when Pi exits.
+- **Token speed** — A `⚡N.N tk/s` indicator appears in the footer showing the generation speed of the last assistant turn.
 
-`/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`.
+## Commands
 
-Two files back this:
+Run `/mtplx` to open an interactive menu:
 
-- `~/.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.
+| Option | What it does |
+| -------- | ------------- |
+| **Toggle (on/off)** | Start or stop the MTPLX server |
+| **Fan Curves** | Set the thermal profile (`default`, `smart`, `max`) |
+| **Models (register)** | Scan installed MTPLX models and register one with Pi |
+| **Remove Model** | Unregister a model from Pi |
+| **Uninstall** | Remove the `mtplx` provider from Pi's config |
 
 ## Configuration
 
-There is no config file to write. The extension uses fixed, documented defaults:
+### Model registry
 
-| 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`) |
+Models are registered in `~/.pi/agent/mtplx-models.json`. Each entry maps a Pi model ID to an MTPLX artifact ref:
 
-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.
+```json
+{
+  "mtplx-qwen38-27b-optimized-quality": {
+    "ref": "Youssofal/Qwen3.8-27B-MTPLX-Optimized-Quality"
+  }
+}
+```
 
-## Troubleshooting
+Register new models via the `/mtplx` → **Models** menu, or add entries manually to this file (then run `/reload`).
 
-- **"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.
+### Fan mode
 
-## Development
+Controls the thermal profile of your MTPLX server. Saved to `~/.pi/agent/mtplx-fanmode.json` and persists across restarts.
 
-```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)
-```
+| Mode | Behavior |
+| ------ | ---------- |
+| `default` | System default fan curve |
+| `smart` | Default — adaptive thermal management |
+| `max` | Maximum fan, fastest inference |
 
-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
-```
+## Troubleshooting
 
-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).
+| 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 startup timed out after 180s** | Run `mtplx status --deep` for MTPLX-side diagnostics (model validation, memory, thermal) |
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT — see [LICENSE](./LICENSE).

package/extensions/mtplx.ts

@@ -8,7 +8,7 @@
  */
 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 { MTPLX_PROVIDER, listModels, removeModel, removePiMtplxProvider, MTPLX_MODELS } 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";
 
@@ -19,7 +19,7 @@ export default function mtplxAutostart(pi: ExtensionAPI): void {
 			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 topChoices = [`Toggle (${status})`, `Fan Curves (current: ${getFanMode()})`, `Models (register)`, `Remove Model`, "Uninstall (remove provider)"];
 			const top = await ctx.ui.select("MTPLX", topChoices, undefined);
 			if (!top) return;
 			if (top.startsWith("Toggle")) {
@@ -50,15 +50,31 @@ export default function mtplxAutostart(pi: ExtensionAPI): void {
 			if (top.startsWith("Models")) {
 				await listModels(ctx);
 			}
+			if (top.startsWith("Remove Model")) {
+				const registered = Object.keys(MTPLX_MODELS);
+				if (registered.length === 0) {
+					ctx.ui.notify("No MTPLX models registered. Register one first via Models (register).", "warning");
+					return;
+				}
+				const choices = registered.map((id) => `${id} (registered)`);
+				choices.push("Cancel");
+				const picked = await ctx.ui.select("Remove a registered MTPLX model", choices, undefined);
+				if (!picked || picked === "Cancel") return;
+				if (removeModel(picked)) {
+					ctx.ui.notify(`Removed ${picked} from models.json and enabledModels. Run /reload.`, "info");
+				} else {
+					ctx.ui.notify(`${picked} not found in registered models.`, "warning");
+				}
+			}
 			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.`,
+					`Remove the ${MTPLX_PROVIDER} provider (and all its models) from models.json and enabledModels? 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");
+					ctx.ui.notify(`Removed ${MTPLX_PROVIDER} provider from models.json and enabledModels. 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");
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-mtplx",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Zero-config MTPLX integration for Pi coding agent",
 	"keywords": [
 		"pi-package",
@@ -50,4 +50,4 @@
 		"typecheck": "tsc --noEmit",
 		"test": "tsx --test test/*.test.ts"
 	}
-}
+}

package/src/model-discovery.ts

@@ -27,6 +27,7 @@ const execFileAsync = promisify(execFile);
 // 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 SETTINGS_FILE = join(homedir(), ".pi", "agent", "settings.json");
 
 const BUILTIN_MODELS: Record<string, { ref: string }> = {
 	"mtplx-qwen38-27b-optimized-quality": {
@@ -59,6 +60,49 @@ export function saveRegisteredModels(): void {
 	}
 }
 
+// --- enabledModels management (settings.json) ---
+
+function loadEnabledModels(): string[] {
+	try {
+		const parsed = JSON.parse(readFileSync(SETTINGS_FILE, "utf8")) as { enabledModels?: unknown };
+		return Array.isArray(parsed.enabledModels) ? (parsed.enabledModels as string[]) : [];
+	} catch {
+		return [];
+	}
+}
+
+export function enableModelInSettings(modelId: string): boolean {
+	try {
+		const catalog = JSON.parse(readFileSync(SETTINGS_FILE, "utf8")) as { enabledModels?: unknown[] };
+		const enabled = Array.isArray(catalog.enabledModels) ? catalog.enabledModels : [];
+		const entry = `mtplx/${modelId}`;
+		if (enabled.includes(entry)) return true;
+		enabled.push(entry);
+		catalog.enabledModels = enabled;
+		writeFileSync(SETTINGS_FILE, JSON.stringify(catalog, null, 2) + "\n");
+		return true;
+	} catch (error) {
+		console.error(`pi-mtplx could not enable ${modelId} in settings.json: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	}
+}
+
+export function disableModelInSettings(modelId: string): boolean {
+	try {
+		const catalog = JSON.parse(readFileSync(SETTINGS_FILE, "utf8")) as { enabledModels?: unknown[] };
+		const enabled = Array.isArray(catalog.enabledModels) ? catalog.enabledModels : [];
+		const entry = `mtplx/${modelId}`;
+		const idx = enabled.indexOf(entry);
+		if (idx === -1) return true;
+		enabled.splice(idx, 1);
+		catalog.enabledModels = enabled;
+		writeFileSync(SETTINGS_FILE, JSON.stringify(catalog, null, 2) + "\n");
+		return true;
+	} catch (error) {
+		console.error(`pi-mtplx could not disable ${modelId} in settings.json: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	}
+}
 type MtplxListedModel = { repo_id?: unknown; path?: unknown; name?: unknown };
 
 export async function listMtplxModels(): Promise<MtplxListedModel[]> {
@@ -158,19 +202,48 @@ export async function listModels(ctx: ExtensionContext): Promise<void> {
 		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");
+	// 3) Also enable the model in settings.json so it shows on first boot.
+	enableModelInSettings(modelId);
+	ctx.ui.notify(`Registered ${modelId} → ${ref}. 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.
+ * Remove a single registered model from the provider and from enabledModels.
  */
-export function removePiMtplxProvider(): boolean {
+export function removeModel(modelId: string): boolean {
+	// 1) Remove from the mtplx provider in models.json
 	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> };
+		const provider = (catalog.providers?.[MTPLX_PROVIDER] as { models?: unknown[] }) ?? {};
+		const models = Array.isArray(provider.models) ? provider.models : [];
+		const filtered = (models as { id?: string }[]).filter((m) => m.id !== modelId);
+		if (filtered.length === models.length) return false; // not found
+		(provider as { models?: unknown[] }).models = filtered;
+		writeFileSync(modelsJsonPath, JSON.stringify(catalog, null, 2) + "\n");
+	} catch (error) {
+		console.error(`pi-mtplx could not remove ${modelId} from models.json: ${error instanceof Error ? error.message : String(error)}`);
+		return false;
+	}
+	// 2) Also remove from enabledModels in settings.json
+	disableModelInSettings(modelId);
+	return true;
+}
+
+/**
+ * Remove the entire `mtplx` provider from models.json and clean enabledModels.
+ */
+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>; enabledModels?: string[] };
 		if (!catalog.providers || !(MTPLX_PROVIDER in catalog.providers)) return false;
+		// Remove all mtplx models from enabledModels
+		if (catalog.enabledModels) {
+			catalog.enabledModels = catalog.enabledModels.filter((m: string) => !m.startsWith("mtplx/"));
+		}
 		delete catalog.providers[MTPLX_PROVIDER];
 		writeFileSync(modelsJsonPath, JSON.stringify(catalog, null, 2) + "\n");
 		return true;