@pi-kaush/pi-agent-mode 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Add the `/agent` command for activating a configured Pi agent as a persistent mode in the current session.
+- Support `/agent <name>`, an interactive selector, and `/agent none` / `/agent off` restoration of the pre-activation baseline.
+- Capture model, thinking level, and active tools as one baseline on first activation; keep it across agent switches.
+- Append agent prompts to Pi's base prompt, apply tool allowlists with missing-tool reporting, and support model thinking suffixes (`:low`, `:high`, `:max`).
+- Restore the last active agent across session resume and reload, reading both the namespaced `pi-agent-mode/state` entry and legacy `active-agent-state` entries (newest recognized entry on the active branch wins).
+- Keep the package standalone with zero runtime dependencies: discovery and display helpers are self-contained and no delegated-subagent runner is required.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaushik Gopal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# pi-agent-mode
+
+Activates a configured Pi agent as a persistent mode in the current session. It switches
+the session to the agent's model, thinking level, and tool set, appends the agent's
+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
+
+```sh
+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`.
+
+## Usage
+
+```text
+/agent               open an agent selector
+/agent <name>        activate the named user or project agent
+/agent none          restore the pre-activation model, thinking level, and tools
+/agent off           same as /agent none
+```
+
+Agent definitions come from Markdown files in Pi's user agent directory
+(`~/.pi/agent/agents/*.md`) or the nearest project `agents/` directory (project
+agents take precedence by name and are confirmed before activation unless the
+agent sets `confirmProjectAgents: false`).
+
+Supported frontmatter:
+
+```yaml
+---
+name: reviewer # required
+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
+confirmProjectAgents: false # project agents default to requiring confirmation
+---
+Prompt body appended to Pi's base instructions while the agent is active.
+```
+
+## Behavior
+
+- The first activation captures the current model, thinking level, and active
+  tools as one baseline. Switching agents keeps that original baseline, so
+  clearing always returns to the pre-`/agent` session state.
+- Missing models or failed authentication abort activation without corrupting
+  the previous state.
+- The active agent survives session resume and reload; the footer status shows
+  the active agent, including its emoji when configured.
+- Durable state is written as a namespaced `pi-agent-mode/state` session entry.
+  Legacy `active-agent-state` entries from earlier local implementations are
+  still read on resume; the newest recognized entry on the active branch wins.
+
+## Development
+
+```sh
+npm run check
+npm pack --workspace @pi-kaush/pi-agent-mode --dry-run
+```
+
+Load the live source in isolation:
+
+```sh
+pi --no-extensions -e ~/dev/oss/pi-kaush/extensions/pi-agent-mode/src/index.ts
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pi-kaush/pi-agent-mode",
+  "version": "0.1.0",
+  "description": "Activate a configured Pi agent as a persistent mode in the current session.",
+  "license": "MIT",
+  "author": "Kaushik Gopal",
+  "type": "module",
+  "exports": "./src/index.ts",
+  "types": "./src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agent",
+    "mode"
+  ],
+  "homepage": "https://github.com/kaushikgopal/pi-kaush/tree/main/extensions/pi-agent-mode#readme",
+  "bugs": {
+    "url": "https://github.com/kaushikgopal/pi-kaush/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaushikgopal/pi-kaush.git",
+    "directory": "extensions/pi-agent-mode"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.6"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "package:check": "node ./scripts/check-package.mjs"
+  },
+  "sideEffects": false
+}

package/src/agent-discovery.ts

@@ -0,0 +1,168 @@
+/**
+ * Agent discovery for `/agent` mode activation.
+ *
+ * Discovery reads Markdown agent definitions from Pi's user agent directory
+ * and the nearest project `agents/` directory. Agent Markdown files remain
+ * the source of persona/model/tool definitions; this module never spawns
+ * children or runs delegated subagents.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  parseFrontmatter,
+} from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  emoji?: string;
+  tools?: string[];
+  model?: string;
+  confirmProjectAgents?: boolean;
+  systemPrompt: string;
+  source: "user" | "project";
+  filePath: string;
+}
+
+interface AgentFrontmatter extends Record<string, unknown> {
+  name?: string;
+  description?: string;
+  emoji?: string;
+  tools?: string;
+  model?: string;
+  confirmProjectAgents?: boolean;
+}
+
+export interface AgentDiscoveryResult {
+  agents: AgentConfig[];
+  projectAgentsDir: string | null;
+}
+
+export interface AgentIdentity {
+  name: string;
+  emoji?: string;
+}
+
+export function formatAgentDisplayName(agent: AgentIdentity): string {
+  const emoji = agent.emoji?.trim();
+  return emoji ? `${emoji} ${agent.name}` : agent.name;
+}
+
+function loadAgentsFromDir(
+  dir: string,
+  source: "user" | "project",
+): AgentConfig[] {
+  const agents: AgentConfig[] = [];
+
+  if (!fs.existsSync(dir)) {
+    return agents;
+  }
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return agents;
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+    const filePath = path.join(dir, entry.name);
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);
+
+    if (!frontmatter.name || !frontmatter.description) {
+      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;
+}
+
+function isDirectory(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+  let currentDir = cwd;
+  while (true) {
+    const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
+    if (isDirectory(candidate)) return candidate;
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+export function discoverAgents(
+  cwd: string,
+  scope: AgentScope,
+): AgentDiscoveryResult {
+  const userDir = path.join(getAgentDir(), "agents");
+  const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+  const userAgents =
+    scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+  const projectAgents =
+    scope === "user" || !projectAgentsDir
+      ? []
+      : loadAgentsFromDir(projectAgentsDir, "project");
+
+  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);
+  }
+
+  return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+
+export function shouldConfirmProjectAgent(
+  agent: AgentConfig,
+  invocationSetting?: boolean,
+): boolean {
+  return invocationSetting ?? agent.confirmProjectAgents ?? true;
+}

package/src/index.ts

@@ -0,0 +1,337 @@
+/**
+ * `/agent` — activate a configured Pi agent as a persistent mode in the
+ * current session.
+ *
+ * This package is a mode on the current agent session: it switches model,
+ * thinking level, and active tools, appends the agent prompt to the base
+ * prompt, and restores the pre-activation baseline on `/agent none` or
+ * `/agent off`. It does not spawn children and provides no delegated
+ * subagents.
+ */
+
+import type {
+  CustomEntry,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  discoverAgents,
+  formatAgentDisplayName,
+  shouldConfirmProjectAgent,
+  type AgentConfig,
+} from "./agent-discovery.ts";
+import { parseAgentModelSpec, type ThinkingLevel } from "./model-spec.ts";
+
+interface ModelReference {
+  provider: string;
+  id: string;
+}
+
+export interface AgentModelSpec {
+  model: string;
+  thinkingLevel?: ThinkingLevel;
+}
+
+export { parseAgentModelSpec };
+
+// Durable session state is namespaced so it cannot collide with other
+// packages. Legacy Aikado sessions wrote `active-agent-state`; restore reads
+// both types and prefers the newest recognized entry on the active branch so
+// sessions activated by either implementation resume correctly.
+const PI_AGENT_MODE_STATE_TYPE = "pi-agent-mode/state";
+const LEGACY_ACTIVE_AGENT_STATE_TYPE = "active-agent-state";
+const ACTIVE_AGENT_STATE_TYPES = [
+  LEGACY_ACTIVE_AGENT_STATE_TYPE,
+  PI_AGENT_MODE_STATE_TYPE,
+];
+
+interface AgentBaseline {
+  model?: ModelReference;
+  thinkingLevel: ThinkingLevel;
+  tools: string[];
+}
+
+interface ActiveAgent {
+  agent: AgentConfig;
+  baseline: AgentBaseline;
+}
+
+interface ActiveAgentState {
+  active: boolean;
+  name?: string;
+  baseline?: AgentBaseline;
+}
+
+export function registerAgentMode(pi: ExtensionAPI) {
+  let activeAgent: ActiveAgent | undefined;
+
+  function getBaseline(ctx: ExtensionContext): AgentBaseline {
+    return {
+      ...(ctx.model
+        ? { model: { provider: ctx.model.provider, id: ctx.model.id } }
+        : {}),
+      thinkingLevel: pi.getThinkingLevel(),
+      tools: pi.getActiveTools(),
+    };
+  }
+
+  function updateAgentStatus(ctx: ExtensionContext) {
+    if (!activeAgent) {
+      ctx.ui.setStatus("active-agent", undefined);
+      return;
+    }
+
+    ctx.ui.setStatus(
+      "active-agent",
+      ctx.ui.theme.bold(
+        ctx.ui.theme.fg("warning", formatAgentDisplayName(activeAgent.agent)),
+      ),
+    );
+  }
+
+  function persistActiveAgent() {
+    const state: ActiveAgentState = activeAgent
+      ? {
+          active: true,
+          name: activeAgent.agent.name,
+          baseline: activeAgent.baseline,
+        }
+      : { active: false };
+    pi.appendEntry(PI_AGENT_MODE_STATE_TYPE, state);
+  }
+
+  function findModel(modelSpec: string, ctx: ExtensionContext) {
+    const spec = modelSpec.trim();
+    const separator = spec.indexOf("/");
+    if (separator > 0 && separator < spec.length - 1) {
+      return ctx.modelRegistry.find(
+        spec.slice(0, separator),
+        spec.slice(separator + 1),
+      );
+    }
+
+    const matches = ctx.modelRegistry
+      .getAll()
+      .filter((model) => model.id === spec || model.name === spec);
+    return (
+      matches.find((model) => model.provider === ctx.model?.provider) ??
+      matches[0]
+    );
+  }
+
+  async function restoreModel(
+    model: ModelReference | undefined,
+    ctx: ExtensionContext,
+  ): Promise<boolean> {
+    if (!model) return true;
+    if (ctx.model?.provider === model.provider && ctx.model.id === model.id)
+      return true;
+
+    const resolved = ctx.modelRegistry.find(model.provider, model.id);
+    if (!resolved) {
+      ctx.ui.notify(
+        `Cannot restore model ${model.provider}/${model.id}: it is no longer available.`,
+        "warning",
+      );
+      return false;
+    }
+    if (await pi.setModel(resolved)) return true;
+
+    ctx.ui.notify(
+      `Cannot restore model ${model.provider}/${model.id}: authentication is unavailable.`,
+      "warning",
+    );
+    return false;
+  }
+
+  function applyAgentTools(
+    agent: AgentConfig,
+    baseline: AgentBaseline,
+    ctx: ExtensionContext,
+  ) {
+    const requested = agent.tools?.length ? agent.tools : baseline.tools;
+    const available = new Set(pi.getAllTools().map((tool) => tool.name));
+    const valid = requested.filter((tool) => available.has(tool));
+    const missing = requested.filter((tool) => !available.has(tool));
+
+    if (missing.length > 0) {
+      ctx.ui.notify(
+        `Agent ${formatAgentDisplayName(agent)}: unavailable tools ignored: ${missing.join(", ")}`,
+        "warning",
+      );
+    }
+    pi.setActiveTools(valid);
+  }
+
+  async function activateAgent(
+    agent: AgentConfig,
+    ctx: ExtensionContext,
+    baseline = activeAgent?.baseline ?? getBaseline(ctx),
+    persist = true,
+  ): Promise<boolean> {
+    baseline = {
+      ...baseline,
+      thinkingLevel: baseline.thinkingLevel ?? pi.getThinkingLevel(),
+    };
+    let thinkingLevel = baseline.thinkingLevel;
+    if (agent.model) {
+      const modelSpec = parseAgentModelSpec(agent.model);
+      const model = findModel(modelSpec.model, ctx);
+      if (!model) {
+        ctx.ui.notify(
+          `Agent ${formatAgentDisplayName(agent)}: configured model "${agent.model}" was not found.`,
+          "error",
+        );
+        return false;
+      }
+      if (!(await pi.setModel(model))) {
+        ctx.ui.notify(
+          `Agent ${formatAgentDisplayName(agent)}: authentication is unavailable for ${agent.model}.`,
+          "error",
+        );
+        return false;
+      }
+      thinkingLevel = modelSpec.thinkingLevel ?? baseline.thinkingLevel;
+    } else {
+      await restoreModel(baseline.model, ctx);
+    }
+
+    pi.setThinkingLevel(thinkingLevel);
+    applyAgentTools(agent, baseline, ctx);
+    activeAgent = { agent, baseline };
+    updateAgentStatus(ctx);
+    if (persist) persistActiveAgent();
+    return true;
+  }
+
+  async function clearActiveAgent(ctx: ExtensionContext) {
+    if (!activeAgent) {
+      ctx.ui.notify("No active agent.", "info");
+      return;
+    }
+
+    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",
+    );
+  }
+
+  async function confirmProjectAgent(
+    agent: AgentConfig,
+    ctx: ExtensionContext,
+  ): Promise<boolean> {
+    if (
+      agent.source !== "project" ||
+      !ctx.hasUI ||
+      !shouldConfirmProjectAgent(agent)
+    )
+      return true;
+    return ctx.ui.confirm(
+      "Activate project-local agent?",
+      `Agent: ${formatAgentDisplayName(agent)}\nSource: ${agent.filePath}\n\nProject agents are repo-controlled. Only continue for trusted projects.`,
+    );
+  }
+
+  pi.registerCommand("agent", {
+    description:
+      "Activate a named agent in this session; use /agent none to restore defaults",
+    handler: async (args, ctx) => {
+      const requested = args.trim();
+      if (requested === "none" || requested === "off") {
+        await clearActiveAgent(ctx);
+        return;
+      }
+
+      const agents = discoverAgents(ctx.cwd, "both").agents;
+      if (agents.length === 0) {
+        ctx.ui.notify("No agents found.", "warning");
+        return;
+      }
+
+      let agent: AgentConfig | undefined;
+      if (requested) {
+        agent = agents.find((candidate) => candidate.name === requested);
+        if (!agent) {
+          ctx.ui.notify(
+            `Unknown agent "${requested}". Available: ${agents.map((candidate) => formatAgentDisplayName(candidate)).join(", ")}`,
+            "warning",
+          );
+          return;
+        }
+      } else {
+        if (!ctx.hasUI) {
+          ctx.ui.notify(
+            `Usage: /agent <name|none>. Available: ${agents.map((agent) => formatAgentDisplayName(agent)).join(", ")}`,
+            "info",
+          );
+          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)];
+      }
+
+      if (!agent || !(await confirmProjectAgent(agent, ctx))) return;
+      if (await activateAgent(agent, ctx)) {
+        ctx.ui.notify(`Active agent: ${formatAgentDisplayName(agent)}`, "info");
+      }
+    },
+  });
+
+  pi.on("before_agent_start", (event) => {
+    if (!activeAgent) return;
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n## Active agent: ${formatAgentDisplayName(activeAgent.agent)}\nThe following agent definition is active for this session. Follow it in addition to Pi's base instructions and loaded project context.\n\n${activeAgent.agent.systemPrompt}`,
+    };
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    activeAgent = undefined;
+    const stateEntry = ctx.sessionManager
+      .getBranch()
+      .filter(
+        (entry): entry is CustomEntry<ActiveAgentState> =>
+          entry.type === "custom" &&
+          ACTIVE_AGENT_STATE_TYPES.includes(entry.customType),
+      )
+      .pop();
+    const state = stateEntry?.data;
+    if (!state?.active || !state.name) {
+      updateAgentStatus(ctx);
+      return;
+    }
+
+    const agent = discoverAgents(ctx.cwd, "both").agents.find(
+      (candidate) => candidate.name === state.name,
+    );
+    if (!agent) {
+      ctx.ui.notify(
+        `Active agent "${state.name}" is no longer available.`,
+        "warning",
+      );
+      updateAgentStatus(ctx);
+      return;
+    }
+
+    await activateAgent(agent, ctx, state.baseline ?? getBaseline(ctx), false);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    ctx.ui.setStatus("active-agent", undefined);
+  });
+}
+
+// Pi loads the package as an extension through this default factory.
+export default async function (pi: ExtensionAPI) {
+  registerAgentMode(pi);
+}

package/src/model-spec.ts

@@ -0,0 +1,41 @@
+/**
+ * Parsing of agent-configured model specifications.
+ *
+ * Agent frontmatter `model` values may carry a thinking suffix such as
+ * `:low`, `:high`, or `:max`. Unknown suffixes are left attached to the
+ * model id so lookup can decide whether the id as a whole exists.
+ */
+
+export type ThinkingLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+const THINKING_LEVELS = new Set<ThinkingLevel>([
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]);
+
+export interface AgentModelSpec {
+  model: string;
+  thinkingLevel?: ThinkingLevel;
+}
+
+export function parseAgentModelSpec(modelSpec: string): AgentModelSpec {
+  const spec = modelSpec.trim();
+  const separator = spec.lastIndexOf(":");
+  if (separator <= 0 || separator === spec.length - 1) return { model: spec };
+
+  const suffix = spec.slice(separator + 1) as ThinkingLevel;
+  if (!THINKING_LEVELS.has(suffix)) return { model: spec };
+  return { model: spec.slice(0, separator), thinkingLevel: suffix };
+}