@pi-archimedes/subagent 0.8.0 → 0.9.0

package/src/agents.ts

@@ -10,12 +10,14 @@ import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 export interface AgentConfig {
   name: string;
   description: string;
+  tools?: string[];
   model?: string;
   thinking?: string;
-  tools?: string[];
   systemPrompt: string;
   source: "user" | "project";
   filePath: string;
+  // Extra fields preserved from frontmatter but not editable in TUI
+  extraFields?: Record<string, unknown>;
 }
 
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
@@ -46,9 +48,26 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 
     if (!frontmatter.name || !frontmatter.description) continue;
 
-    const tools = typeof frontmatter.tools === "string"
-      ? frontmatter.tools.split(",").map((t: string) => t.trim()).filter(Boolean)
-      : undefined;
+    // Handle tools specially — preserve non-string values in extraFields
+    let parsedTools: string[] | undefined;
+    if (typeof frontmatter.tools === "string") {
+      parsedTools = frontmatter.tools.split(",").map((t: string) => t.trim()).filter(Boolean);
+    }
+
+    const knownKeys = new Set(["name", "description", "model", "thinking"]);
+    const extraFields: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(frontmatter)) {
+      if (key === "tools") continue; // tools is handled separately above/below
+      if (!knownKeys.has(key) && value != null && typeof value !== "object") {
+        extraFields[key] = String(value);
+      } else if (!knownKeys.has(key) && value != null) {
+        extraFields[key] = value;
+      }
+    }
+    // If tools was non-string, store it in extraFields for round-trip preservation
+    if (frontmatter.tools !== undefined && !parsedTools && "tools" in frontmatter) {
+      extraFields.tools = frontmatter.tools;
+    }
 
     const config: AgentConfig = {
       name: frontmatter.name as string,
@@ -59,7 +78,8 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
     };
     if (frontmatter.model) config.model = frontmatter.model as string;
     if (frontmatter.thinking) config.thinking = frontmatter.thinking as string;
-    if (tools && tools.length > 0) config.tools = tools;
+    if (parsedTools && parsedTools.length > 0) config.tools = parsedTools;
+    if (Object.keys(extraFields).length > 0) config.extraFields = extraFields;
 
     agents.push(config);
   }
@@ -67,19 +87,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
   return agents;
 }
 
