@pi-kaush/pi-agent-mode 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Add `profile` frontmatter: activate a named model profile from the shared machine-local `~/.pi/agent/profiles.yaml` (`@pi-kaush/pi-model-profiles`), walking candidates in order and applying the first available model and thinking level.
+- Reject agents declaring both `profile` and `model`; precedence is explicit: profile first, then model, then the session default.
+- Load `@pi-kaush/pi-model-profiles` lazily so a missing library degrades only profile support; `/agent` remains fully functional without it.
+
 ## 0.1.0
 
 - Add the `/agent` command for activating a configured Pi agent as a persistent mode in the current session.

package/README.md

@@ -5,14 +5,13 @@ the session to the agent's model, thinking level, and tool set, appends the agen
 prompt to Pi's base instructions, and restores the pre-activation baseline when cleared.
 It does not spawn children and provides no delegated subagents.
 
-## Install
+### Install
 
-```sh
+```fish
 pi install npm:@pi-kaush/pi-agent-mode
 ```
 
-Restart Pi or run `/reload`. To pin a specific release, append its version, such as
-`@0.1.0`.
+Restart Pi or run `/reload`.
 
 ## Usage
 
@@ -37,11 +36,27 @@ description: ... # required
 emoji: 🔍 # optional, shown in the footer status
 tools: read, grep # optional allowlist; unavailable tools are reported and omitted
 model: provider/model:high # optional; thinking suffix may be :off/:low/:medium/:high/:max
+profile: coder # optional; named model candidates from ~/.pi/agent/profiles.yaml
 confirmProjectAgents: false # project agents default to requiring confirmation
 ---
 Prompt body appended to Pi's base instructions while the agent is active.
 ```
 
+## Model selection precedence
+
+Agent frontmatter may declare a `model` (exact model, optional thinking
+suffix) or a `profile` — a named entry in the shared machine-local
+`~/.pi/agent/profiles.yaml` maintained by
+[@pi-kaush/pi-model-profiles](../pi-model-profiles). An agent must not declare
+both. Profile candidates are walked in order at activation and the first
+model that exists and is authenticated wins; once the session is running,
+models never switch mid-request. Agents without either keep the current
+session model.
+
+`pi-agent-mode` loads `@pi-kaush/pi-model-profiles` lazily: if the library is
+missing, only agents that declare `profile:` fail (with an install hint) and
+every other `/agent` capability is unencumbered.
+
 ## Behavior
 
 - The first activation captures the current model, thinking level, and active

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-kaush/pi-agent-mode",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Activate a configured Pi agent as a persistent mode in the current session.",
   "license": "MIT",
   "author": "Kaushik Gopal",
@@ -33,12 +33,19 @@
       "./src/index.ts"
     ]
   },
