@difflab/pi 0.1.0 → 0.2.0

package/dist/extensions/index.js

@@ -13323,11 +13323,376 @@ function rpiv_ask_user_question_default(pi) {
   registerAskUserQuestionReconciler(pi);
 }
 
+// src/modes.ts
+import {
+  getAgentDir,
+  parseFrontmatter as parseFrontmatter2
+} from "@earendil-works/pi-coding-agent";
+import { readFile as readFile2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { basename, extname, join as join5 } from "node:path";
+
+// src/assets.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { dirname as dirname2, join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveBundledAgentsDir(moduleUrl = import.meta.url) {
+  const moduleDir = dirname2(fileURLToPath(moduleUrl));
+  const candidates = [
+    join3(moduleDir, "agents"),
+    join3(moduleDir, "..", "agents"),
+    join3(moduleDir, "..", "..", "agents")
+  ];
+  return candidates.find((path) => existsSync2(path)) ?? candidates[1];
+}
+
+// src/config.ts
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { z } from "zod";
+import { homedir as homedir2 } from "node:os";
+import { join as join4 } from "node:path";
+
+// src/fsx.ts
+import { readdir, readFile } from "node:fs/promises";
+async function readDirectoryIfExists(path) {
+  try {
+    return await readdir(path, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingPath(error))
+      return [];
+    throw error;
+  }
+}
+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 = z.string().trim().min(1);
+var agentConfigSchema = z.object({
+  models: z.array(modelReferenceSchema).optional()
+}).strict();
+var diffpiConfigSchema = z.object({
+  agents: z.record(z.string(), agentConfigSchema).optional()
+}).strict();
+function diffpiConfigPaths(homeDir = homedir2()) {
+  const directory = join4(homeDir, ".difflab", "diffpi");
+  return {
+    yaml: join4(directory, "config.yaml"),
+    json: join4(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/modes.ts
+async function discoverAgentModes(options) {
+  const agentDir = options.agentDir ?? getAgentDir();
+  const homeDir = options.homeDir ?? homedir3();
+  const modes = new Map;
+  const diagnostics = [];
+  await loadAgentModes(options.bundledAgentsDir ?? BUNDLED_AGENTS_DIR, "diffpi agent", modes, diagnostics);
+  await loadAgentModes(join5(agentDir, "agents"), "user agent", modes, diagnostics);
+  if (options.includeSkills) {
+    await loadSkillModes(join5(homeDir, ".agents", "skills"), "user skill", modes, diagnostics);
+    await loadSkillModes(join5(agentDir, "skills"), "pi user skill", modes, diagnostics);
+  }
+  if (options.projectTrusted === true) {
+    if (options.includeSkills) {
+      await loadSkillModes(join5(options.cwd, ".agents", "skills"), "project skill", modes, diagnostics);
+      await loadSkillModes(join5(options.cwd, ".pi", "skills"), "pi project skill", modes, diagnostics);
+    }
+    await loadAgentModes(join5(options.cwd, ".agents", "agents"), "project agent", modes, diagnostics);
+    await loadAgentModes(join5(options.cwd, ".pi", "agents"), "pi project agent", modes, diagnostics);
+  }
+  const userConfig = await loadDiffpiConfig({ homeDir });
+  const configuredModes = [...modes.values()].map((mode) => ({
+    ...mode,
+    modelPreferences: resolveAgentModelPreferences(mode.id, mode.modelPreferences, userConfig.config)
+  }));
+  return {
+    modes: configuredModes.sort((left, right) => left.id.localeCompare(right.id)),
+    diagnostics
+  };
+}
+function resolveAgentMode(modes, requested) {
+  const name = requested.trim();
+  if (!name)
+    return { ok: false, message: "Agent name is required." };
+  const exact = modes.find((mode) => mode.id === name);
+  if (exact)
+    return { ok: true, active: exact, message: `Active inline agent: ${exact.id}.` };
+  const lowerName = name.toLowerCase();
+  const matches = modes.filter((mode) => mode.id.toLowerCase() === lowerName);
+  if (matches.length === 1) {
+    const active = matches[0];
+    return { ok: true, active, message: `Active inline agent: ${active.id}.` };
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      message: `Inline agent "${name}" is ambiguous. Use one of: ${matches.map((mode) => mode.id).join(", ")}.`
+    };
+  }
+  return { ok: false, message: `Unknown inline agent "${name}". Run /skill:mode or diffpi_modes_list.` };
+}
+function createModeController(pi, options = {}) {
+  let active;
+  let baseline;
+  const updateStatus = (ctx) => {
+    ctx.ui.setStatus(MODE_STATUS_KEY, active ? `mode: ${active.id}` : undefined);
+  };
+  const list = (ctx, listOptions = {}) => discoverAgentModes({
+    cwd: ctx.cwd,
+    agentDir: options.agentDir,
+    bundledAgentsDir: options.bundledAgentsDir,
+    homeDir: options.homeDir,
+    projectTrusted: ctx.isProjectTrusted(),
+    includeSkills: listOptions.includeSkills
+  });
+  return {
+    list,
+    async set(agent, ctx) {
+      const catalog = await list(ctx, { includeSkills: agent.includes(":") });
+      const result = resolveAgentMode(catalog.modes, agent);
+      if (!result.ok || !result.active)
+        return result;
+      baseline ??= captureRuntime(pi, ctx);
+      if (active && baseline)
+        await restoreRuntime(pi, baseline, ctx);
+      active = result.active;
+      const runtimeMessage = await applyModeRuntime(pi, active, ctx);
+      pi.appendEntry(MODE_STATE_ENTRY, { active, baseline });
+      updateStatus(ctx);
+      return { ...result, message: `${result.message} ${runtimeMessage}` };
+    },
+    async unset(ctx) {
+      if (!active)
+        return { ok: true, message: "Inline agent is already clear." };
+      if (baseline)
+        await restoreRuntime(pi, baseline, ctx);
+      active = undefined;
+      pi.appendEntry(MODE_STATE_ENTRY, { active: null });
+      baseline = undefined;
+      updateStatus(ctx);
+      return { ok: true, message: "Inline agent cleared. The previous model, thinking, tools, and prompt resume." };
+    },
+    async restore(ctx) {
+      const previousActive = active;
+      const previousBaseline = baseline;
+      const entry = [...ctx.sessionManager.getBranch()].reverse().find((candidate) => candidate.type === "custom" && candidate.customType === MODE_STATE_ENTRY);
+      const restored = entry?.data?.active;
+      const restoredBaseline = entry?.data?.baseline;
+      if (isAgentModeSnapshot(restored)) {
+        active = restored;
+        baseline = isModeBaseline(restoredBaseline) ? restoredBaseline : previousBaseline;
+        await applyModeRuntime(pi, active, ctx);
+      } else {
+        if (previousActive && previousBaseline)
+          pi.setActiveTools(previousBaseline.tools);
+        active = undefined;
+        baseline = undefined;
+      }
+      updateStatus(ctx);
+    },
+    apply(systemPrompt) {
+      if (!active)
+        return systemPrompt;
+      if (active.promptStrategy === "replace")
+        return active.systemPrompt;
+      return `${systemPrompt}
+
+## Active inline agent: ${active.label}
+
+${active.systemPrompt}`;
+    },
+    getActive() {
+      return active;
+    }
+  };
+}
+var MODE_STATE_ENTRY = "diffpi-mode-state";
+var MODE_STATUS_KEY = "diffpi-mode";
+var MODE_CONTROL_TOOLS = ["ask_user_question", "diffpi_modes_list", "diffpi_modes_set", "diffpi_modes_unset"];
+var BUNDLED_AGENTS_DIR = resolveBundledAgentsDir();
+var THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+async function applyModeRuntime(pi, mode, ctx) {
+  let selectedModel;
+  if (mode.modelPreferences.length > 0) {
+    const scoped = ctx.scopedModels.length > 0 ? ctx.scopedModels.map((entry) => entry.model) : undefined;
+    const availableModels = scoped ?? ctx.modelRegistry.getAvailable();
+    for (const preference of mode.modelPreferences) {
+      const model = findPreferredModel(availableModels, preference);
+      if (model && await pi.setModel(model)) {
+        selectedModel = `${model.provider}/${model.id}`;
+        break;
+      }
+    }
+  }
+  if (mode.thinkingLevel)
+    pi.setThinkingLevel(mode.thinkingLevel);
+  if (mode.tools.length > 0) {
+    const availableTools = new Set(pi.getAllTools().map((tool) => tool.name));
+    const selectedTools = [...new Set([...mode.tools, ...MODE_CONTROL_TOOLS])].filter((tool) => availableTools.has(tool));
+    if (selectedTools.length > 0)
+      pi.setActiveTools(selectedTools);
+  }
+  const parts = [];
+  if (mode.modelPreferences.length > 0) {
+    parts.push(selectedModel ? `Model: ${selectedModel}.` : "No preferred model was available; kept the current model.");
+  }
+  if (mode.thinkingLevel)
+    parts.push(`Thinking: ${mode.thinkingLevel}.`);
+  if (mode.tools.length > 0)
+    parts.push("Applied the profile tool set.");
+  return parts.join(" ") || "The profile changes the prompt only.";
+}
+async function restoreRuntime(pi, state, ctx) {
+  if (state.model) {
+    const model = ctx.modelRegistry.find(state.model.provider, state.model.id);
+    if (model)
+      await pi.setModel(model);
+  }
+  pi.setThinkingLevel(state.thinkingLevel);
+  pi.setActiveTools(state.tools);
+}
+function captureRuntime(pi, ctx) {
+  return {
+    model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+    thinkingLevel: pi.getThinkingLevel(),
+    tools: pi.getActiveTools()
+  };
+}
+async function loadSkillModes(skillsDir, source, modes, diagnostics) {
+  const entries = await readDirectoryIfExists(skillsDir);
+  for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+    await loadAgentModes(join5(skillsDir, entry.name, "agents"), `${source} ${entry.name}`, modes, diagnostics, entry.name);
+  }
+}
+async function loadAgentModes(directory, source, modes, diagnostics, skillName) {
+  const entries = await readDirectoryIfExists(directory);
+  for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith(".md")).sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = join5(directory, entry.name);
+    try {
+      const content = await readFile2(path, "utf8");
+      const { frontmatter, body } = parseFrontmatter2(content.startsWith("\uFEFF") ? content.slice(1) : content);
+      if (frontmatter.enabled === false || frontmatter.inline === false)
+        continue;
+      const name = getFrontmatterText(frontmatter.name) ?? basename(path, extname(path));
+      const systemPrompt = body.trim();
+      if (!name || name.includes(":") || !systemPrompt) {
+        diagnostics.push(`Skipped ${path}: agent name must not contain ":" and prompt body is required.`);
+        continue;
+      }
+      const id = skillName ? `${skillName}:${name}` : name;
+      modes.set(id, {
+        id,
+        label: getFrontmatterText(frontmatter.display_name) ?? name,
+        description: getFrontmatterText(frontmatter.description) ?? `Inline agent from ${basename(path)}`,
+        systemPrompt,
+        promptStrategy: frontmatter.prompt_mode === "append" ? "append" : "replace",
+        modelPreferences: [
+          ...getFrontmatterList(frontmatter.model),
+          ...getFrontmatterList(frontmatter.model_fallbacks)
+        ],
+        thinkingLevel: getThinkingLevel(frontmatter.thinking),
+        tools: getFrontmatterList(frontmatter.tools),
+        source,
+        sourcePath: path
+      });
+    } catch (error) {
+      diagnostics.push(`Skipped ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+function getFrontmatterText(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function getFrontmatterList(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 getThinkingLevel(value) {
+  const level = getFrontmatterText(value);
+  return level && THINKING_LEVELS.has(level) ? level : undefined;
+}
+function isAgentModeSnapshot(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  return typeof candidate.id === "string" && typeof candidate.label === "string" && typeof candidate.description === "string" && typeof candidate.systemPrompt === "string" && (candidate.promptStrategy === "append" || candidate.promptStrategy === "replace") && Array.isArray(candidate.modelPreferences) && (candidate.thinkingLevel === undefined || THINKING_LEVELS.has(candidate.thinkingLevel)) && Array.isArray(candidate.tools) && typeof candidate.source === "string" && typeof candidate.sourcePath === "string";
+}
+function isModeBaseline(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const candidate = value;
+  const model = candidate.model;
+  return (model === undefined || typeof model.provider === "string" && typeof model.id === "string") && candidate.thinkingLevel !== undefined && THINKING_LEVELS.has(candidate.thinkingLevel) && Array.isArray(candidate.tools) && candidate.tools.every((tool) => typeof tool === "string");
+}
+
 // src/tools/reload.ts
 import { defineTool } from "@earendil-works/pi-coding-agent";
-import { z } from "zod";
-var reloadParametersSchema = z.object({});
-var reloadParameters = z.toJSONSchema(reloadParametersSchema, { io: "input" });
+import { z as z2 } from "zod";
+var reloadParametersSchema = z2.object({});
+var reloadParameters = z2.toJSONSchema(reloadParametersSchema, { io: "input" });
 function createDiffpiReloadTool(pi) {
   return defineTool({
     name: "diffpi_reload",
@@ -13350,21 +13715,122 @@ 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";
+import { z as z3 } from "zod";
+var emptyParametersSchema = z3.object({});
+var emptyParameters = z3.toJSONSchema(emptyParametersSchema, { io: "input" });
+var listParametersSchema = z3.object({
+  includeSkills: z3.boolean().optional().describe("Include skill-owned agents using skill:agent ids.")
+});
+var listParameters = z3.toJSONSchema(listParametersSchema, { io: "input" });
+var setParametersSchema = z3.object({
+  agent: z3.string().trim().min(1).describe("Inline agent id from diffpi_modes_list.")
+});
+var setParameters = z3.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 homedir5 } from "node:os";
-import { join as join7 } from "node:path";
+import { parseFrontmatter as parseFrontmatter3 } from "@earendil-works/pi-coding-agent";
+import { readdir as readdir2, readFile as readFile5 } from "node:fs/promises";
+import { homedir as homedir7 } from "node:os";
+import { basename as basename3, join as join10 } from "node:path";
 
 // src/mcp.ts
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join3 } from "node:path";
+import { mkdir, readFile as readFile3, writeFile } from "node:fs/promises";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname3, join as join6 } from "node:path";
 var mcp = {
-  globalConfigPath(homeDir = homedir2()) {
-    return join3(homeDir, ".config", "mcp", "mcp.json");
+  globalConfigPath(homeDir = homedir4()) {
+    return join6(homeDir, ".config", "mcp", "mcp.json");
   },
   async serversEnsure(servers, options = {}) {
     const path = options.path ?? mcp.globalConfigPath();
@@ -13377,7 +13843,7 @@ var mcp = {
     const next = { ...current, mcpServers: nextServers };
     const changed = JSON.stringify(current) !== JSON.stringify(next);
     if (changed && !options.dryRun) {
-      await mkdir(dirname2(path), { recursive: true });
+      await mkdir(dirname3(path), { recursive: true });
       await writeFile(path, `${JSON.stringify(next, null, 2)}
 `, "utf8");
     }
@@ -13407,7 +13873,7 @@ function getParsedConfig(content, path) {
 }
 async function getOptionalFile(path) {
   try {
-    return await readFile(path, "utf8");
+    return await readFile3(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return;
@@ -13419,14 +13885,14 @@ function isRecord(value) {
 }
 
 // src/mise.ts
-import { mkdir as mkdir2, readFile as readFile2, 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";
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir5 } from "node:os";
+import { basename as basename2, dirname as dirname4, join as join8 } from "node:path";
 
 // src/process.ts
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
-import { delimiter, join as join4 } from "node:path";
+import { delimiter, join as join7 } from "node:path";
 import { spawn as spawn2 } from "node:child_process";
 var MAX_CAPTURED_OUTPUT_LENGTH = 65536;
 async function findExecutable(name) {
@@ -13441,7 +13907,7 @@ async function findExecutable(name) {
   for (const directory of (process.env.PATH ?? "").split(delimiter)) {
     if (!directory)
       continue;
-    const candidate = join4(directory, name);
+    const candidate = join7(directory, name);
     try {
       await access(candidate, constants.X_OK);
       return candidate;
@@ -13488,11 +13954,11 @@ var mise = {
     return findExecutable(name);
   },
   async install(options = {}) {
-    const homeDir = options.homeDir ?? homedir3();
+    const homeDir = options.homeDir ?? homedir5();
     const platform = options.platform ?? process.platform;
     if (platform === "win32")
       throw new Error("Automatic mise installation supports macOS and Linux only.");
-    const installedPath = join5(homeDir, ".local", "bin", "mise");
+    const installedPath = join8(homeDir, ".local", "bin", "mise");
     if (options.dryRun)
       return installedPath;
     await runChecked("sh", ["-c", "curl -fsSL https://mise.run | sh"]);
@@ -13502,8 +13968,8 @@ var mise = {
     return executable;
   },
   async hookEnsure(executable, options = {}) {
-    const homeDir = options.homeDir ?? homedir3();
-    const hook = getShellHook(basename(options.shell ?? process.env.SHELL ?? ""), executable, homeDir);
+    const homeDir = options.homeDir ?? homedir5();
+    const hook = getShellHook(basename2(options.shell ?? process.env.SHELL ?? ""), executable, homeDir);
     const current = await getOptionalFile2(hook.path);
     if (current.includes(MISE_HOOK_START))
       return { path: hook.path, changed: false, planned: false };
@@ -13512,7 +13978,7 @@ var mise = {
     const separator = current.length === 0 || current.endsWith(`
 `) ? "" : `
 `;
-    await mkdir2(dirname3(hook.path), { recursive: true });
+    await mkdir2(dirname4(hook.path), { recursive: true });
     await writeFile2(hook.path, `${current}${separator}${hook.content}`, "utf8");
     return { path: hook.path, changed: true, planned: false };
   },
@@ -13530,7 +13996,7 @@ var mise = {
   async toolInstallLocal(executable, specification, cwd = process.cwd()) {
     await runChecked(executable, ["use", "--path", cwd, specification], { cwd });
   },
-  async toolUpdateAllGlobal(executable, homeDir = homedir3()) {
+  async toolUpdateAllGlobal(executable, homeDir = homedir5()) {
     await runChecked(executable, ["upgrade"], { cwd: homeDir });
   }
 };
@@ -13539,7 +14005,7 @@ function getShellHook(shell, executable, homeDir) {
   switch (shell.toLowerCase()) {
     case "zsh":
       return {
-        path: join5(homeDir, ".zshrc"),
+        path: join8(homeDir, ".zshrc"),
         content: `${MISE_HOOK_START}
 eval "$(${command} activate zsh)"
 ${MISE_HOOK_END}
@@ -13547,7 +14013,7 @@ ${MISE_HOOK_END}
       };
     case "fish":
       return {
-        path: join5(homeDir, ".config", "fish", "config.fish"),
+        path: join8(homeDir, ".config", "fish", "config.fish"),
         content: `${MISE_HOOK_START}
 ${command} activate fish | source
 ${MISE_HOOK_END}
@@ -13556,7 +14022,7 @@ ${MISE_HOOK_END}
     case "nu":
     case "nushell":
       return {
-        path: join5(homeDir, ".config", "nushell", "config.nu"),
+        path: join8(homeDir, ".config", "nushell", "config.nu"),
         content: `${MISE_HOOK_START}
 let mise_bin = ${command}
 let mise_path = $nu.default-config-dir | path join mise.nu
@@ -13567,7 +14033,7 @@ ${MISE_HOOK_END}
       };
     case "xonsh":
       return {
-        path: join5(homeDir, ".xonshrc"),
+        path: join8(homeDir, ".xonshrc"),
         content: `${MISE_HOOK_START}
 execx($(${command} activate xonsh))
 ${MISE_HOOK_END}
@@ -13575,7 +14041,7 @@ ${MISE_HOOK_END}
       };
     case "elvish":
       return {
-        path: join5(homeDir, ".config", "elvish", "rc.elv"),
+        path: join8(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 }
@@ -13586,7 +14052,7 @@ ${MISE_HOOK_END}
     case "pwsh":
     case "powershell":
       return {
-        path: join5(homeDir, ".config", "powershell", "Microsoft.PowerShell_profile.ps1"),
+        path: join8(homeDir, ".config", "powershell", "Microsoft.PowerShell_profile.ps1"),
         content: `${MISE_HOOK_START}
 (& ${command} activate pwsh) | Out-String | Invoke-Expression
 ${MISE_HOOK_END}
@@ -13595,7 +14061,7 @@ ${MISE_HOOK_END}
     case "bash":
     default:
       return {
-        path: join5(homeDir, ".bashrc"),
+        path: join8(homeDir, ".bashrc"),
         content: `${MISE_HOOK_START}
 eval "$(${command} activate bash)"
 ${MISE_HOOK_END}
@@ -13634,7 +14100,7 @@ function isVersionAtLeast(version, minimumVersion) {
 }
 async function getOptionalFile2(path) {
   try {
-    return await readFile2(path, "utf8");
+    return await readFile4(path, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT")
       return "";
@@ -13646,79 +14112,86 @@ function getShellQuoted(value) {
 }
 
 // src/pi.ts
-import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
-import { homedir as homedir4 } from "node:os";
-import { dirname as dirname4, join as join6 } from "node:path";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { dirname as dirname5, join as join9 } 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 = join9(agentDir, "agents", filename);
+  const currentText = await readTextIfExists(path);
+  const changed = currentText !== content;
+  if (changed && !dryRun) {
+    await mkdir3(dirname5(path), { recursive: true });
+    await writeFile3(path, content, "utf8");
+  }
+  return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
+}
+async function checkGlobalPiSkill(name, agentDir = resolvePiAgentDir(), sharedSkillsDir = join9(homedir6(), ".agents", "skills")) {
+  const roots = [join9(agentDir, "skills"), sharedSkillsDir];
+  for (const root of roots) {
+    if (await readTextIfExists(join9(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 = homedir4()) {
-    return getAgentDir(homeDir);
-  },
-  async skillCheckGlobal(name, agentDir = getAgentDir(), sharedSkillsDir = join6(homedir4(), ".agents", "skills")) {
-    const roots = [join6(agentDir, "skills"), sharedSkillsDir];
-    for (const root of roots) {
-      if (await getOptionalFile3(join6(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(dirname4(path), { recursive: true });
-      await writeFile3(path, `${JSON.stringify(next, null, 2)}
-`, "utf8");
-    }
-    return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
   }
-};
-function getAgentDir(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"));
+  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(dirname5(path), { recursive: true });
+    await writeFile3(path, `${JSON.stringify(next, null, 2)}
+`, "utf8");
   }
+  return { path, changed, existed: currentText !== undefined, planned: changed && dryRun };
+}
+async function findPiExecutable() {
+  return findExecutable("pi");
+}
+async function listPiPackages(executable) {
+  return (await runChecked(executable, ["list"])).stdout;
 }
-function getParsedObject(content, path) {
+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 = homedir6()) {
+  return process.env.PI_CODING_AGENT_DIR ?? (process.env.XDG_CONFIG_HOME ? join9(process.env.XDG_CONFIG_HOME, "pi") : join9(homeDir, ".pi", "agent"));
+}
+function parseJsonObject(content, path) {
   if (!content?.trim())
     return {};
   try {
@@ -13760,9 +14233,10 @@ var PI_SKILL_SOURCES = [
   { repository: "AminBlg/SimpleEnglish", skills: ["simple-english"] }
 ];
 var MCP_ADAPTER_PACKAGE = "npm:pi-mcp-adapter";
+var BUNDLED_AGENTS_DIR2 = resolveBundledAgentsDir();
 async function ensureMise(options = {}) {
-  const homeDir = options.homeDir ?? homedir5();
-  const current = await mise.executableCheck() ?? await mise.executableCheck(join7(homeDir, ".local", "bin", "mise"));
+  const homeDir = options.homeDir ?? homedir7();
+  const current = await mise.executableCheck() ?? await mise.executableCheck(join10(homeDir, ".local", "bin", "mise"));
   if (current)
     return { executable: current, action: createSetupAction("mise", "ready", current) };
   reportProgress(options, "Installing mise");
@@ -13807,18 +14281,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(join7(agentDir, "web-search.json"), (config) => ({ ...config, workflow: "auto-summary" }), options.dryRun);
+  const webSearch = await pi.configEnsure(join10(agentDir, "web-search.json"), (config) => ({ ...config, workflow: "auto-summary" }), options.dryRun);
   actions.push(getConfigSetupAction("web search settings", webSearch));
-  const lsp = await pi.configEnsure(join7(agentDir, "pi-lsp.json"), (config) => ({
+  const lsp = await pi.configEnsure(join10(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_DIR2;
+  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 = basename3(entry.name, ".md").replace(/^diffpi-/, "");
+    const source = await readFile5(join10(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 = join7(options.homeDir ?? homedir5(), ".agents", "skills");
+  const sharedSkillsDir = join10(options.homeDir ?? homedir7(), ".agents", "skills");
   const actions = [];
   for (const source of PI_SKILL_SOURCES) {
     const missing = [];
@@ -13875,13 +14364,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 } = parseFrontmatter3(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)
@@ -13903,6 +14434,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);
@@ -13921,11 +14456,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.",
@@ -13938,11 +14473,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: {} });
       }
@@ -13950,7 +14486,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.",
@@ -13962,12 +14498,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.");
@@ -13988,31 +14525,37 @@ ${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)];
 }
 
 // extensions/index.ts
 var RELOAD_COMMAND = "diffpi-reload";
-var DOCS_ROUTING_GUIDANCE = `## Documentation routing
+var SKILL_ROUTING_GUIDANCE = `## Skill and tool routing
 Use the docs-search skill before web search for library or API documentation.
 Use docs-manage when the required documentation is absent or stale.
-Use fetch-url for a one-time read that does not belong in the documentation index.`;
+Use fetch-url for a one-time read that does not belong in the documentation index.
+Use the context-mode skill for commands, tests, builds, logs, API responses, and other output that can be large.
+Use ctx_execute or ctx_execute_file to analyze that output, and use ctx_fetch_and_index with ctx_search for external documentation.`;
 function difflabPiExtension(pi) {
   rpiv_ask_user_question_default(pi);
+  const modes = createModeController(pi);
   pi.registerCommand(RELOAD_COMMAND, {
     description: "Reload extensions, skills, prompts, themes, and context files",
     handler: async (_args, ctx) => {
       await ctx.reload();
     }
   });
-  for (const tool of createPiTools(pi))
+  for (const tool of createPiTools(pi, modes))
     pi.registerTool(tool);
-  pi.on("before_agent_start", (event) => ({
-    systemPrompt: `${event.systemPrompt}
+  pi.on("session_start", async (_event, ctx) => modes.restore(ctx));
+  pi.on("session_tree", async (_event, ctx) => modes.restore(ctx));
+  pi.on("before_agent_start", (event) => {
+    const defaultPrompt = `${event.systemPrompt}
 
-${DOCS_ROUTING_GUIDANCE}`
-  }));
+${SKILL_ROUTING_GUIDANCE}`;
+    return { systemPrompt: modes.apply(defaultPrompt) };
+  });
 }
 export {
   difflabPiExtension as default