-function isDirectory(p: string): boolean {
-  try {
-    return fs.statSync(p).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 function findNearestProjectAgentsDir(cwd: string): string | null {
+  // Walk up looking for a git repo, even if .pi/agents doesn't exist yet
   let currentDir = cwd;
   while (true) {
-    const candidate = path.join(currentDir, ".pi", "agents");
-    if (isDirectory(candidate)) return candidate;
+    const gitPath = path.join(currentDir, ".git");
+    if (fs.existsSync(gitPath)) {
+      return path.join(currentDir, ".pi", "agents");
+    }
 
     const parentDir = path.dirname(currentDir);
     if (parentDir === currentDir) return null;
@@ -87,6 +102,16 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
   }
 }
 
+/**
+ * Result of discovering agents — separated by source with directory paths.
+ */
+export interface AgentsDiscoveryResult {
+  user: AgentConfig[];
+  project: AgentConfig[];
+  userDir: string;        // e.g., ~/.pi/agent/agents
+  projectDir: string | null;  // e.g., .pi/agents or null if not found
+}
+
 /**
  * Discover all available agents from user and/or project directories.
  */
@@ -105,6 +130,24 @@ export function discoverAgents(cwd: string): AgentConfig[] {
   return Array.from(agentMap.values());
 }
 
+/**
+ * Discover agents and return them separated by source with directory paths.
+ */
+export function discoverAgentsAll(cwd: string): AgentsDiscoveryResult {
+  const userDir = path.join(getAgentDir(), "agents");
+  const projectDir = findNearestProjectAgentsDir(cwd);
+
+  const userAgents = loadAgentsFromDir(userDir, "user");
+  const projectAgents = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
+
+  return {
+    user: userAgents,
+    project: projectAgents,
+    userDir,
+    projectDir,
+  };
+}
+
 /**
  * Look up an agent config by name.
  */

package/src/frontmatter-io.ts

@@ -0,0 +1,103 @@
+/**
+ * Frontmatter serialization and validation for agent config files.
+ */
+
+import type { AgentConfig } from "./agents.js";
+
+/**
+ * Regex for valid agentspec names: lowercase alphanumeric + hyphens, 3-50 chars.
+ * Alphanumeric start/end. Also allows single-char names.
+ */
+export const AGENT_NAME_REGEX = /^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/;
+
+const SINGLE_CHAR_NAME_REGEX = /^[a-z0-9]$/;
+
+/**
+ * Validate an agent name against agentspec format rules.
+ * Returns an error message string if invalid, null if valid.
+ */
+export function validateAgentName(name: string): string | null {
+  if (!name || name.length === 0) {
+    return "Name is required";
+  }
+  if (SINGLE_CHAR_NAME_REGEX.test(name)) {
+    return null;
+  }
+  if (AGENT_NAME_REGEX.test(name)) {
+    return null;
+  }
+  return "Name must be 3-50 lowercase alphanumeric characters or hyphens, starting and ending with alphanumeric";
+}
+
+function needsYamlQuoting(value: string): boolean {
+  if (value === "") return true;
+  // Special YAML characters at start
+  if (/^["'#\{\[\|>&!*%?@`-]/.test(value)) return true;
+  // Contains colon (could be mistaken for mapping)
+  if (value.includes(":")) return true;
+  // Contains # (inline comment marker) anywhere
+  if (value.includes("#")) return true;
+  // Contains newline
+  if (value.includes("\n")) return true;
+  // Leading/trailing whitespace
+  if (value !== value.trim()) return true;
+  // YAML booleans/nulls
+  if (/^(true|false|yes|no|on|off|null|True|False|Yes|No|On|Off|NULL|Null)$/i.test(value)) return true;
+  return false;
+}
+
+function quoteYamlValue(value: string): string {
+  if (!needsYamlQuoting(value)) return value;
+  // Escape backslashes and double quotes, wrap in double quotes
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
+
+/**
+ * Serialize an AgentConfig back to a valid .md file with frontmatter.
+ * Produces output that parseFrontmatter can re-parse faithfully.
+ */
+export function serializeAgent(config: AgentConfig): string {
+  const lines: string[] = ["---"];
+
+  // Required fields
+  lines.push(`name: ${quoteYamlValue(config.name)}`);
+  lines.push(`description: ${quoteYamlValue(config.description)}`);
+
+  // Optional known fields
+  if (config.tools && config.tools.length > 0) {
+    lines.push(`tools: ${quoteYamlValue(config.tools.join(", "))}`);
+  }
+  if (config.model) {
+    lines.push(`model: ${quoteYamlValue(config.model)}`);
+  }
+  if (config.thinking) {
+    lines.push(`thinking: ${quoteYamlValue(config.thinking)}`);
+  }
+
+  // Extra fields (sorted alphabetically)
+  if (config.extraFields) {
+    for (const key of Object.keys(config.extraFields).sort()) {
+      const value = config.extraFields[key]!;
+      if (typeof value === "string") {
+        lines.push(`${key}: ${quoteYamlValue(value)}`);
+      } else if (Array.isArray(value)) {
+        // Serialize array as YAML block sequence
+        lines.push(`${key}:`);
+        for (const item of value) {
+          lines.push(`  - ${quoteYamlValue(String(item))}`);
+        }
+      } else {
+        // Fallback: JSON stringify for objects
+        lines.push(`${key}: ${JSON.stringify(value)}`);
+      }
+    }
+  }
+
+  lines.push("---");
+  lines.push("");
+  lines.push(config.systemPrompt);
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/index.ts

@@ -1,9 +1,10 @@
-import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { executeSubagent, executeParallel } from "./execute.js";
 import { renderSubagentResult } from "./render.js";
-import { discoverAgents, findAgent } from "./agents.js";
+import { discoverAgents, discoverAgentsAll, findAgent } from "./agents.js";
+import { createAgentManager } from "./agent-manager.js";
 import type {
   SubagentDetails,
   SubagentProgress,
@@ -96,7 +97,9 @@ export function registerSubagent(pi: ExtensionAPI): void {
             agent: t.agent ?? undefined,
             agentConfig: t.agent ? findAgent(agents, t.agent) : undefined,
             task: t.task,
-            model: t.model ?? undefined,
+            // Fall back to the parent's currently-selected model when the caller
+            // (and the agent frontmatter) didn't specify one.
+            model: t.model ?? ctx.model?.id,
             cwd: t.cwd ?? undefined,
           })),
           signal: signal ?? undefined,
@@ -141,7 +144,9 @@ export function registerSubagent(pi: ExtensionAPI): void {
           agent: params.agent ?? undefined,
           agentConfig,
           task: params.task,
-          model: params.model ?? undefined,
+          // Fall back to the parent's currently-selected model when the caller
+          // (and the agent frontmatter) didn't specify one.
+          model: params.model ?? ctx.model?.id,
           cwd: params.cwd ?? undefined,
           signal: signal ?? undefined,
           onUpdate: (progress: SubagentProgress) => {
@@ -255,6 +260,35 @@ function formatResultsSummary(results: SubagentResult[]): string {
   return lines.join("\n");
 }
 
+// ── Command registration ────────────────────────────────────────────────────
+
+export function registerAgentsCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("agents", {
+    description: "Open the Agents Manager",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      const { user, project, userDir, projectDir } = discoverAgentsAll(ctx.cwd);
+
+      const availableModels = ctx.modelRegistry.getAvailable().map((m) => ({
+        id: m.id,
+        provider: m.provider,
+        fullId: `${m.provider}/${m.id}`,
+      }));
+
+      const availableTools = pi.getAllTools().map((t) => ({
+        name: t.name,
+        description: t.description ?? "",
+      }));
+
+      await ctx.ui.custom<void>(
+        (tui: TUI, theme: Theme, _keybindings, done: () => void) => {
+          return createAgentManager(user, project, userDir, projectDir, tui, theme, done, availableModels, availableTools);
+        },
+        { overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } },
+      );
+    },
+  });
+}
+
 // ── Default export ──────────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI): void {

package/src/spawn.ts

@@ -101,7 +101,8 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
       args.push("--tools", agent.tools.join(","));
     }
   } else if (options.model) {
-    // Fallback: use model from tool call params (legacy)
+    // Fallback: tool-call model (which itself falls back to the parent's
+    // currently-selected model via ctx.model?.id at the call site).
     args.push("--model", options.model);
   }