mu-agent 0.1.13 → 0.2.0

package/kyrn/bin/kyrn-doctor

@@ -74,8 +74,12 @@ if (layout === "package") {
 		"dependencies",
 		installed
 			? "installed"
-			: `missing: cd ${root} && npm ci --ignore-scripts && npm run hydrate:model-data`,
+			: `missing: cd ${root} && npm ci --ignore-scripts && npm run hydrate:model-catalog`,
 	);
+	// The model list pi reads at its start is generated, not committed (installHint in mu.mjs).
+	if (installed && !existsSync(join(root, "packages", "ai", "src", "providers", "data", ".manifest.json"))) {
+		row("fix", "model list", `not generated: cd ${root} && npm run hydrate:model-catalog`);
+	}
 
 	// A link on POSIX, a small mu.cmd on Windows, where a link to a script cannot be run.
 	const linked = linkState({
@@ -118,14 +122,32 @@ row(
 const config = readJson(join(agentDir, "mu.json")) ?? readJson(join(agentDir, "kyrn.json"));
 const tiers = (env("JUDGE") ? env("JUDGE").split(",") : (config?.tiers ?? ["jev"])).map((tier) => tier.trim());
 const mode = env("JUDGE_MODE") ?? config?.modes?.default ?? "active";
-row("--", "judges", `${tiers.join(" > ")} · default mode ${mode}${env("JUDGE") ? " (from MU_JUDGE)" : ""}`);
 const overrides = Object.entries(config?.modes ?? {}).filter(([id]) => id !== "default");
+// The modes mu sets out of the box besides the default, as packages/kyrn-judge/src/config.ts has them: one of these in
+// mu.json gives way to a default of off (DecisionEngine.getMode).
+const BUILT_IN_MODES = {
+	"swarm.patch": "off",
+	"capability.disclosure": "off",
+	"notify.routing": "shadow",
+	"input.interjection": "shadow",
+	"turn.drift": "shadow",
+};
+// Whether any decision point asks a judge (DecisionEngine.asksJudge). With none, nothing is sent to one, and the rows
+// about keys and judges that answer would only mislead.
+const asksJudge = mode !== "off" || overrides.some(([id, value]) => value !== "off" && BUILT_IN_MODES[id] !== value);
+row(
+	"--",
+	"judges",
+	`${tiers.join(" > ")} · default mode ${mode}${env("JUDGE") ? " (from MU_JUDGE)" : ""}${asksJudge ? "" : " · no decision point asks a judge, so nothing is sent to one"}`,
+);
 if (overrides.length > 0) row("--", "modes", overrides.map(([id, value]) => `${id}=${value}`).join(" "));
 const ladder = config?.features?.swarm?.models ?? [];
 row("--", "subagents", ladder.length > 0 ? `model ladder ${ladder.join(" < ")}` : "use the session's model (no ladder configured)");
 
 const judgeSupport = localJudgeSupport({ platform: process.platform, env: process.env, wsl });
-if (tiers.some((tier) => tier.startsWith("laya")) && !judgeSupport.runs && !judgeSupport.url) {
+if (!asksJudge) {
+	// Nothing asks the local judge either: whether it is up does not matter.
+} else if (tiers.some((tier) => tier.startsWith("laya")) && !judgeSupport.runs && !judgeSupport.url) {
 	// Not a failure of this installation: the sidecar is Core ML, and there is none for this platform.
 	row("--", "local judge", `not available on ${platformName({ platform: process.platform, wsl })}: the Laya sidecar needs Core ML (macOS on Apple silicon)`);
 	row("--", "", "Laya's decision points use the next judge or their fallbacks. Use Jev, an LLM judge or MU_LOCAL_JUDGE_URL=<a server with the same API>");
@@ -174,8 +196,11 @@ const CLASSIFIER_KEYS = {
 const fromFile = existsSync(envFile) ? parseEnvFile(readFileSync(envFile, "utf8")).entries : [];
 const has = (name) => Boolean(process.env[name]) || fromFile.some(([key, value]) => key === name && value !== "");
 const where = `to ${tilde(envFile)} or to your environment`;
-const jevTier = tiers.find((tier) => ["jev", "typesafe", "gateway"].includes((config?.judges?.[tier] ?? JEV_ROUTES[tier])?.type));
-if (jevTier) {
+// mude speaks System One too, but on this machine and with a key of its own (its rows are below).
+const jevTier = tiers.find(
+	(tier) => tier !== "mude" && ["jev", "typesafe", "gateway"].includes((config?.judges?.[tier] ?? JEV_ROUTES[tier])?.type),
+);
+if (jevTier && asksJudge) {
 	const judge = config?.judges?.[jevTier] ?? JEV_ROUTES[jevTier];
 	if (judge.type === "jev") {
 		// The order the registry tries: TypeSafe directly, Jev on OpenRouter, the Vercel AI Gateway, OpenCode Zen,
@@ -215,15 +240,40 @@ if (jevTier) {
 	}
 }
 
+// mude on this Mac (mu judge mude): its server's /health, and the key mu sends it.
+if (asksJudge && tiers.includes("mude")) {
+	const fallback = tiers.filter((tier) => tier !== "mude");
+	const behind = fallback.length > 0 ? `until it answers, ${fallback.join(" > ")} decide${fallback.length === 1 ? "s" : ""} (what they read leaves this machine)` : "until it answers, decisions take their fallbacks";
+	if (process.platform !== "darwin") {
+		row("--", "mude 1.0", `not available on ${platformName({ platform: process.platform, wsl })}: mude 1.0 runs on a Mac with Apple silicon`);
+	} else {
+		const entry = config?.judges?.mude;
+		const address = (typeof entry?.baseUrl === "string" ? entry.baseUrl : "http://127.0.0.1:8790/v1/systemone").replace(/\/v1\/systemone\/?$/, "");
+		const startedAt = performance.now();
+		try {
+			const response = await fetch(`${address}/health`, { signal: AbortSignal.timeout(2000) });
+			const health = await response.json();
+			const ms = Math.round(performance.now() - startedAt);
+			row(health.status === "ready" ? "ok" : "--", "mude 1.0", `${address} · ${health.status} · ${ms} ms`);
+		} catch {
+			row("fix", "mude 1.0", `${address} isn't answering: run mu judge mude start   (first time: mu judge mude install)`);
+			row("--", "", behind);
+		}
+		if (!has("MU_JUDGE_MUDE_KEY")) row("fix", "mude 1.0 key", "MU_JUDGE_MUDE_KEY is not set, so mu can't ask mude 1.0: run mu judge mude enable");
+	}
+}
+
 // Classifier models of pi's catalog (Jev on OpenCode Zen or Cloudflare, Clef, …), for the tiers and routes that use them.
 const classifierOf = (tier) =>
 	tier.startsWith("classifier:")
 		? { type: "classifier", model: tier.slice("classifier:".length) }
 		: (config?.judges?.[tier] ?? JEV_ROUTES[tier]);
-const askedTiers = [
-	...tiers,
-	...Object.values(config?.routes ?? {}).flatMap((value) => (Array.isArray(value) ? value : String(value).split(","))),
-].map((tier) => String(tier).trim());
+const askedTiers = asksJudge
+	? [
+			...tiers,
+			...Object.values(config?.routes ?? {}).flatMap((value) => (Array.isArray(value) ? value : String(value).split(","))),
+		].map((tier) => String(tier).trim())
+	: [];
 for (const model of new Set(askedTiers.map(classifierOf).filter((judge) => judge?.type === "classifier").map((judge) => judge.model))) {
 	const provider = String(model ?? "").split("/")[0];
 	// OpenCode's free models answer without a key (the client sends "public", as OpenCode's own does).
@@ -325,12 +375,16 @@ const canRelate = (tier) =>
 const browseTiers = config?.routes?.["browser.step"] ?? tiers;
 const routed = Object.entries(config?.routes ?? {});
 if (routed.length > 0) row("--", "routes", routed.map(([id, value]) => `${id} -> ${[value].flat().join(" > ")}`).join(" · "));
+// mu's browser runs on the judge: with browser.step off it is switched off (src/extension/features/browser.ts).
+const browseMode = config?.modes?.["browser.step"] ?? mode;
 row(
-	[browseTiers].flat().some(canRelate) ? "ok" : "--",
+	browseMode !== "off" && [browseTiers].flat().some(canRelate) ? "ok" : "--",
 	"browse",
-	[browseTiers].flat().some(canRelate)
-		? `driven by ${[browseTiers].flat().join(" > ")}`
-		: 'needs a judge that can match a goal to a page. In mu.json: "routes": { "browser.step": ["llm:openai/gpt-5.6-luna"] }',
+	browseMode === "off"
+		? "off: mu's browser runs on the judge, and browser.step is off"
+		: [browseTiers].flat().some(canRelate)
+			? `driven by ${[browseTiers].flat().join(" > ")}`
+			: 'needs a judge that can match a goal to a page. In mu.json: "routes": { "browser.step": ["llm:openai/gpt-5.6-luna"] }',
 );
 
 const marks = { ok: "\x1b[32m ok\x1b[0m", fix: "\x1b[33mfix\x1b[0m", "--": "\x1b[2m  ·\x1b[0m" };

package/kyrn/bin/mu.mjs

@@ -102,6 +102,8 @@ export function usage(platform) {
 		"  mu -c | -r               continue the last session | pick a session to resume",
 		"  mu setup                 connect a model (paste an API key or pick a service) and choose a judge",
 		"                           (see mu setup --help for scripting, reading a key from stdin and the supported services)",
+		"  mu judge mude install    run mude 1.0, mu's decision model optimized for coding, on this Mac as the judge (Apple silicon, 1.8 GB)",
+		"                           enable | disable | start | stop | status | uninstall (mu judge mude help)",
 		"  mu judge <cmd>           manage the local judge, Laya (macOS on Apple silicon): setup | start | stop | status | run",
 		"  mu ledger [n] [--json]   print the judge's verdicts from the last n sessions",
 		"  mu import <file>...      import Claude Code, Codex and ZCode conversations; --list shows them (mu import --help)",
@@ -321,8 +323,8 @@ export function layoutOf({ root, platform, exists }) {
 }
 
 /**
- * The files the npm package runs: pi, the judgment layer, the sign-in of `mu auth`, the importer of `mu import` and the
- * wizard of `mu setup`.
+ * The files the npm package runs: pi, the judgment layer, the sign-in of `mu auth`, the importer of `mu import`, the
+ * wizard of `mu setup` and `mu judge mude`.
  */
 export function packageEntries({ root, platform }) {
 	const path = pathFor(platform);
@@ -332,6 +334,7 @@ export function packageEntries({ root, platform }) {
 		auth: path.join(root, "judge", "dist", "auth.js"),
 		import: path.join(root, "judge", "dist", "import.js"),
 		setup: path.join(root, "judge", "dist", "setup.js"),
+		mude: path.join(root, "judge", "dist", "mude.js"),
 	};
 }
 
@@ -354,12 +357,26 @@ export function dependenciesInstalled({ root, platform, exists }) {
 	}
 }
 
-export function installHint({ root, platform }) {
-	const steps = [`cd ${root}`, "npm ci --ignore-scripts", "npm run hydrate:model-data"];
-	// Windows PowerShell 5 has no `&&`.
+/**
+ * Writes the model list pi reads at its start (packages/ai/src/providers/data, not committed) from the pinned catalog in
+ * the repository: offline and the same every time, as CI builds it.
+ */
+const HYDRATE = "npm run hydrate:model-catalog";
+
+/** A problem and the commands that fix it, one line to paste; Windows PowerShell 5 has no `&&`, so a list there. */
+function stepsHint(problem, steps, platform) {
 	return platform === "win32"
-		? `mu's dependencies aren't installed. Run:\n${steps.map((step) => `  ${step}`).join("\n")}`
-		: `mu's dependencies aren't installed. Run:  ${steps.join(" && ")}`;
+		? `${problem}. Run:\n${steps.map((step) => `  ${step}`).join("\n")}`
+		: `${problem}. Run:  ${steps.join(" && ")}`;
+}
+
+export function installHint({ root, platform }) {
+	return stepsHint("mu's dependencies aren't installed", [`cd ${root}`, "npm ci --ignore-scripts", HYDRATE], platform);
+}
+
+/** A checkout whose dependencies are in but whose model list was never written: a clone right after npm install. */
+export function modelDataHint({ root, platform }) {
+	return stepsHint("mu's list of models isn't generated in this checkout yet", [`cd ${root}`, HYDRATE], platform);
 }
 
 /** What mu says on a Node that does not strip TypeScript types, which a checkout cannot run on. */
@@ -372,12 +389,16 @@ const NO_TYPE_STRIPPING =
  * pi's own source resolver (packages/coding-agent/src/experimental/source-resolver.ts: each workspace package
  * resolves to its sources, as tsconfig.json's paths say) and Node's compile cache (compile-cache.mjs), the way pi
  * runs its own checkout (pi-test.sh). A runtime that does not strip types, a checkout whose dependencies are not
- * installed and one without the resolver are each said, not left to a failed import.
+ * installed or whose model list is not generated, and one without the resolver are each said, not left to a failed
+ * import.
  */
 export function sourceRuntime({ root, platform, stripsTypes, exists }) {
 	const path = pathFor(platform);
 	if (!stripsTypes) return { error: NO_TYPE_STRIPPING };
 	if (!dependenciesInstalled({ root, platform, exists })) return { error: installHint({ root, platform }) };
+	// Without it pi fails at its first import with ERR_MODULE_NOT_FOUND for a provider's .json.
+	if (!exists(path.join(root, "packages", "ai", "src", "providers", "data", ".manifest.json")))
+		return { error: modelDataHint({ root, platform }) };
 	const resolver = path.join(root, "packages", "coding-agent", "src", "experimental", "source-resolver.ts");
 	if (!exists(resolver)) return { error: `pi's source resolver is missing from this checkout (${resolver})` };
 	// As URLs: `--import` reads a Windows path such as C:\... as a URL whose scheme is c:.
@@ -422,6 +443,28 @@ export function wantsLaya({ env, agentDir, platform, readFile }) {
 }
 
 /** The Core ML sidecar exists for macOS only. Anything else needs a server of its own behind MU_LOCAL_JUDGE_URL. */
+/**
+ * Whether the configuration asks for mude (mu judge mude): MU_JUDGE naming it, else `tiers` or a route in mu.json (or
+ * kyrn.json when there is no mu.json). Its server is then started when a session starts, as Laya's is.
+ */
+export function wantsMude({ env, agentDir, platform, readFile }) {
+	const judges = muEnv("JUDGE", env);
+	if (judges) return judges.split(",").some((judge) => judge.trim() === "mude");
+	const path = pathFor(platform);
+	for (const name of ["mu.json", "kyrn.json"]) {
+		let config;
+		try {
+			config = JSON.parse(readFile(path.join(agentDir, name)));
+		} catch (error) {
+			if (error instanceof SyntaxError) return false;
+			continue;
+		}
+		const named = (tiers) => Array.isArray(tiers) && tiers.includes("mude");
+		return named(config?.tiers) || Object.values(config?.routes ?? {}).some(named);
+	}
+	return false;
+}
+
 export function localJudgeSupport({ platform, env, wsl = false }) {
 	if (platform === "darwin") return { runs: true };
 	const url = muEnv("LOCAL_JUDGE_URL", env);
@@ -562,6 +605,14 @@ export function planLaunch({
 		}
 	}
 
+	// mude's server, when the configuration asks for it: started without waiting, so a session never waits for the
+	// model to load (what mude cannot answer yet goes to the judges behind it). Only a Mac runs it.
+	let startMude;
+	if (execPath && platform === "darwin" && wantsMude({ env: childEnv, agentDir, platform, readFile: fs.readFile })) {
+		const mude = planMude({ platform, env: childEnv, argv: ["start", "--no-wait"], root, home, execPath, fs, stripsTypes });
+		if (!mude.error) startMude = { command: mude.command, args: mude.args, env: mude.env };
+	}
+
 	return {
 		command: execPath,
 		args: [...entry, ...judgeArgs({ argv, layout, root, platform, agentDir, readFile: fs.readFile }), ...argv],
@@ -572,6 +623,7 @@ export function planLaunch({
 		appDir,
 		agentDir,
 		startJudge,
+		startMude,
 		notes,
 		preface: argv[0] === "-h" || argv[0] === "--help" ? `${usage(platform)}\n\npi's help (mu passes all of this through):\n` : undefined,
 	};
@@ -588,10 +640,17 @@ export function planLaunch({
  *
  * A checkout runs there as it runs on the command line (sourceRuntime). Returns { error } when pi cannot run.
  */
-export function planHost({ platform, env, argv, root, home, fs, wsl = false, stripsTypes = true }) {
+export function planHost({ platform, env, argv, root, home, fs, wsl = false, stripsTypes = true, nodePath, nodeEnv = {} }) {
 	const path = pathFor(platform);
 	const launch = planLaunch({ platform, env, argv, root, home, execPath: "", fs, wsl, stripsTypes });
 	if (launch.error !== undefined) return { error: launch.error };
+	// mude's server is started by a Node of the host's: `nodePath` with `nodeEnv` (Electron's own binary with
+	// ELECTRON_RUN_AS_NODE=1 in the desktop app). Without one, the host leaves it to the app.
+	let startMude;
+	if (nodePath && platform === "darwin" && wantsMude({ env: launch.env, agentDir: launch.agentDir, platform, readFile: fs.readFile })) {
+		const mude = planMude({ platform, env: { ...launch.env, ...nodeEnv }, argv: ["start", "--no-wait"], root, home, execPath: nodePath, fs, stripsTypes });
+		if (!mude.error) startMude = { command: mude.command, args: mude.args, env: mude.env };
+	}
 	const common = {
 		env: launch.env,
 		layout: launch.layout,
@@ -599,6 +658,7 @@ export function planHost({ platform, env, argv, root, home, fs, wsl = false, str
 		appDir: launch.appDir,
 		agentDir: launch.agentDir,
 		startJudge: launch.startJudge,
+		startMude,
 		notes: launch.notes,
 	};
 	if (launch.layout === "package") {
@@ -643,6 +703,7 @@ function prepareFiles({ plan, platform, root, err }) {
  */
 export function prepareLaunch({ plan, platform, root, bin, err }) {
 	prepareFiles({ plan, platform, root, err });
+	startMudeServer(plan);
 	if (plan.startJudge) {
 		const started = spawnSync(pathFor(platform).join(bin, "kyrn-judge-local"), ["start"], {
 			stdio: "ignore",
@@ -652,12 +713,32 @@ export function prepareLaunch({ plan, platform, root, bin, err }) {
 	}
 }
 
+/**
+ * mude's server, started in the background (`mu judge mude start --no-wait`): nothing waits for it, and it outlives this
+ * process, shared by every mu session like Laya. When mude is not installed it does nothing (the doctor says so).
+ */
+function startMudeServer(plan) {
+	if (!plan.startMude) return;
+	try {
+		const child = spawn(plan.startMude.command, plan.startMude.args, {
+			env: plan.startMude.env,
+			stdio: "ignore",
+			detached: true,
+		});
+		child.once("error", () => {});
+		child.unref();
+	} catch {
+		// mu works without it: the judges behind mude answer.
+	}
+}
+
 /**
  * prepareLaunch for a program that must not stop while the local judge starts, such as the desktop app's main process:
  * the same steps and notes, with the local judge started through a child process it waits for without blocking.
  */
 export async function prepareLaunchAsync({ plan, platform, root, bin, err }) {
 	prepareFiles({ plan, platform, root, err });
+	startMudeServer(plan);
 	if (!plan.startJudge) return;
 	const status = await new Promise((resolve) => {
 		const child = spawn(pathFor(platform).join(bin, "kyrn-judge-local"), ["start"], {
@@ -775,6 +856,42 @@ export function planImport({ platform, env, argv, root, home, execPath, fs, stri
 	return { command: execPath, args: [...entry, ...argv], env: childEnv, agentDir };
 }
 
+// ---------------------------------------------------------------------------------------------------------
+// mu judge mude
+// ---------------------------------------------------------------------------------------------------------
+
+/**
+ * `mu judge mude <command>` (packages/kyrn-judge/src/mude): mude on this Mac, from the checkout's TypeScript or the
+ * package's built judge/dist/mude.js. It is told where mu keeps things: the agent folder (mu.json), mu's home (the
+ * model and its environment go under local-judge/mude), the .env (its key) and the lock of its Python packages.
+ */
+export function planMude({ platform, env, argv, root, home, execPath, fs, stripsTypes = true }) {
+	const path = pathFor(platform);
+	const layout = layoutOf({ root, platform, exists: fs.exists });
+	let entry;
+	if (layout === "package") {
+		const built = packageEntries({ root, platform }).mude;
+		if (!fs.exists(built)) {
+			return { error: `This mu-agent package has no mu judge mude (${built} is missing). Update it: npm i -g mu-agent` };
+		}
+		entry = [built];
+	} else {
+		const source = path.join(root, "packages", "kyrn-judge", "src", "mude", "cli.ts");
+		if (!fs.exists(source)) return { error: `mu judge mude is missing from this checkout (${source})` };
+		if (!stripsTypes) return { error: NO_TYPE_STRIPPING };
+		entry = ["--disable-warning=ExperimentalWarning", source];
+	}
+	const muDir = muHome({ home, platform, isDir: fs.isDir });
+	const agentDir = agentDirFor({ env, muDir, platform });
+	const childEnv = {};
+	for (const [key, value] of Object.entries(env)) if (typeof value === "string") childEnv[key] = value;
+	childEnv.MU_AGENT_DIR = agentDir;
+	childEnv.MU_MUDE_HOME = muDir;
+	childEnv.MU_MUDE_ENV_FILE = envFilePath({ layout, root, muDir, platform });
+	childEnv.MU_MUDE_LOCK = path.join(root, "kyrn", "local-judge", "mude-requirements.lock.txt");
+	return { command: execPath, args: [...entry, ...argv], env: childEnv, agentDir };
+}
+
 // ---------------------------------------------------------------------------------------------------------
 // mu setup
 // ---------------------------------------------------------------------------------------------------------
@@ -1486,6 +1603,23 @@ export async function main(argv = process.argv.slice(2)) {
 			},
 		});
 	}
+	if (command === "judge" && rest[0] === "mude") {
+		const plan = planMude({
+			platform,
+			env,
+			argv: rest.slice(1),
+			root,
+			home,
+			execPath: process.execPath,
+			stripsTypes: Boolean(process.features.typescript),
+			fs: { exists: existsSync, isDir, readFile: readText },
+		});
+		if (plan.error) {
+			err(plan.error);
+			return 1;
+		}
+		return handOver({ command: plan.command, args: plan.args, env: plan.env, strategy: "spawn" });
+	}
 	if (command === "judge") {
 		const plan = planJudge({ platform, env, argv: rest, bin, wsl });
 		if (plan.kind === "script") return handOver({ command: plan.command, args: plan.args, env, strategy });