@jaybeeuu/agent-cortex 1.37.1 → 1.38.1

package/extensions/agent-modes/discover.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import {
+  type AgentDef,
+  type TokenMap,
+  discoverAgents,
+  loadTokenMap,
+} from "./discover.ts";
+
+// Real token-map.json at the package root — the canonical tool/path map the
+// extension ships with. Used to verify translation against the source of truth.
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const REAL_TOKEN_MAP = loadTokenMap(join(REPO_ROOT, "agents"));
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+interface Fixture {
+  dir: string;
+  agentsDir: string;
+  cleanup: () => void;
+}
+
+function makeFixture(): Fixture {
+  const dir = mkdtempSync(join(tmpdir(), "agent-modes-"));
+  return {
+    dir,
+    agentsDir: join(dir, "agents"),
+    cleanup: () => rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+function writeFixture(fx: Fixture, relPath: string, content: string): void {
+  const p = join(fx.dir, relPath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+}
+
+function writeComposableAgent(
+  fx: Fixture,
+  name: string,
+  opts: {
+    body?: string;
+    frontmatter?: Record<string, unknown>;
+    sections?: Record<string, string>;
+  } = {},
+): void {
+  const base = `agents/${name}`;
+  writeFixture(fx, `${base}/agent.md`, opts.body ?? `# ${name}\nBody of ${name}.`);
+  writeFixture(
+    fx,
+    `${base}/pi/frontmatter.json`,
+    JSON.stringify(
+      opts.frontmatter ?? {
+        name: `agent-cortex:${name}`,
+        description: `Description of ${name}`,
+        tools: ["bash", "view", "task"],
+      },
+    ),
+  );
+  for (const [section, body] of Object.entries(opts.sections ?? {})) {
+    writeFixture(fx, `${base}/pi/${section}.md`, body);
+  }
+}
+
+function writeFlatAgent(fx: Fixture, name: string, body: string): void {
+  writeFixture(fx, `agents/${name}.agent.md`, body);
+}
+
+const fixtures: Fixture[] = [];
+function track(fx: Fixture): Fixture {
+  fixtures.push(fx);
+  return fx;
+}
+
+after(() => {
+  for (const fx of fixtures) fx.cleanup();
+});
+
+const FLAT_FRONTMATTER = (name: string, tools: string) =>
+  `---\ndescription: "Flat description of ${name}"\nname: "agent-cortex:${name}"\ntools: ${tools}\n---\n\nFlat body of ${name}.`;
+
+// ─── Tokens ───────────────────────────────────────────────────────────────────
+
+const TOKEN_PROSE =
+  "Run with {{TOOL:bash}}.\n" +
+  "Ask the user with {{TOOL:ask_user}}.\n" +
+  "Read the plan skill at {{PATH:skills/workflow/plan/SKILL.md}}.\n" +
+  "Agents live in {{PATH:agents_dir}}.";
+
+// ─── Composable discovery ────────────────────────────────────────────────────
+
+describe("discoverAgents (composable source format)", () => {
+  it("discovers agents from <name>/agent.md + <name>/pi/frontmatter.json", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "ralph", {
+      body: "# ralph\nUse {{TOOL:task}} to spawn subagents.\n\n{{SECTION:polling}}",
+      frontmatter: {
+        name: "agent-cortex:ralph",
+        description: "Runs beads end-to-end",
+        tools: ["bash", "view", "rg", "glob", "task", "read_agent"],
+      },
+      sections: {
+        polling: "## PI polling\nPoll with task + read_agent.",
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    const ralph = agents[0];
+    assert.equal(ralph.id, "ralph");
+    assert.equal(ralph.name, "agent-cortex:ralph");
+    assert.equal(ralph.description, "Runs beads end-to-end");
+    // Canonical tool names translated to PI names via token-map (glob→find, rg→grep, view→read).
+    assert.deepEqual(ralph.tools, ["bash", "find", "grep", "read", "read_agent", "task"]);
+    // SECTION token resolved from pi/<section>.md; TOOL token substituted.
+    assert.match(ralph.prompt, /Use task to spawn subagents\./);
+    assert.match(ralph.prompt, /Poll with task \+ read_agent\./);
+    assert.doesNotMatch(ralph.prompt, /\{\{/);
+  });
+
+  it("substitutes TOOL / PATH tokens against token-map.json using the real plugin root", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "plan", {
+      body: TOKEN_PROSE,
+      frontmatter: { name: "agent-cortex:plan", description: "Planner", tools: [] },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+    assert.equal(agents.length, 1);
+    const plan = agents[0];
+
+    // {{TOOL:bash}} → bash.
+    assert.match(plan.prompt, /Run with bash\./);
+    // {{TOOL:ask_user}} → null for pi — token dropped (dangling prose is the author's
+    // responsibility per token-map.README), not left as literal token syntax.
+    assert.doesNotMatch(plan.prompt, /\{\{TOOL:ask_user\}\}/);
+    // Relative {{PATH:...}} resolves against the actual package root (dir of agents/).
+    assert.match(plan.prompt, new RegExp(`Read the plan skill at ${escapeRegExp(fx.dir)}/skills/workflow/plan/SKILL\\.md\\.`));
+    // Named {{PATH:agents_dir}} resolves to <root>/agents.
+    assert.match(plan.prompt, new RegExp(`Agents live in ${escapeRegExp(fx.agentsDir)}\\.`));
+    assert.doesNotMatch(plan.prompt, /\{\{/);
+  });
+
+  it("drops null-mapped tools (ask_user, skill) from the PI tool set", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "plan", {
+      frontmatter: {
+        name: "agent-cortex:plan",
+        description: "Planner",
+        tools: ["bash", "ask_user", "skill", "web_fetch"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+    assert.equal(agents.length, 1);
+    // ask_user → null (omitted), skill → null (omitted), web_fetch → fetch_content.
+    assert.deepEqual(agents[0].tools, ["bash", "fetch_content"]);
+  });
+
+  it("uses the built-in fallback map when token-map.json is unavailable", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "legacy", {
+      frontmatter: {
+        name: "agent-cortex:legacy",
+        description: "No token map",
+        tools: ["view", "glob", "ask_user"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir);
+    assert.equal(agents.length, 1);
+    // Copilot→PI fallback: view→read, glob→find+ls; unmapped ask_user passes through.
+    assert.deepEqual(agents[0].tools, ["ask_user", "find", "ls", "read"]);
+  });
+
+  it("returns an empty list for a missing agents directory", () => {
+    const fx = track(makeFixture());
+    assert.deepEqual(discoverAgents(join(fx.dir, "does-not-exist"), REAL_TOKEN_MAP), []);
+  });
+
+  it("returns an empty list when no agents are present", () => {
+    const fx = track(makeFixture());
+    mkdirSync(fx.agentsDir, { recursive: true });
+    assert.deepEqual(discoverAgents(fx.agentsDir, REAL_TOKEN_MAP), []);
+  });
+});
+
+// ─── Flat fallback ────────────────────────────────────────────────────────────
+
+describe("discoverAgents (flat fallback)", () => {
+  it("prefers a composable directory over its flat file for the same agent", () => {
+    const fx = track(makeFixture());
+    writeComposableAgent(fx, "ralph", { body: "Composable body." });
+    writeFlatAgent(fx, "ralph", FLAT_FRONTMATTER("ralph", '["bash", "view"]'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    assert.equal(agents[0].id, "ralph");
+    assert.match(agents[0].prompt, /Composable body\./);
+    assert.doesNotMatch(agents[0].prompt, /Flat body/);
+  });
+
+  it("falls back to flat *.agent.md for agents without a composable directory", () => {
+    const fx = track(makeFixture());
+    writeFlatAgent(fx, "strategy", FLAT_FRONTMATTER("strategy", '["bash", "view", "web_fetch"]'));
+
+    const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
+
+    assert.equal(agents.length, 1);
+    const strategy = agents[0];
+    assert.equal(strategy.id, "strategy");
+    assert.equal(strategy.name, "agent-cortex:strategy");
+    assert.equal(strategy.description, "Flat description of strategy");
+    // view→read, web_fetch→fetch_content via token-map.
+    assert.deepEqual(strategy.tools, ["bash", "fetch_content", "read"]);
+    assert.match(strategy.prompt, /Flat body of strategy\./);
+  });
+});
+
+// ─── loadTokenMap ────────────────────────────────────────────────────────────
+
+describe("loadTokenMap", () => {
+  it("reads the real token-map.json at the package root", () => {
+    assert.ok(REAL_TOKEN_MAP);
+    assert.equal(typeof REAL_TOKEN_MAP?.tools?.bash?.pi, "string");
+    // ask_user has no PI equivalent per the contract — must stay null.
+    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, null);
+    assert.ok(REAL_TOKEN_MAP?.paths?.agents_dir);
+  });
+});
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/extensions/agent-modes/discover.ts

@@ -0,0 +1,458 @@
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Agent discovery for the agent-modes extension.
+ *
+ * Agents are read from the composable source format (`agents/<name>/agent.md` +
+ * `agents/<name>/pi/frontmatter.json`) — the canonical layout defined in
+ * agents/README.md. The PI system prompt is composed per the token-map.json
+ * contract:
+ *
+ *   1. `{{SECTION:name}}` is resolved from the agent's `pi/<name>.md` section file.
+ *   2. `{{TOOL:key}}` and `{{PATH:key}}` are substituted against the pi column of
+ *      token-map.json, with the plugin root resolved from the actual extension
+ *      location (installers must compute it from the real resolution, per the
+ *      token-map notes — a hardcoded `~/.pi/...` literal would break checkout
+ *      and symlinked installs).
+ *
+ * Flat `agents/*.agent.md` files are parsed as a fallback for agents that have
+ * no composable directory (they are generated output for Copilot, so they may
+ * exist for any agent). A composable directory always wins over its flat
+ * counterpart.
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface AgentDef {
+  /** Lowercase id derived from the directory/file name (e.g. "ralph", "ralph-plan") */
+  id: string;
+  /** Display name from frontmatter or prettified id */
+  name: string;
+  /** Description from frontmatter */
+  description: string;
+  /** Colour for the status indicator */
+  color: ThemeColor;
+  /** PI tool names to enable (empty = all tools) */
+  tools: string[];
+  /** Full agent body (the system prompt to inject) */
+  prompt: string;
+}
+
+export type HarnessId = "copilot" | "claude" | "pi";
+
+export interface PathSpec {
+  base: string;
+  relative: string;
+}
+
+/** Shape of token-map.json (see the file at the package root). */
+export interface TokenMap {
+  tools: Record<string, Record<HarnessId, string | null>>;
+  paths: Record<string, Record<HarnessId, string | PathSpec>>;
+}
+
+const PI: HarnessId = "pi";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Mapping from agent id → colour for the status indicator. */
+const AGENT_COLORS: Record<string, ThemeColor> = {
+  ralph: "accent",
+  "ralph-plan": "warning",
+  strategy: "accent",
+};
+
+/** Modes with no tool restriction get the full default set. */
+const DEFAULT_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+/**
+ * Copilot CLI tool names → PI built-in tool names. Fallback translation used
+ * when token-map.json is unavailable; token-map.json is the source of truth
+ * when present.
+ */
+const COPILOT_TO_PI: Record<string, string[]> = {
+  bash: ["bash"],
+  view: ["read"],
+  read: ["read"],
+  edit: ["edit"],
+  create: ["write"],
+  write: ["write"],
+  grep: ["grep"],
+  rg: ["grep", "find"],
+  glob: ["find", "ls"],
+  find: ["find"],
+  ls: ["ls"],
+};
+
+// ─── Read helpers ────────────────────────────────────────────────────────────
+
+function isFile(p: string): boolean {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Load token-map.json from the package root (sibling of the agents dir). */
+export function loadTokenMap(agentsDir: string): TokenMap | null {
+  try {
+    const raw = readFileSync(join(agentsDir, "..", "token-map.json"), "utf-8");
+    const parsed = JSON.parse(raw) as Partial<TokenMap>;
+    return parsed.tools && parsed.paths ? (parsed as TokenMap) : null;
+  } catch {
+    return null;
+  }
+}
+
+function prettifyId(id: string): string {
+  return id
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+// ─── Tool translation ────────────────────────────────────────────────────────
+
+/**
+ * Translate a frontmatter tool list into PI tool names.
+ *
+ * With token-map.json: canonical keys are translated via the pi column; a null
+ * mapping means PI has no equivalent (ask_user, skill) and the entry is omitted;
+ * a name that is not a canonical key passes through untouched (it may be a
+ * native PI tool such as `fetch_content`). Without the map, the built-in
+ * COPILOT_TO_PI fallback applies and unknown names pass through.
+ */
+function translateTools(raw: unknown, tokenMap: TokenMap | null): string[] {
+  if (!Array.isArray(raw)) return [];
+
+  const out = new Set<string>();
+  for (const t of raw) {
+    if (typeof t !== "string" || t === "") continue;
+
+    if (tokenMap) {
+      const mapping = tokenMap.tools[t];
+      if (mapping === undefined) {
+        out.add(t); // not a canonical key — pass through (may be a native PI tool)
+      } else if (mapping[PI] === null) {
+        console.warn(`[agent-modes] Tool "${t}" has no PI equivalent — omitted from the tool set`);
+      } else {
+        out.add(mapping[PI] as string);
+      }
+    } else {
+      const fallback = COPILOT_TO_PI[t];
+      if (fallback) {
+        for (const f of fallback) out.add(f);
+      } else {
+        out.add(t);
+      }
+    }
+  }
+  return [...out].sort();
+}
+
+// ─── PATH token resolution ───────────────────────────────────────────────────
+
+/**
+ * Resolve a `{{PATH:...}}` argument for the pi harness.
+ *
+ * A named key resolves through token-map.json's `paths` table; the `plugin_root`
+ * base is always overridden with the actual package root (the directory
+ * containing `agents/`) because the map's literal only describes the default npm
+ * install layout. Anything that is not a named key is treated as a relative path
+ * under the package root.
+ */
+function resolvePathToken(arg: string, tokenMap: TokenMap | null, pluginRoot: string): string {
+  const entry = tokenMap?.paths?.[arg];
+  if (!entry) return join(pluginRoot, arg);
+
+  const spec = entry[PI];
+  if (typeof spec === "string") {
+    return arg === "plugin_root" ? pluginRoot : spec; // ${ENV} literals left verbatim
+  }
+  if (spec && typeof spec === "object" && typeof spec.base === "string" && typeof spec.relative === "string") {
+    const base = resolvePathToken(spec.base, tokenMap, pluginRoot);
+    return join(base, spec.relative);
+  }
+  console.warn(`[agent-modes] Unresolvable {{PATH:${arg}}} — token dropped`);
+  return "";
+}
+
+// ─── Prompt composition ──────────────────────────────────────────────────────
+
+/**
+ * Compose the PI system prompt for a composable agent directory.
+ *
+ * Substitution order follows the token-map contract: SECTION, then TOOL, then
+ * PATH. Section files resolve from `<agentDir>/pi/<name>.md`; missing sections
+ * and null-mapped tools drop the token with a warning so the prompt never ships
+ * literal token syntax.
+ */
+function composePiPrompt(
+  agentDir: string,
+  id: string,
+  tokenMap: TokenMap | null,
+  pluginRoot: string,
+): string {
+  let body = readFileSync(join(agentDir, "agent.md"), "utf-8").trim();
+
+  // 1. {{SECTION:name}} → content of pi/<name>.md
+  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, name: string) => {
+    const sectionPath = join(agentDir, "pi", `${name}.md`);
+    if (!isFile(sectionPath)) {
+      console.warn(`[agent-modes] Missing section "${name}" for agent "${id}" — token dropped`);
+      return "";
+    }
+    return readFileSync(sectionPath, "utf-8").trim();
+  });
+
+  // 2. {{TOOL:key}} → tools[key].pi (null mapping drops the token)
+  body = body.replace(/\{\{TOOL:([^}]+)\}\}/g, (_token, key: string) => {
+    const mapping = tokenMap?.tools?.[key];
+    if (mapping === undefined) {
+      console.warn(`[agent-modes] Unknown tool token {{TOOL:${key}}} in agent "${id}" — token dropped`);
+      return "";
+    }
+    if (mapping[PI] === null) {
+      console.warn(`[agent-modes] Tool token {{TOOL:${key}}} has no PI equivalent in agent "${id}" — token dropped`);
+      return "";
+    }
+    return mapping[PI] as string;
+  });
+
+  // 3. {{PATH:key-or-relative}} → resolved against the actual plugin root
+  body = body.replace(/\{\{PATH:([^}]+)\}\}/g, (_token, arg: string) => resolvePathToken(arg, tokenMap, pluginRoot));
+
+  return body;
+}
+
+// ─── Composable directory reading ────────────────────────────────────────────
+
+interface Frontmatter {
+  name?: string;
+  description?: string;
+  tools?: string[];
+}
+
+interface ComposableFrontmatter extends Frontmatter {
+  name: string;
+  description: string;
+  tools: string[];
+}
+
+function parseFrontmatterJson(raw: string, id: string): ComposableFrontmatter {
+  let fm: Record<string, unknown>;
+  try {
+    fm = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err) {
+    console.warn(`[agent-modes] Invalid frontmatter.json for agent "${id}": ${err}`);
+    return { name: prettifyId(id), description: "", tools: [] };
+  }
+
+  return {
+    name: typeof fm.name === "string" && fm.name !== "" ? fm.name : prettifyId(id),
+    description: typeof fm.description === "string" ? fm.description : "",
+    tools: Array.isArray(fm.tools) ? (fm.tools.filter((t): t is string => typeof t === "string") as string[]) : [],
+  };
+}
+
+function readComposableAgent(
+  agentDir: string,
+  id: string,
+  tokenMap: TokenMap | null,
+  pluginRoot: string,
+): AgentDef | null {
+  try {
+    const fm = parseFrontmatterJson(readFileSync(join(agentDir, "pi", "frontmatter.json"), "utf-8"), id);
+    const tools = translateTools(fm.tools, tokenMap);
+    return {
+      id,
+      name: fm.name,
+      description: fm.description,
+      color: AGENT_COLORS[id] ?? "accent",
+      tools: tools.length > 0 ? tools : [...DEFAULT_TOOLS],
+      prompt: composePiPrompt(agentDir, id, tokenMap, pluginRoot),
+    };
+  } catch (err) {
+    console.warn(`[agent-modes] Failed to read composable agent "${id}": ${err}`);
+    return null;
+  }
+}
+
+// ─── Flat file parsing (transitional fallback) ───────────────────────────────
+
+interface FlatParsed {
+  name?: string;
+  description?: string;
+  tools?: string[];
+  prompt: string;
+}
+
+function parseFlatFrontmatter(raw: string): FlatParsed {
+  const lines = raw.split(/\r?\n/);
+  if (lines[0] !== "---") return { prompt: raw };
+
+  // Find closing ---
+  let sep = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      sep = i;
+      break;
+    }
+  }
+  if (sep === -1) return { prompt: raw };
+
+  const yamlLines = lines.slice(1, sep);
+  const prompt = lines.slice(sep + 1).join("\n").trim();
+
+  let name: string | undefined;
+  let description: string | undefined;
+  let tools: string[] | undefined;
+
+  for (const line of yamlLines) {
+    const trimmed = line.trim();
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) continue;
+
+    const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
+    const val = trimmed.slice(colonIdx + 1).trim();
+
+    if (key === "name") {
+      name = val.replace(/^["']|["']$/g, "");
+    } else if (key === "description") {
+      description = val.replace(/^["']|["']$/g, "");
+    }
+  }
+
+  // Parse tools from the tools frontmatter.
+  // Supports two formats:
+  //   tools: ["bash", "view"]        (JSON array, single line)
+  //   tools:                         (YAML list, subsequent lines)
+  //     - bash
+  //     - view
+  let inToolsBlock = false;
+  for (const line of yamlLines) {
+    const trimmed = line.trim();
+
+    // Check for inline JSON array: tools: ["foo", "bar"]
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx !== -1) {
+      const key = trimmed.slice(0, colonIdx).trim().toLowerCase();
+      const val = trimmed.slice(colonIdx + 1).trim();
+      if (key === "tools") {
+        if (val.startsWith("[")) {
+          try {
+            tools = JSON.parse(val);
+          } catch {
+            // Malformed JSON — fall through
+          }
+          continue;
+        }
+        if (val === "[]" || val === "") {
+          tools = [];
+          continue;
+        }
+      }
+    }
+
+    // YAML block format: "tools:" on its own line, items on subsequent lines
+    if (trimmed === "tools:") {
+      inToolsBlock = true;
+      if (!tools) tools = [];
+      continue;
+    }
+    if (inToolsBlock) {
+      if (line.startsWith("  ") || line.startsWith("\t") || trimmed.startsWith("- ")) {
+        const item = trimmed.replace(/^- /, "").trim().replace(/^["']|["']$/g, "");
+        if (item) {
+          if (!tools) tools = [];
+          tools.push(item);
+        }
+      } else if (trimmed !== "") {
+        inToolsBlock = false;
+      }
+    }
+  }
+
+  return { name, description, tools, prompt };
+}
+
+function readFlatAgent(filePath: string, tokenMap: TokenMap | null): AgentDef | null {
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    console.warn(`[agent-modes] Failed to read ${basename(filePath)}: ${err}`);
+    return null;
+  }
+
+  const parsed = parseFlatFrontmatter(raw);
+  const id = basename(filePath).replace(/\.agent\.md$/i, "").toLowerCase();
+  const name = parsed.name || prettifyId(id);
+  const tools = translateTools(parsed.tools, tokenMap);
+
+  return {
+    id,
+    name,
+    description: parsed.description || "",
+    color: AGENT_COLORS[id] ?? "accent",
+    tools: tools.length > 0 ? tools : [...DEFAULT_TOOLS],
+    prompt: parsed.prompt || `You are ${name}. ${parsed.description || ""}`,
+  };
+}
+
+// ─── Discovery ───────────────────────────────────────────────────────────────
+
+/**
+ * Discover agents from the agents directory.
+ *
+ * Composable directories (`<name>/agent.md` + `<name>/pi/frontmatter.json`) are
+ * the primary source. Flat `*.agent.md` files (generated output for Copilot) are
+ * read only when no composable directory exists for that agent id. When
+ * `tokenMap` is omitted, token-map.json is loaded from the package root;
+ * missing/unreadable maps fall back to the built-in copilot→pi translation.
+ */
+export function discoverAgents(agentsDir: string, tokenMap: TokenMap | null = null): AgentDef[] {
+  if (!existsSync(agentsDir) || !statSync(agentsDir).isDirectory()) {
+    console.warn(`[agent-modes] Agents directory not found: ${agentsDir}`);
+    return [];
+  }
+
+  const map = tokenMap ?? loadTokenMap(agentsDir);
+  const pluginRoot = join(agentsDir, "..");
+
+  const entries = readdirSync(agentsDir, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+
+  const agents: AgentDef[] = [];
+  const composableIds = new Set<string>();
+
+  // 1. Composable directory format
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = join(agentsDir, entry.name);
+    if (!isFile(join(dir, "agent.md")) || !isFile(join(dir, "pi", "frontmatter.json"))) continue;
+    const id = entry.name.toLowerCase();
+    const def = readComposableAgent(dir, id, map, pluginRoot);
+    if (def) {
+      composableIds.add(id);
+      agents.push(def);
+    }
+  }
+
+  // 2. Flat fallback for agents without a composable directory
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".agent.md")) continue;
+    const id = entry.name.replace(/\.agent\.md$/i, "").toLowerCase();
+    if (composableIds.has(id)) continue; // composable wins
+    const def = readFlatAgent(join(agentsDir, entry.name), map);
+    if (def) agents.push(def);
+  }
+
+  return agents;
+}
+
+export { DEFAULT_TOOLS };