@pi-kaush/pi-agent-mode 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+- Refresh Pi's local model catalog before `/agent` model selection and baseline
+  restoration, so a long-lived session sees newly configured profile candidates
+  without using the parent's model-cycling scope. Report refresh failures without
+  changing the active agent.
+- 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,29 @@ 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. Before selecting a model, `/agent` refreshes Pi's local model catalog so
+models added during a long-lived session can be used; the parent session's
+`enabledModels` / `--models` cycling scope does not limit profile candidates.
+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.1",
+  "version": "0.2.1",
   "description": "Activate a configured Pi agent as a persistent mode in the current session.",
   "license": "MIT",
   "author": "Kaushik Gopal",
@@ -33,6 +33,9 @@
       "./src/index.ts"
     ]
   },
+  "dependencies": {
+    "@pi-kaush/pi-model-profiles": "^0.1.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.80.6",
     "@earendil-works/pi-tui": ">=0.80.6"

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;
 }
 
@@ -105,6 +107,10 @@ function loadAgentsFromDir(
           : undefined;
       const model =
         typeof frontmatter.model === "string" ? frontmatter.model : undefined;
+      const profile =
+        typeof frontmatter.profile === "string"
+          ? frontmatter.profile.trim()
+          : undefined;
 
       agents.push({
         name,
@@ -112,6 +118,7 @@ function loadAgentsFromDir(
         ...(emoji ? { emoji } : {}),
         ...(tools && tools.length > 0 ? { tools } : {}),
         ...(model ? { model } : {}),
+        ...(profile ? { profile } : {}),
         ...(typeof frontmatter.confirmProjectAgents === "boolean"
           ? { confirmProjectAgents: frontmatter.confirmProjectAgents }
           : {}),

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,
@@ -32,7 +34,7 @@ interface ModelReference {
   id: string;
 }
 
-export { parseAgentModelSpec };
+export { isModuleUnavailable, parseAgentModelSpec };
 export type { AgentModelSpec } from "./model-spec.ts";
 
 // Durable session state is namespaced so it cannot collide with other
@@ -99,6 +101,15 @@ function isActiveAgentState(value: unknown): value is ActiveAgentState {
   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;
 
@@ -137,6 +148,26 @@ export function registerAgentMode(pi: ExtensionAPI) {
     pi.appendEntry(PI_AGENT_MODE_STATE_TYPE, state);
   }
 
+  async function refreshModelCatalog(ctx: ExtensionContext): Promise<boolean> {
+    try {
+      // Activation may happen after models.json changes in a long-lived session.
+      // Pi 0.80 accepts no options; newer Pi can suppress remote catalog fetches.
+      // The cycling scope is independent of the models an agent may select.
+      await (
+        ctx.modelRegistry.refresh as (options: {
+          allowNetwork: boolean;
+        }) => void | Promise<unknown>
+      )({ allowNetwork: false });
+      return true;
+    } catch (error) {
+      ctx.ui.notify(
+        `Could not refresh model catalog: ${error instanceof Error ? error.message : error}`,
+        "error",
+      );
+      return false;
+    }
+  }
+
   function findModel(modelSpec: string, ctx: ExtensionContext) {
     const spec = modelSpec.trim();
     const separator = spec.indexOf("/");
@@ -164,6 +195,7 @@ export function registerAgentMode(pi: ExtensionAPI) {
     if (ctx.model?.provider === model.provider && ctx.model.id === model.id)
       return true;
 
+    if (!(await refreshModelCatalog(ctx))) return false;
     const resolved = ctx.modelRegistry.find(model.provider, model.id);
     if (!resolved) {
       ctx.ui.notify(
@@ -200,6 +232,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,
@@ -211,7 +304,20 @@ 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 || agent.model) && !(await refreshModelCatalog(ctx)))
+      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) {