@difflab/pi 0.1.0 → 0.2.0

package/dist/tools/index.js

@@ -25,21 +25,224 @@ function createDiffpiReloadTool(pi) {
   });
 }
 
-// src/tools/setup.ts
+// src/tools/modes.ts
 import { defineTool as defineTool2 } from "@earendil-works/pi-coding-agent";
 import { z as z2 } from "zod";
+var emptyParametersSchema = z2.object({});
+var emptyParameters = z2.toJSONSchema(emptyParametersSchema, { io: "input" });
+var listParametersSchema = z2.object({
+  includeSkills: z2.boolean().optional().describe("Include skill-owned agents using skill:agent ids.")
+});
+var listParameters = z2.toJSONSchema(listParametersSchema, { io: "input" });
+var setParametersSchema = z2.object({
+  agent: z2.string().trim().min(1).describe("Inline agent id from diffpi_modes_list.")
+});
+var setParameters = z2.toJSONSchema(setParametersSchema, { io: "input" });
+function createModeTools(controller) {
+  return [
+    defineTool2({
+      name: "diffpi_modes_list",
+      label: "diffpi modes list",
+      description: "List inline agents shared with the subagent plugin, optionally including skill-owned agents.",
+      promptSnippet: "List inline agents before selecting one when the requested agent is unclear",
+      promptGuidelines: [
+        "Call diffpi_modes_list when the user asks which inline agents are available.",
+        "Set includeSkills to true only when the user asks for skill agents or runs /skill:mode --include-skills.",
+        "Inline mode applies the profile prompt, first available preferred model, thinking level, and available tools."
+      ],
+      parameters: listParameters,
+      executionMode: "parallel",
+      async execute(_toolCallId, input, _signal, _onUpdate, ctx) {
+        const params = listParametersSchema.parse(input);
+        const catalog = await controller.list(ctx, { includeSkills: params.includeSkills });
+        return {
+          content: [{ type: "text", text: formatCatalog(catalog, controller.getActive()?.id) }],
+          details: { active: controller.getActive()?.id, catalog }
+        };
+      }
+    }),
+    defineTool2({
+      name: "diffpi_modes_set",
+      label: "diffpi modes set",
+      description: "Set a validated available agent as the inline behavioral agent for subsequent chat turns.",
+      promptSnippet: "Set the inline behavioral agent only after the user chooses one",
+      promptGuidelines: [
+        "Call diffpi_modes_set only after the user explicitly selects an agent.",
+        "Use the exact skill:agent id for a skill-owned agent.",
+        "The selected prompt takes effect on the next model turn."
+      ],
+      parameters: setParameters,
+      executionMode: "sequential",
+      async execute(_toolCallId, input, _signal, _onUpdate, ctx) {
+        const params = setParametersSchema.parse(input);
+        const result = await controller.set(params.agent, ctx);
+        if (!result.ok)
+          throw new Error(result.message);
+        return {
+          content: [{ type: "text", text: `${result.message} The prompt takes effect on the next turn.` }],
+          details: { active: result.active }
+        };
+      }
+    }),
+    defineTool2({
+      name: "diffpi_modes_unset",
+      label: "diffpi modes unset",
+      description: "Clear the inline behavioral agent and restore default Pi prompting for subsequent turns.",
+      promptSnippet: "Clear the inline agent when the user asks for default behavior",
+      promptGuidelines: [
+        "Call diffpi_modes_unset only when the user explicitly asks to clear the active inline agent."
+      ],
+      parameters: emptyParameters,
+      executionMode: "sequential",
+      async execute(_toolCallId, input, _signal, _onUpdate, ctx) {
+        emptyParametersSchema.parse(input);
+        const result = await controller.unset(ctx);
+        return {
+          content: [{ type: "text", text: result.message }],
+          details: { active: controller.getActive()?.id }
+        };
+      }
+    })
+  ];
+}
+function formatCatalog(catalog, active) {
+  const lines = [`Active inline agent: ${active ?? "default"}.`, "", "Available inline agents:"];
+  for (const mode of catalog.modes) {
+    const runtime = [mode.modelPreferences[0], mode.thinkingLevel].filter(Boolean).join(", ");
+    lines.push(`- ${mode.id} [${mode.promptStrategy}${runtime ? `; ${runtime}` : ""}] — ${sanitize(mode.description)} (${mode.source})`);
+  }
+  if (catalog.diagnostics.length > 0) {
+    lines.push("", "Skipped agent files:");
+    for (const diagnostic of catalog.diagnostics)
+      lines.push(`- ${sanitize(diagnostic)}`);
+  }
+  lines.push("", "Inline mode applies the profile prompt, preferred available model, thinking level, and tool set.");
+  return lines.join(`
+`);
+}
+function sanitize(value) {
+  return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+// src/tools/setup.ts
+import { defineTool as defineTool3 } from "@earendil-works/pi-coding-agent";
+import { z as z4 } from "zod";
 
 // src/setup.ts
-import { homedir as homedir4 } from "node:os";
-import { join as join5 } from "node:path";
+import { parseFrontmatter as parseFrontmatter2 } from "@earendil-works/pi-coding-agent";
+import { readdir as readdir2, readFile as readFile4 } from "node:fs/promises";
+import { homedir as homedir5 } from "node:os";
+import { basename as basename2, join as join7 } from "node:path";
 
-// src/mcp.ts
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+// src/assets.ts
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveBundledAgentsDir(moduleUrl = import.meta.url) {
+  const moduleDir = dirname(fileURLToPath(moduleUrl));
+  const candidates = [
+    join(moduleDir, "agents"),
+    join(moduleDir, "..", "agents"),
+    join(moduleDir, "..", "..", "agents")
+  ];
+  return candidates.find((path) => existsSync(path)) ?? candidates[1];
+}
+
+// src/config.ts
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { z as z3 } from "zod";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/fsx.ts
+import { readdir, readFile } from "node:fs/promises";
+async function readTextIfExists(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissingPath(error))
+      return;
+    throw error;
+  }
+}
+function isMissingPath(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+// src/config.ts
+var modelReferenceSchema = z3.string().trim().min(1);
+var agentConfigSchema = z3.object({
+  models: z3.array(modelReferenceSchema).optional()
+}).strict();
+var diffpiConfigSchema = z3.object({
+  agents: z3.record(z3.string(), agentConfigSchema).optional()
+}).strict();
+function diffpiConfigPaths(homeDir = homedir()) {
+  const directory = join2(homeDir, ".difflab", "diffpi");
+  return {
+    yaml: join2(directory, "config.yaml"),
+    json: join2(directory, "config.json")
+  };
+}
+async function loadDiffpiConfig(options = {}) {
+  const paths = diffpiConfigPaths(options.homeDir);
+  for (const [format, path] of [
+    ["yaml", paths.yaml],
+    ["json", paths.json]
+  ]) {
+    const content = await readTextIfExists(path);
+    if (content === undefined)
+      continue;
+    try {
+      const value = format === "yaml" ? parseYamlConfig(content) : JSON.parse(content);
+      return { config: diffpiConfigSchema.parse(value ?? {}), path };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(`Invalid Diffpi config at ${path}: ${reason}`, { cause: error });
+    }
+  }
+  return { config: {} };
+}
+function resolveAgentModelPreferences(agentId, profilePreferences, config) {
+  const override = config.agents?.[agentId];
+  if (override && Object.hasOwn(override, "models"))
+    return [...override.models ?? []];
+  return [...profilePreferences];
+}
+function findPreferredModel(models, preference) {
+  const normalizedPreference = normalizeModelReference(preference);
+  const exactReference = models.find((model) => normalizeModelReference(`${model.provider}/${model.id}`) === normalizedPreference);
+  if (exactReference)
+    return exactReference;
+  const idPreference = preference.includes("/") ? preference.slice(preference.indexOf("/") + 1) : preference;
+  const normalizedIdPreference = normalizeModelReference(idPreference);
+  const exactId = models.find((model) => normalizeModelReference(model.id) === normalizedIdPreference);
+  if (exactId)
+    return exactId;
+  const preferenceTokens = normalizedIdPreference.split("-").filter(Boolean);
+  return models.find((model) => {
+    const modelTokens = new Set(normalizeModelReference(model.id).split("-").filter(Boolean));
+    return preferenceTokens.every((token) => modelTokens.has(token));
+  });
+}
+function parseYamlConfig(content) {
+  const document = content.replace(/^\uFEFF/, "").replace(/^---[^\S\r\n]*(?:#.*)?(?:\r?\n|$)/, "");
+  return parseFrontmatter(`---
+${document}
+---
+`).frontmatter;
+}
+function normalizeModelReference(value) {
+  return value.toLowerCase().replace(/^~/, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+// src/mcp.ts
+import { mkdir, readFile as readFile2, writeFile } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join3 } from "node:path";
 var mcp = {
-  globalConfigPath(homeDir = homedir()) {
-    return join(homeDir, ".config", "mcp", "mcp.json");
+  globalConfigPath(homeDir = homedir2()) {
+    return join3(homeDir, ".config", "mcp", "mcp.json");
   },
   async serversEnsure(servers, options = {}) {
     const path = options.path ?? mcp.globalConfigPath();
@@ -52,7 +255,7 @@ var mcp = {
     const next = { ...current, mcpServers: nextServers };
     const changed = JSON.stringify(current) !== JSON.stringify(next);
     if (changed && !options.dryRun) {
-      await mkdir(dirname(path), { recursive: true });
+      await mkdir(dirname2(path), { recursive: true });
       await writeFile(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
     }
@@ -82,7 +285,7 @@ function getParsedConfig(content, path) {
 }
 async function getOptionalFile(path) {
   try {
-    return await readFile(path, "utf8");
+    return await readFile2(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return;
@@ -94,14 +297,14 @@ function isRecord(value) {
 }
 
 // src/mise.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { basename, dirname as dirname2, join as join3 } from "node:path";
+import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { basename, dirname as dirname3, join as join5 } from "node:path";
 
 // src/process.ts
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
-import { delimiter, join as join2 } from "node:path";
+import { delimiter, join as join4 } from "node:path";
 import { spawn } from "node:child_process";
 var MAX_CAPTURED_OUTPUT_LENGTH = 65536;
 async function findExecutable(name) {
@@ -116,7 +319,7 @@ async function findExecutable(name) {
   for (const directory of (process.env.PATH ?? "").split(delimiter)) {
     if (!directory)
       continue;
-    const candidate = join2(directory, name);
+    const candidate = join4(directory, name);
     try {
       await access(candidate, constants.X_OK);
       return candidate;
@@ -163,11 +366,11 @@ var mise = {
     return findExecutable(name);
   },
   async install(options = {}) {
-    const homeDir = options.homeDir ?? homedir2();
+    const homeDir = options.homeDir ?? homedir3();
     const platform = options.platform ?? process.platform;
     if (platform === "win32")
       throw new Error("Automatic mise installation supports macOS and Linux only.");
-    const installedPath = join3(homeDir, ".local", "bin", "mise");
+    const installedPath = join5(homeDir, ".local", "bin", "mise");
     if (options.dryRun)
       return installedPath;
     await runChecked("sh", ["-c", "curl -fsSL https://mise.run | sh"]);
@@ -177,7 +380,7 @@ var mise = {
     return executable;
   },
   async hookEnsure(executable, options = {}) {
-    const homeDir = options.homeDir ?? homedir2();
+    const homeDir = options.homeDir ?? homedir3();
     const hook = getShellHook(basename(options.shell ?? process.env.SHELL ?? ""), executable, homeDir);
     const current = await getOptionalFile2(hook.path);
     if (current.includes(MISE_HOOK_START))
@@ -187,7 +390,7 @@ var mise = {
     const separator = current.length === 0 || current.endsWith(`
 `) ? "" : `
 `;
-    await mkdir2(dirname2(hook.path), { recursive: true });
+    await mkdir2(dirname3(hook.path), { recursive: true });
     await writeFile2(hook.path, `${current}${separator}${hook.content}`, "utf8");
     return { path: hook.path, changed: true, planned: false };
   },
@@ -205,7 +408,7 @@ var mise = {
   async toolInstallLocal(executable, specification, cwd = process.cwd()) {
     await runChecked(executable, ["use", "--path", cwd, specification], { cwd });
   },
-  async toolUpdateAllGlobal(executable, homeDir = homedir2()) {
+  async toolUpdateAllGlobal(executable, homeDir = homedir3()) {
     await runChecked(executable, ["upgrade"], { cwd: homeDir });
   }
 };
@@ -214,7 +417,7 @@ function getShellHook(shell, executable, homeDir) {
   switch (shell.toLowerCase()) {
     case "zsh":
       return {
-        path: join3(homeDir, ".zshrc"),
+        path: join5(homeDir, ".zshrc"),
         content: `${MISE_HOOK_START}
 eval "$(${command} activate zsh)"
 ${MISE_HOOK_END}
@@ -222,7 +425,7 @@ ${MISE_HOOK_END}
       };
     case "fish":
       return {
-        path: join3(homeDir, ".config", "fish", "config.fish"),
+        path: join5(homeDir, ".config", "fish", "config.fish"),
         content: `${MISE_HOOK_START}
 ${command} activate fish | source
 ${MISE_HOOK_END}
@@ -231,7 +434,7 @@ ${MISE_HOOK_END}
     case "nu":
     case "nushell":
       return {
-        path: join3(homeDir, ".config", "nushell", "config.nu"),
+        path: join5(homeDir, ".config", "nushell", "config.nu"),
         content: `${MISE_HOOK_START}
 let mise_bin = ${command}
 let mise_path = $nu.default-config-dir | path join mise.nu
@@ -242,7 +445,7 @@ ${MISE_HOOK_END}
       };
     case "xonsh":
       return {
-        path: join3(homeDir, ".xonshrc"),
+        path: join5(homeDir, ".xonshrc"),
         content: `${MISE_HOOK_START}
 execx($(${command} activate xonsh))
 ${MISE_HOOK_END}
@@ -250,7 +453,7 @@ ${MISE_HOOK_END}
       };
     case "elvish":
       return {
-        path: join3(homeDir, ".config", "elvish", "rc.elv"),
+        path: join5(homeDir, ".config", "elvish", "rc.elv"),
         content: `${MISE_HOOK_START}
 var mise: = (ns [&])
 eval (${command} activate elvish | slurp) &ns=$mise: &on-end={|ns| set mise: = $ns }
@@ -261,7 +464,7 @@ ${MISE_HOOK_END}
     case "pwsh":
     case "powershell":
       return {
-        path: join3(homeDir, ".config", "powershell", "Microsoft.PowerShell_profile.ps1"),
+        path: join5(homeDir, ".config", "powershell", "Microsoft.PowerShell_profile.ps1"),
         content: `${MISE_HOOK_START}
 (& ${command} activate pwsh) | Out-String | Invoke-Expression
 ${MISE_HOOK_END}
@@ -270,7 +473,7 @@ ${MISE_HOOK_END}
     case "bash":
     default:
       return {
-        path: join3(homeDir, ".bashrc"),
+        path: join5(homeDir, ".bashrc"),
         content: `${MISE_HOOK_START}
 eval "$(${command} activate bash)"
 ${MISE_HOOK_END}
@@ -309,7 +512,7 @@ function isVersionAtLeast(version, minimumVersion) {
 }
 async function getOptionalFile2(path) {
   try {
-    return await readFile2(path, "utf8");
+    return await readFile3(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return "";
@@ -321,79 +524,86 @@ function getShellQuoted(value) {
 }
 
 // src/pi.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
-import { homedir as homedir3 } from "node:os";
-import { dirname as dirname3, join as join4 } from "node:path";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname4, join as join6 } from "node:path";
 var pi = {
-  async executableCheck() {
-    return findExecutable("pi");
-  },
-  async packageList(executable) {
-    return (await runChecked(executable, ["list"])).stdout;
-  },
-  packageCheck(listOutput, source) {
-    if (listOutput.includes(source))
+  executableCheck: findPiExecutable,
+  packageList: listPiPackages,
+  packageCheck: hasPiPackage,
+  packageInstall: installPiPackage,
+  agentDir: resolvePiAgentDir,
+  agentEnsure: ensurePiAgent,
+  skillCheckGlobal: checkGlobalPiSkill,
+  skillInstallGlobal: installGlobalPiSkills,
+  configEnsure: ensurePiConfig
+};
+async function ensurePiAgent(filename, content, agentDir = resolvePiAgentDir(), dryRun = false) {
+  const path = join6(agentDir, "agents", filename);
+  const currentText = await readTextIfExists(path);
+  const changed = currentText !== content;
+  if (changed && !dryRun) {
+    await mkdir3(dirname4(path), { recursive: true });
+    await writeFile3(path, content, "utf8");
+  }
+  return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
+}
+async function checkGlobalPiSkill(name, agentDir = resolvePiAgentDir(), sharedSkillsDir = join6(homedir4(), ".agents", "skills")) {
+  const roots = [join6(agentDir, "skills"), sharedSkillsDir];
+  for (const root of roots) {
+    if (await readTextIfExists(join6(root, name, "SKILL.md")) !== undefined)
       return true;
-    return source.startsWith("https://") && listOutput.includes(source.slice("https://".length));
-  },
-  async packageInstall(executable, source) {
-    await runChecked(executable, ["install", source]);
-  },
-  agentDir(homeDir = homedir3()) {
-    return getAgentDir(homeDir);
-  },
-  async skillCheckGlobal(name, agentDir = getAgentDir(), sharedSkillsDir = join4(homedir3(), ".agents", "skills")) {
-    const roots = [join4(agentDir, "skills"), sharedSkillsDir];
-    for (const root of roots) {
-      if (await getOptionalFile3(join4(root, name, "SKILL.md")) !== undefined)
-        return true;
-    }
-    return false;
-  },
-  async skillInstallGlobal(miseExecutable, source, names) {
-    const selection = names.flatMap((name) => ["--skill", name]);
-    await runChecked(miseExecutable, [
-      "x",
-      "node@22",
-      "--",
-      "npx",
-      "-y",
-      "skills",
-      "add",
-      source,
-      ...selection,
-      "--global",
-      "--agent",
-      "pi",
-      "--yes"
-    ]);
-  },
-  async configEnsure(path, update, dryRun = false) {
-    const currentText = await getOptionalFile3(path);
-    const current = getParsedObject(currentText, path);
-    const next = update(current);
-    const changed = JSON.stringify(current) !== JSON.stringify(next);
-    if (changed && !dryRun) {
-      await mkdir3(dirname3(path), { recursive: true });
-      await writeFile3(path, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-    }
-    return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
   }
-};
-function getAgentDir(homeDir = homedir3()) {
-  return process.env.PI_CODING_AGENT_DIR ?? (process.env.XDG_CONFIG_HOME ? join4(process.env.XDG_CONFIG_HOME, "pi") : join4(homeDir, ".pi", "agent"));
+  return false;
 }
-async function getOptionalFile3(path) {
-  try {
-    return await readFile3(path, "utf8");
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT")
-      return;
-    throw error;
+async function installGlobalPiSkills(miseExecutable, source, names) {
+  const selection = names.flatMap((name) => ["--skill", name]);
+  await runChecked(miseExecutable, [
+    "x",
+    "node@22",
+    "--",
+    "npx",
+    "-y",
+    "skills",
+    "add",
+    source,
+    ...selection,
+    "--global",
+    "--agent",
+    "pi",
+    "--yes"
+  ]);
+}
+async function ensurePiConfig(path, update, dryRun = false) {
+  const currentText = await readTextIfExists(path);
+  const current = parseJsonObject(currentText, path);
+  const next = update(current);
+  const changed = JSON.stringify(current) !== JSON.stringify(next);
+  if (changed && !dryRun) {
+    await mkdir3(dirname4(path), { recursive: true });
+    await writeFile3(path, `${JSON.stringify(next, null, 2)}
+`, "utf8");
   }
+  return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
 }
-function getParsedObject(content, path) {
+async function findPiExecutable() {
+  return findExecutable("pi");
+}
+async function listPiPackages(executable) {
+  return (await runChecked(executable, ["list"])).stdout;
+}
+function hasPiPackage(listOutput, source) {
+  if (listOutput.includes(source))
+    return true;
+  return source.startsWith("https://") && listOutput.includes(source.slice("https://".length));
+}
+async function installPiPackage(executable, source) {
+  await runChecked(executable, ["install", source]);
+}
+function resolvePiAgentDir(homeDir = homedir4()) {
+  return process.env.PI_CODING_AGENT_DIR ?? (process.env.XDG_CONFIG_HOME ? join6(process.env.XDG_CONFIG_HOME, "pi") : join6(homeDir, ".pi", "agent"));
+}
+function parseJsonObject(content, path) {
   if (!content?.trim())
     return {};
   try {
@@ -435,9 +645,10 @@ var PI_SKILL_SOURCES = [
   { repository: "AminBlg/SimpleEnglish", skills: ["simple-english"] }
 ];
 var MCP_ADAPTER_PACKAGE = "npm:pi-mcp-adapter";
+var BUNDLED_AGENTS_DIR = resolveBundledAgentsDir();
 async function ensureMise(options = {}) {
-  const homeDir = options.homeDir ?? homedir4();
-  const current = await mise.executableCheck() ?? await mise.executableCheck(join5(homeDir, ".local", "bin", "mise"));
+  const homeDir = options.homeDir ?? homedir5();
+  const current = await mise.executableCheck() ?? await mise.executableCheck(join7(homeDir, ".local", "bin", "mise"));
   if (current)
     return { executable: current, action: createSetupAction("mise", "ready", current) };
   reportProgress(options, "Installing mise");
@@ -482,18 +693,33 @@ async function ensureMiseDeps(miseExecutable, options = {}) {
 async function ensurePiPlugins(options = {}) {
   const actions = await ensurePiPackages(PI_PACKAGES, options);
   const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
-  const webSearch = await pi.configEnsure(join5(agentDir, "web-search.json"), (config) => ({ ...config, workflow: "auto-summary" }), options.dryRun);
+  const webSearch = await pi.configEnsure(join7(agentDir, "web-search.json"), (config) => ({ ...config, workflow: "auto-summary" }), options.dryRun);
   actions.push(getConfigSetupAction("web search settings", webSearch));
-  const lsp = await pi.configEnsure(join5(agentDir, "pi-lsp.json"), (config) => ({
+  const lsp = await pi.configEnsure(join7(agentDir, "pi-lsp.json"), (config) => ({
     ...config,
     progressive: { ...getRecord(config.progressive), enabled: true, inject: "none" }
   }), options.dryRun);
   actions.push(getConfigSetupAction("pi-lsp settings", lsp));
   return actions;
 }
+async function ensurePiAgents(options = {}) {
+  const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
+  const bundledAgentsDir = options.bundledAgentsDir ?? BUNDLED_AGENTS_DIR;
+  const userConfig = await loadDiffpiConfig({ homeDir: options.homeDir });
+  const entries = (await readdir2(bundledAgentsDir, { withFileTypes: true })).filter((entry) => entry.isFile() && entry.name.startsWith("diffpi-") && entry.name.endsWith(".md")).sort((left, right) => left.name.localeCompare(right.name));
+  const actions = [];
+  for (const entry of entries) {
+    const id = basename2(entry.name, ".md").replace(/^diffpi-/, "");
+    const source = await readFile4(join7(bundledAgentsDir, entry.name), "utf8");
+    const content = materializeAgentModels(source, id, userConfig.config, options.availableModels);
+    const result = await pi.agentEnsure(entry.name, content, agentDir, options.dryRun);
+    actions.push(getConfigSetupAction(`pi agent ${id}`, result));
+  }
+  return actions;
+}
 async function ensurePiSkills(miseExecutable, options = {}) {
   const agentDir = options.agentDir ?? pi.agentDir(options.homeDir);
-  const sharedSkillsDir = join5(options.homeDir ?? homedir4(), ".agents", "skills");
+  const sharedSkillsDir = join7(options.homeDir ?? homedir5(), ".agents", "skills");
   const actions = [];
   for (const source of PI_SKILL_SOURCES) {
     const missing = [];
@@ -550,13 +776,55 @@ async function setupPi(options = {}) {
   actions.push(await ensureMiseHooks(miseResult.executable, options));
   actions.push(...await ensureMiseDeps(miseResult.executable, options));
   actions.push(...await ensurePiPlugins(options));
+  actions.push(...await ensurePiAgents(options));
   actions.push(...await ensurePiSkills(miseResult.executable, options));
   actions.push(...await ensureMcpAdapters(miseResult.executable, options));
   return {
     actions,
-    restartPi: actions.some((item) => (item.status === "installed" || item.status === "updated") && (item.name.startsWith("pi package ") || item.name.startsWith("pi skill ") || item.name === "MCP configuration" || item.name === "web search settings" || item.name === "pi-lsp settings"))
+    restartPi: setupRequiresRestart(actions)
   };
 }
+function setupRequiresRestart(actions) {
+  return actions.some((item) => (item.status === "installed" || item.status === "updated") && (item.name.startsWith("pi package ") || item.name.startsWith("pi agent ") || item.name.startsWith("pi skill ") || item.name === "MCP configuration" || item.name === "web search settings" || item.name === "pi-lsp settings"));
+}
+function materializeAgentModels(content, agentId, config, availableModels) {
+  const { frontmatter } = parseFrontmatter2(content.startsWith("\uFEFF") ? content.slice(1) : content);
+  const profilePreferences = [...getTextList(frontmatter.model), ...getTextList(frontmatter.model_fallbacks)];
+  const preferences = resolveAgentModelPreferences(agentId, profilePreferences, config);
+  let selectedIndex = availableModels === undefined && preferences.length > 0 ? 0 : -1;
+  let selectedModel = selectedIndex === 0 ? preferences[0] : undefined;
+  if (availableModels) {
+    for (const [index, preference] of preferences.entries()) {
+      const match = findPreferredModel(availableModels, preference);
+      if (!match)
+        continue;
+      selectedIndex = index;
+      selectedModel = `${match.provider}/${match.id}`;
+      break;
+    }
+  }
+  const fallbacks = preferences.filter((_preference, index) => index !== selectedIndex);
+  return replaceAgentModelFields(content, selectedModel, fallbacks);
+}
+function replaceAgentModelFields(content, model, fallbacks) {
+  const newline = content.includes(`\r
+`) ? `\r
+` : `
+`;
+  const lines = content.replaceAll(`\r
+`, `
+`).split(`
+`);
+  const closingDelimiter = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || closingDelimiter < 0)
+    return content;
+  const frontmatter = lines.slice(1, closingDelimiter).filter((line) => !/^model(?:_fallbacks)?:/.test(line));
+  if (model)
+    frontmatter.push(`model: ${model}`);
+  if (fallbacks.length > 0)
+    frontmatter.push(`model_fallbacks: ${fallbacks.join(", ")}`);
+  return ["---", ...frontmatter, "---", ...lines.slice(closingDelimiter + 1)].join(newline);
+}
 async function ensurePiPackages(packages, options) {
   const executable = await pi.executableCheck();
   if (!executable && !options.dryRun)
@@ -578,6 +846,10 @@ ${source}`;
   }
   return actions;
 }
+function getTextList(value) {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  return values.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+}
 function getConfigSetupAction(name, result) {
   if (!result.changed)
     return createSetupAction(name, "ready", result.path);
@@ -596,11 +868,11 @@ function getRecord(value) {
 }
 
 // src/tools/setup.ts
-var setupParametersSchema = z2.object({
-  issueTracker: z2.enum(["none", "linear", "jira"]).default("none").describe("Issue tracker MCP server to configure. Use none unless the user explicitly selects Linear or Jira.")
+var setupParametersSchema = z4.object({
+  issueTracker: z4.enum(["none", "linear", "jira"]).default("none").describe("Issue tracker MCP server to configure. Use none unless the user explicitly selects Linear or Jira.")
 });
-var setupParameters = z2.toJSONSchema(setupParametersSchema, { io: "input" });
-var diffpiSetupTool = defineTool2({
+var setupParameters = z4.toJSONSchema(setupParametersSchema, { io: "input" });
+var diffpiSetupTool = defineTool3({
   name: "diffpi_setup",
   label: "diffpi setup",
   description: "Install or repair the @difflab/pi environment. This mutates user-level tool installations and configuration files.",
@@ -613,11 +885,12 @@ var diffpiSetupTool = defineTool2({
   ],
   parameters: setupParameters,
   executionMode: "sequential",
-  async execute(_toolCallId, input, _signal, onUpdate) {
+  async execute(_toolCallId, input, _signal, onUpdate, ctx) {
     const params = setupParametersSchema.parse(input);
     const result = await setupPi({
       issueTracker: params.issueTracker,
       installMiseHook: true,
+      availableModels: ctx.modelRegistry.getAvailable(),
       onProgress(message) {
         onUpdate?.({ content: [{ type: "text", text: message }], details: {} });
       }
@@ -625,7 +898,7 @@ var diffpiSetupTool = defineTool2({
     return formatResult(result, "Setup complete.");
   }
 });
-var diffpiValidateTool = defineTool2({
+var diffpiValidateTool = defineTool3({
   name: "diffpi_validate",
   label: "diffpi validate",
   description: "Inspect the @difflab/pi environment without installing software or changing configuration files.",
@@ -637,12 +910,13 @@ var diffpiValidateTool = defineTool2({
   ],
   parameters: setupParameters,
   executionMode: "sequential",
-  async execute(_toolCallId, input) {
+  async execute(_toolCallId, input, _signal, _onUpdate, ctx) {
     const params = setupParametersSchema.parse(input);
     const result = await setupPi({
       issueTracker: params.issueTracker,
       installMiseHook: true,
-      dryRun: true
+      dryRun: true,
+      availableModels: ctx.modelRegistry.getAvailable()
     });
     const incomplete = result.actions.some((item) => item.status === "planned");
     return formatResult(result, incomplete ? "Setup is incomplete." : "Setup is ready.");
@@ -663,11 +937,12 @@ ${lines.join(`
 }
 
 // src/tools/index.ts
-function createPiTools(pi) {
-  return [diffpiSetupTool, diffpiValidateTool, createDiffpiReloadTool(pi)];
+function createPiTools(pi, modes) {
+  return [diffpiSetupTool, diffpiValidateTool, createDiffpiReloadTool(pi), ...createModeTools(modes)];
 }
 export {
   createDiffpiReloadTool,
+  createModeTools,
   createPiTools,
   diffpiSetupTool,
   diffpiValidateTool