+  "dependencies": {
+    "@pi-kaush/pi-model-profiles": "^0.1.0"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.80.6"
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
     }
   },
   "engines": {

package/src/agent-discovery.ts

@@ -23,6 +23,7 @@ export interface AgentConfig {
   emoji?: string;
   tools?: string[];
   model?: string;
+  profile?: string;
   confirmProjectAgents?: boolean;
   systemPrompt: string;
   source: "user" | "project";
@@ -35,6 +36,7 @@ interface AgentFrontmatter extends Record<string, unknown> {
   emoji?: string;
   tools?: string;
   model?: string;
+  profile?: string;
   confirmProjectAgents?: boolean;
 }
 
@@ -82,31 +84,51 @@ function loadAgentsFromDir(
       continue;
     }
 
-    const { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);
-
-    if (!frontmatter.name || !frontmatter.description) {
+    try {
+      const { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);
+      const name =
+        typeof frontmatter.name === "string" ? frontmatter.name : undefined;
+      const description =
+        typeof frontmatter.description === "string"
+          ? frontmatter.description
+          : undefined;
+      if (!name || !description) continue;
+
+      const tools =
+        typeof frontmatter.tools === "string"
+          ? frontmatter.tools
+              .split(",")
+              .map((tool) => tool.trim())
+              .filter(Boolean)
+          : undefined;
+      const emoji =
+        typeof frontmatter.emoji === "string"
+          ? frontmatter.emoji.trim()
+          : undefined;
+      const model =
+        typeof frontmatter.model === "string" ? frontmatter.model : undefined;
+      const profile =
+        typeof frontmatter.profile === "string"
+          ? frontmatter.profile.trim()
+          : undefined;
+
+      agents.push({
+        name,
+        description,
+        ...(emoji ? { emoji } : {}),
+        ...(tools && tools.length > 0 ? { tools } : {}),
+        ...(model ? { model } : {}),
+        ...(profile ? { profile } : {}),
+        ...(typeof frontmatter.confirmProjectAgents === "boolean"
+          ? { confirmProjectAgents: frontmatter.confirmProjectAgents }
+          : {}),
+        systemPrompt: body,
+        source,
+        filePath,
+      });
+    } catch {
       continue;
     }
-
-    const tools = frontmatter.tools
-      ?.split(",")
-      .map((t: string) => t.trim())
-      .filter(Boolean);
-
-    const emoji = frontmatter.emoji?.trim();
-    agents.push({
-      name: frontmatter.name,
-      description: frontmatter.description,
-      ...(emoji ? { emoji } : {}),
-      ...(tools && tools.length > 0 ? { tools } : {}),
-      ...(frontmatter.model ? { model: frontmatter.model } : {}),
-      ...(typeof frontmatter.confirmProjectAgents === "boolean"
-        ? { confirmProjectAgents: frontmatter.confirmProjectAgents }
-        : {}),
-      systemPrompt: body,
-      source,
-      filePath,
-    });
   }
 
   return agents;
@@ -148,14 +170,8 @@ export function discoverAgents(
 
   const agentMap = new Map<string, AgentConfig>();
 
-  if (scope === "both") {
-    for (const agent of userAgents) agentMap.set(agent.name, agent);
-    for (const agent of projectAgents) agentMap.set(agent.name, agent);
-  } else if (scope === "user") {
-    for (const agent of userAgents) agentMap.set(agent.name, agent);
-  } else {
-    for (const agent of projectAgents) agentMap.set(agent.name, agent);
-  }
+  for (const agent of userAgents) agentMap.set(agent.name, agent);
+  for (const agent of projectAgents) agentMap.set(agent.name, agent);
 
   return { agents: Array.from(agentMap.values()), projectAgentsDir };
 }

package/src/agent-picker.ts

@@ -0,0 +1,85 @@
+/**
+ * TUI picker for `/agent`: SelectList with per-item descriptions, theme
+ * colors, agent emoji kept in the label, and a ● marker on the active agent.
+ * Non-TUI modes fall back to plain ctx.ui.select in the command handler.
+ */
+
+import {
+  DynamicBorder,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  SelectList,
+  Text,
+  type SelectItem,
+} from "@earendil-works/pi-tui";
+import { formatAgentDisplayName, type AgentConfig } from "./agent-discovery.ts";
+
+export const NONE_VALUE = "none";
+
+export function buildAgentPickerItems(
+  agents: AgentConfig[],
+  activeName: string | undefined,
+): SelectItem[] {
+  const items: SelectItem[] = agents.map((agent) => {
+    const marker = agent.name === activeName ? "● " : "";
+    const origin = agent.source === "project" ? "Project agent. " : "";
+    return {
+      value: agent.name,
+      label: `${marker}${formatAgentDisplayName(agent)}`,
+      description: `${origin}${agent.description}`,
+    };
+  });
+  if (activeName) {
+    items.push({
+      value: NONE_VALUE,
+      label: "None",
+      description: "Restore the default model, thinking level, and tools",
+    });
+  }
+  return items;
+}
+
+/** Resolves with the picked agent name, NONE_VALUE, or null when cancelled. */
+export async function showAgentPicker(
+  ctx: ExtensionCommandContext,
+  items: SelectItem[],
+): Promise<string | null> {
+  return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(
+      new Text(theme.fg("accent", theme.bold("Activate agent")), 1, 0),
+    );
+
+    const list = new SelectList(items, Math.min(items.length, 10), {
+      selectedPrefix: (t: string) => theme.fg("accent", t),
+      selectedText: (t: string) => theme.fg("accent", t),
+      description: (t: string) => theme.fg("muted", t),
+      scrollInfo: (t: string) => theme.fg("dim", t),
+      noMatch: (t: string) => theme.fg("warning", t),
+    });
+    list.onSelect = (item: SelectItem) => done(item.value);
+    list.onCancel = () => done(null);
+    container.addChild(list);
+
+    container.addChild(
+      new Text(
+        theme.fg("dim", "↑↓ navigate • enter select • esc cancel   ● active"),
+        1,
+        0,
+      ),
+    );
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        list.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+}

package/src/index.ts

@@ -14,6 +14,8 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelProfilesConfig } from "@pi-kaush/pi-model-profiles";
 import {
   discoverAgents,
   formatAgentDisplayName,
@@ -21,18 +23,19 @@ import {
   type AgentConfig,
 } from "./agent-discovery.ts";
 import { parseAgentModelSpec, type ThinkingLevel } from "./model-spec.ts";
+import {
+  buildAgentPickerItems,
+  NONE_VALUE,
+  showAgentPicker,
+} from "./agent-picker.ts";
 
 interface ModelReference {
   provider: string;
   id: string;
 }
 
-export interface AgentModelSpec {
-  model: string;
-  thinkingLevel?: ThinkingLevel;
-}
-
-export { parseAgentModelSpec };
+export { isModuleUnavailable, parseAgentModelSpec };
+export type { AgentModelSpec } from "./model-spec.ts";
 
 // Durable session state is namespaced so it cannot collide with other
 // packages. Legacy Aikado sessions wrote `active-agent-state`; restore reads
@@ -62,6 +65,51 @@ interface ActiveAgentState {
   baseline?: AgentBaseline;
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isActiveAgentState(value: unknown): value is ActiveAgentState {
+  if (!isPlainObject(value) || typeof value.active !== "boolean") return false;
+  if (
+    value.active &&
+    (typeof value.name !== "string" || value.name.length === 0)
+  )
+    return false;
+
+  if (value.baseline !== undefined) {
+    if (!isPlainObject(value.baseline)) return false;
+    if (typeof value.baseline.thinkingLevel !== "string") return false;
+    if (
+      !Array.isArray(value.baseline.tools) ||
+      !value.baseline.tools.every((tool) => typeof tool === "string")
+    )
+      return false;
+
+    if (value.baseline.model !== undefined) {
+      if (
+        !isPlainObject(value.baseline.model) ||
+        typeof value.baseline.model.provider !== "string" ||
+        typeof value.baseline.model.id !== "string"
+      )
+        return false;
+    }
+  }
+
+  return true;
+}
+
+function isModuleUnavailable(error: unknown): boolean {
+  const code = (error as { code?: string } | undefined)?.code;
+  return (
+    code === "MODULE_NOT_FOUND" ||
+    code === "ERR_MODULE_NOT_FOUND" ||
+    (error instanceof Error && error.message.includes("Cannot find module"))
+  );
+}
+
 export function registerAgentMode(pi: ExtensionAPI) {
   let activeAgent: ActiveAgent | undefined;
 
@@ -163,6 +211,67 @@ export function registerAgentMode(pi: ExtensionAPI) {
     pi.setActiveTools(valid);
   }
 
+  /**
+   * Walk the agent's profile candidates in order and switch to the first
+   * model that exists and is authenticated. Fallback happens only during
+   * activation; running sessions never switch models mid-request.
+   */
+  async function applyProfileModels(
+    agent: AgentConfig,
+    ctx: ExtensionContext,
+  ): Promise<{ thinkingLevel?: ThinkingLevel } | false> {
+    let profiles: ModelProfilesConfig;
+    try {
+      // Runtime-only import: a missing @pi-kaush/pi-model-profiles degrades
+      // just profile support instead of failing the whole extension load.
+      const profilesModule = await import("@pi-kaush/pi-model-profiles");
+      profiles = profilesModule.loadModelProfiles(
+        profilesModule.resolveProfilesPath(getAgentDir()),
+      );
+    } catch (error) {
+      if (isModuleUnavailable(error)) {
+        ctx.ui.notify(
+          `Agent ${formatAgentDisplayName(agent)}: profile support unavailable; install it with pi install npm:@pi-kaush/pi-model-profiles.`,
+          "warning",
+        );
+      } else {
+        ctx.ui.notify(
+          `Agent ${formatAgentDisplayName(agent)}: ${error instanceof Error ? error.message : error}`,
+          "error",
+        );
+      }
+      return false;
+    }
+
+    const profileName = agent.profile!.trim();
+    const profile = profiles.profiles[profileName];
+    if (!profile) {
+      ctx.ui.notify(
+        `Agent ${formatAgentDisplayName(agent)}: unknown profile "${profileName}". Available: ${Object.keys(profiles.profiles).join(", ")}.`,
+        "error",
+      );
+      return false;
+    }
+
+    for (const candidate of profile.candidates) {
+      const model = findModel(candidate.model, ctx);
+      if (!model) continue;
+      if (await pi.setModel(model)) {
+        return {
+          ...(candidate.thinkingLevel !== undefined
+            ? { thinkingLevel: candidate.thinkingLevel }
+            : {}),
+        };
+      }
+    }
+
+    ctx.ui.notify(
+      `Agent ${formatAgentDisplayName(agent)}: profile "${profileName}" has no available candidate models. Configured: ${profile.candidates.map((candidate) => candidate.model).join(", ")}.`,
+      "error",
+    );
+    return false;
+  }
+
   async function activateAgent(
     agent: AgentConfig,
     ctx: ExtensionContext,
@@ -174,7 +283,18 @@ export function registerAgentMode(pi: ExtensionAPI) {
       thinkingLevel: baseline.thinkingLevel ?? pi.getThinkingLevel(),
     };
     let thinkingLevel = baseline.thinkingLevel;
-    if (agent.model) {
+    if (agent.profile && agent.model) {
+      ctx.ui.notify(
+        `Agent ${formatAgentDisplayName(agent)}: declare either "profile" or "model" in frontmatter, not both.`,
+        "error",
+      );
+      return false;
+    }
+    if (agent.profile) {
+      const applied = await applyProfileModels(agent, ctx);
+      if (!applied) return false;
+      thinkingLevel = applied.thinkingLevel ?? baseline.thinkingLevel;
+    } else if (agent.model) {
       const modelSpec = parseAgentModelSpec(agent.model);
       const model = findModel(modelSpec.model, ctx);
       if (!model) {
@@ -192,8 +312,12 @@ export function registerAgentMode(pi: ExtensionAPI) {
         return false;
       }
       thinkingLevel = modelSpec.thinkingLevel ?? baseline.thinkingLevel;
-    } else {
-      await restoreModel(baseline.model, ctx);
+    } else if (!(await restoreModel(baseline.model, ctx))) {
+      ctx.ui.notify(
+        `Agent ${formatAgentDisplayName(agent)}: could not restore the baseline model; activation aborted.`,
+        "error",
+      );
+      return false;
     }
 
     pi.setThinkingLevel(thinkingLevel);
@@ -210,15 +334,17 @@ export function registerAgentMode(pi: ExtensionAPI) {
       return;
     }
 
-    await restoreModel(activeAgent.baseline.model, ctx);
+    const modelRestored = await restoreModel(activeAgent.baseline.model, ctx);
     pi.setThinkingLevel(activeAgent.baseline.thinkingLevel);
     pi.setActiveTools(activeAgent.baseline.tools);
     activeAgent = undefined;
     updateAgentStatus(ctx);
     persistActiveAgent();
     ctx.ui.notify(
-      "Active agent cleared; previous model and tools restored.",
-      "info",
+      modelRestored
+        ? "Active agent cleared; previous model and tools restored."
+        : "Active agent cleared, but the previous model could not be restored.",
+      modelRestored ? "info" : "warning",
     );
   }
 
@@ -272,13 +398,52 @@ export function registerAgentMode(pi: ExtensionAPI) {
           );
           return;
         }
-        const choices = agents.map(
-          (candidate) =>
-            `${formatAgentDisplayName(candidate)} — ${candidate.description}`,
-        );
-        const choice = await ctx.ui.select("Activate agent:", choices);
-        if (!choice) return;
-        agent = agents[choices.indexOf(choice)];
+        let picked: string | null;
+        if (ctx.mode === "tui") {
+          picked = await showAgentPicker(
+            ctx,
+            buildAgentPickerItems(agents, activeAgent?.agent.name),
+          );
+        } else {
+          const items = buildAgentPickerItems(agents, activeAgent?.agent.name);
+          const baseLabels = items.map(
+            (item) => `${item.label} — ${item.description}`,
+          );
+          const labelCounts = new Map<string, number>();
+          for (const label of baseLabels) {
+            labelCounts.set(label, (labelCounts.get(label) ?? 0) + 1);
+          }
+          const labels = baseLabels.map((label, index) =>
+            labelCounts.get(label)! > 1
+              ? `${label} [${items[index]!.value}]`
+              : label,
+          );
+          const choice = await ctx.ui.select("Activate agent:", labels);
+          if (choice === undefined) {
+            picked = null;
+          } else {
+            const firstMatch = labels.indexOf(choice);
+            if (
+              firstMatch !== -1 &&
+              labels.lastIndexOf(choice) !== firstMatch
+            ) {
+              ctx.ui.notify(
+                "That selection matches more than one agent; rename one of the duplicates.",
+                "warning",
+              );
+              picked = null;
+            } else {
+              picked =
+                firstMatch === -1 ? null : (items[firstMatch]?.value ?? null);
+            }
+          }
+        }
+        if (!picked) return;
+        if (picked === NONE_VALUE) {
+          await clearActiveAgent(ctx);
+          return;
+        }
+        agent = agents.find((candidate) => candidate.name === picked);
       }
 
       if (!agent || !(await confirmProjectAgent(agent, ctx))) return;
@@ -302,7 +467,8 @@ export function registerAgentMode(pi: ExtensionAPI) {
       .filter(
         (entry): entry is CustomEntry<ActiveAgentState> =>
           entry.type === "custom" &&
-          ACTIVE_AGENT_STATE_TYPES.includes(entry.customType),
+          ACTIVE_AGENT_STATE_TYPES.includes(entry.customType) &&
+          isActiveAgentState(entry.data),
       )
       .pop();
     const state = stateEntry?.data;