pi-open-agents 0.1.0

package/src/config/schema.ts

@@ -0,0 +1,313 @@
+/**
+ * Agent definition schema: validation, normalization, and default application.
+ *
+ * This is the brain of the parsing pipeline. Raw frontmatter goes in,
+ * a fully validated AgentDefinition comes out.
+ *
+ * Handles:
+ * - Required field validation (name)
+ * - Enum validation (mode, thinking, systemPrompt)
+ * - Type coercion (numbers, booleans, arrays)
+ * - OpenCode aliases (prompt → body, tools map → permission, maxSteps → steps)
+ * - Default application (with settings fallbacks for thinking)
+ */
+
+import type {
+  AgentDefinition,
+  AgentMode,
+  AgentSource,
+  PermissionAction,
+  PermissionConfig,
+  SystemPromptMode,
+  ThinkingLevel,
+} from "../types.ts";
+import {
+  AGENT_MODES,
+  PERMISSION_ACTIONS,
+  SYSTEM_PROMPT_MODES,
+  THINKING_LEVELS,
+} from "../types.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+export interface SchemaDefaults {
+  /** Default thinking level, typically from settings.json defaultThinkingLevel */
+  thinking: ThinkingLevel;
+}
+
+export const SCHEMA_DEFAULTS: SchemaDefaults = {
+  thinking: "off",
+};
+
+// ─── Parse Error ─────────────────────────────────────────────────────────────
+
+export class AgentParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentParseError";
+  }
+}
+
+// ─── Main Entry Point ────────────────────────────────────────────────────────
+
+/**
+ * Parse raw .md file content into a validated AgentDefinition.
+ *
+ * @param content     Raw file content (with frontmatter)
+ * @param filePath    Absolute path to the file
+ * @param source      Discovery origin (global/project)
+ * @param defaults    Schema defaults (thinking fallback)
+ * @param nameHint    Optional name derived from file path (used if no frontmatter name)
+ */
+export function parseAgentDefinition(
+  content: string,
+  filePath: string,
+  source: AgentSource,
+  defaults: SchemaDefaults = SCHEMA_DEFAULTS,
+  nameHint?: string,
+): AgentDefinition {
+  const { data, body } = parseFrontmatter(content);
+
+  // ── Name (required) ──
+  const name = parseString(data.name) ?? nameHint;
+  if (!name) {
+    throw new AgentParseError("missing required field: name");
+  }
+
+  // ── Prompt: body wins over frontmatter "prompt" field ──
+  // OpenCode uses frontmatter "prompt" field; pi uses the body.
+  // If both exist, body takes precedence (pi convention).
+  const frontmatterPrompt = parseString(data.prompt);
+  const prompt = body || frontmatterPrompt || "";
+
+  // ── Identity fields ──
+  const mode = parseEnum<AgentMode>(data.mode, AGENT_MODES, "all");
+  const hidden = parseBoolean(data.hidden, false);
+  const color = parseOptionalString(data.color);
+  const disable = parseBoolean(data.disable, false);
+  const description = parseOptionalString(data.description);
+
+  // ── Model fields ──
+  const model = parseOptionalString(data.model);
+  const variant = parseOptionalString(data.variant);
+  const temperature = parseOptionalNumber(data.temperature);
+  const topP = parseOptionalNumber(data["top_p"] ?? data.topP);
+
+  // ── Execution control ──
+  const thinking = parseEnum<ThinkingLevel>(data.thinking, THINKING_LEVELS, defaults.thinking);
+  const steps = parseOptionalNumber(data.steps ?? data.maxSteps); // maxSteps is OC alias
+  const systemPrompt = parseEnum<SystemPromptMode>(
+    data.systemPrompt ?? data["system-prompt"],
+    SYSTEM_PROMPT_MODES,
+    "append",
+  );
+
+  // ── Tools & permissions ──
+  const { permission, tools } = parseToolsAndPermission(data);
+
+  // ── Subagent controls ──
+  const maxDepth = parseNumber(data.maxDepth, 10);
+  const allowedAgents = parseStringArray(data.allowedAgents);
+  const skills = parseStringArray(data.skills);
+
+  return {
+    name,
+    description,
+    mode,
+    hidden,
+    color,
+    disable,
+    model,
+    variant,
+    temperature,
+    topP,
+    thinking,
+    steps,
+    systemPrompt,
+    permission,
+    tools,
+    maxDepth,
+    allowedAgents: allowedAgents.length > 0 ? allowedAgents : undefined,
+    skills: skills.length > 0 ? skills : undefined,
+    prompt,
+    source,
+    filePath,
+  };
+}
+
+// ─── Tools & Permission Resolution ───────────────────────────────────────────
+
+/**
+ * Resolve tools and permission from raw frontmatter data.
+ *
+ * Logic:
+ * 1. If `permission` field exists → use it
+ * 2. Else if `tools` field exists:
+ *    a. If tools is a map (OpenCode style) → convert to permission rules
+ *    b. If tools is a CSV string/array (pi style) → keep as whitelist
+ * 3. Both can coexist: permission for rules, tools for simple whitelist
+ */
+function parseToolsAndPermission(
+  data: Record<string, unknown>,
+): { permission?: PermissionConfig; tools?: string[] } {
+  let permission: PermissionConfig | undefined;
+  let tools: string[] | undefined;
+
+  const rawPermission = data.permission;
+  const rawTools = data.tools;
+
+  // Parse permission block
+  if (rawPermission !== undefined && rawPermission !== null) {
+    permission = parsePermissionConfig(rawPermission);
+  }
+
+  // Parse tools field
+  if (rawTools !== undefined && rawTools !== null) {
+    if (typeof rawTools === "object" && !Array.isArray(rawTools)) {
+      // OpenCode-style tools map: { "read": true, "write": false }
+      // Convert to permission if no explicit permission block
+      if (!permission) {
+        permission = toolsMapToPermission(rawTools as Record<string, unknown>);
+      }
+    } else {
+      // pi-style CSV or array: "read, bash, edit"
+      tools = parseStringArray(rawTools);
+    }
+  }
+
+  return { permission, tools };
+}
+
+/**
+ * Convert OpenCode-style tools map to PermissionConfig.
+ *
+ * { "read": true, "write": false } → { "read": "allow", "write": "deny" }
+ */
+function toolsMapToPermission(toolsMap: Record<string, unknown>): PermissionConfig {
+  const config: PermissionConfig = {};
+
+  for (const [toolName, enabled] of Object.entries(toolsMap)) {
+    // Skip non-boolean values
+    if (typeof enabled !== "boolean") continue;
+
+    // Map edit-like tools to "edit" permission (OpenCode convention)
+    const permKey = toolName === "write" || toolName === "edit" || toolName === "apply_patch"
+      ? "edit"
+      : toolName;
+
+    config[permKey] = enabled ? "allow" : "deny";
+  }
+
+  return config;
+}
+
+/**
+ * Parse and validate a PermissionConfig from raw frontmatter data.
+ */
+function parsePermissionConfig(raw: unknown): PermissionConfig | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new AgentParseError(`invalid permission: expected object, got ${typeof raw}`);
+  }
+
+  const config: PermissionConfig = {};
+  const obj = raw as Record<string, unknown>;
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === "string") {
+      // Simple form: bash: allow
+      const action = validateAction(value, key);
+      config[key] = action;
+    } else if (typeof value === "object" && value !== null) {
+      // Pattern form: edit: { "*.env": deny }
+      const nested: Record<string, PermissionAction> = {};
+      for (const [pattern, action] of Object.entries(value as Record<string, unknown>)) {
+        if (typeof action === "string") {
+          nested[pattern] = validateAction(action, `${key}.${pattern}`);
+        }
+      }
+      config[key] = nested;
+    }
+  }
+
+  return Object.keys(config).length > 0 ? config : undefined;
+}
+
+function validateAction(value: string, context: string): PermissionAction {
+  const action = value as PermissionAction;
+  if (!PERMISSION_ACTIONS.includes(action)) {
+    throw new AgentParseError(
+      `invalid permission action "${value}" for "${context}": must be allow, deny, or ask`,
+    );
+  }
+  return action;
+}
+
+// ─── Type Helpers ────────────────────────────────────────────────────────────
+
+function parseString(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  return String(value).trim() || undefined;
+}
+
+function parseOptionalString(value: unknown): string | undefined {
+  return parseString(value);
+}
+
+function parseBoolean(value: unknown, fallback: boolean): boolean {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    if (value === "true") return true;
+    if (value === "false") return false;
+  }
+  return fallback;
+}
+
+function parseNumber(value: unknown, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === "number") return value;
+  const parsed = Number(value);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+
+function parseOptionalNumber(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "number") return value;
+  const parsed = Number(value);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+function parseEnum<T extends string>(
+  value: unknown,
+  validValues: readonly T[],
+  fallback: T,
+): T {
+  if (value === undefined || value === null) return fallback;
+  const str = String(value).trim() as T;
+  if (!validValues.includes(str)) {
+    throw new AgentParseError(
+      `invalid value "${str}": must be one of ${validValues.join(", ")}`,
+    );
+  }
+  return str;
+}
+
+function parseStringArray(value: unknown): string[] {
+  if (value === undefined || value === null) return [];
+
+  if (Array.isArray(value)) {
+    // Already an array (from YAML parser for inline arrays)
+    return value.map((v) => String(v).trim()).filter(Boolean);
+  }
+
+  if (typeof value === "string") {
+    // CSV string: "read, bash, edit"
+    return value
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
+  return [];
+}

package/src/discovery/loader.ts

@@ -0,0 +1,180 @@
+/**
+ * Agent discovery and loading.
+ *
+ * Scans all discovery paths (pi, OpenCode, shared), parses each .md file
+ * into an AgentDefinition, and merges by name with project overriding global.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import type { AgentDefinition, AgentFs, AgentLoadResult } from "../types.ts";
+import type { SchemaDefaults } from "../config/schema.ts";
+import type { DiscoveryPath } from "../config/paths.ts";
+import { deriveAgentName, getDiscoveryPaths } from "../config/paths.ts";
+import { parseAgentDefinition } from "../config/schema.ts";
+import { SCHEMA_DEFAULTS } from "../config/schema.ts";
+
+// ─── Default Filesystem ──────────────────────────────────────────────────────
+
+const defaultFs: AgentFs = {
+  async listFiles(dir: string): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      const files: string[] = [];
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isFile() || entry.isSymbolicLink()) {
+          if (entry.name.endsWith(".md")) {
+            files.push(fullPath);
+          }
+        } else if (entry.isDirectory()) {
+          // Recurse into subdirectories (for OpenCode-style nested agents)
+          const nested = await this.listFiles(fullPath);
+          files.push(...nested);
+        }
+      }
+      return files.sort();
+    } catch {
+      return [];
+    }
+  },
+
+  async readFile(filePath: string): Promise<string> {
+    return fs.readFile(filePath, "utf8");
+  },
+
+  async exists(dir: string): Promise<boolean> {
+    try {
+      await fs.access(dir);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+// ─── Load Options ────────────────────────────────────────────────────────────
+
+export interface LoadAgentsOptions {
+  /** Current working directory (project root). Defaults to process.cwd() */
+  cwd?: string;
+  /** pi agent directory. Defaults to ~/.pi/agent */
+  agentDir?: string;
+  /** Schema defaults (thinking level fallback). */
+  defaults?: SchemaDefaults;
+  /** Custom filesystem implementation (for testing). */
+  fs?: AgentFs;
+  /** Custom discovery paths (overrides auto-detection). */
+  paths?: DiscoveryPath[];
+}
+
+// ─── Main Loader ─────────────────────────────────────────────────────────────
+
+/**
+ * Load all agent definitions from discovery paths.
+ *
+ * Scan order: global paths first, then project paths.
+ * Merge rule: project overrides global by name.
+ */
+export async function loadAgents(options: LoadAgentsOptions = {}): Promise<AgentLoadResult> {
+  const fileSystem = options.fs ?? defaultFs;
+  const cwd = options.cwd ?? process.cwd();
+  const agentDir = options.agentDir ?? defaultAgentDir();
+  const defaults = options.defaults ?? SCHEMA_DEFAULTS;
+
+  // Build discovery paths
+  const paths = options.paths ?? getDiscoveryPaths(cwd, agentDir);
+
+  // Scan each path, collecting agents grouped by source
+  const globalAgents = new Map<string, AgentDefinition>();
+  const projectAgents = new Map<string, AgentDefinition>();
+  const warnings: AgentLoadResult["warnings"] = [];
+
+  for (const discPath of paths) {
+    // For each subdir pattern, scan the directory
+    for (const subdir of discPath.subdirs) {
+      const scanDir = subdir ? path.join(discPath.dir, subdir) : discPath.dir;
+
+      if (!(await fileSystem.exists(scanDir))) continue;
+
+      const files = await fileSystem.listFiles(scanDir);
+
+      for (const filePath of files) {
+        if (!filePath.endsWith(".md")) continue;
+
+        try {
+          const content = await fileSystem.readFile(filePath);
+          const nameHint = deriveAgentName(filePath, discPath.dir, subdir);
+          const agent = parseAgentDefinition(content, filePath, discPath.source, defaults, nameHint);
+
+          // Skip disabled agents entirely
+          if (agent.disable) continue;
+
+          // Add to the appropriate map
+          const target = discPath.source === "project" ? projectAgents : globalAgents;
+          target.set(agent.name, agent);
+        } catch (error) {
+          warnings.push({
+            filePath,
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
+  }
+
+  // Merge: project overrides global
+  const merged = new Map<string, AgentDefinition>();
+  for (const agent of globalAgents.values()) merged.set(agent.name, agent);
+  for (const agent of projectAgents.values()) merged.set(agent.name, agent);
+
+  return {
+    agents: [...merged.values()],
+    warnings,
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function defaultAgentDir(): string {
+  return path.join(process.env.HOME ?? "", ".pi", "agent");
+}
+
+// ─── Filtering Utilities ────────────────────────────────────────────────────
+
+/**
+ * Filter agents that are visible in the TUI selector.
+ * Shows: mode primary|all, excludes hidden and disable.
+ */
+export function selectableAgents(agents: AgentDefinition[]): AgentDefinition[] {
+  return agents.filter(
+    (a) => !a.hidden && (a.mode === "primary" || a.mode === "all"),
+  );
+}
+
+/**
+ * Filter agents that can be spawned as subagents.
+ * Shows: mode subagent|all.
+ */
+export function spawnableAgents(agents: AgentDefinition[]): AgentDefinition[] {
+  return agents.filter((a) => a.mode === "subagent" || a.mode === "all");
+}
+
+/**
+ * Filter agents available to a parent for delegation.
+ * Applies the parent's allowedAgents whitelist if present.
+ */
+export function agentsAvailableTo(
+  agents: AgentDefinition[],
+  parent?: AgentDefinition,
+): AgentDefinition[] {
+  const spawnable = spawnableAgents(agents);
+
+  if (!parent?.allowedAgents || parent.allowedAgents.length === 0) {
+    return spawnable;
+  }
+
+  return spawnable.filter((a) => parent.allowedAgents!.includes(a.name));
+}

package/src/index.ts

@@ -0,0 +1,204 @@
+/**
+ * pi-open-agents — Unified agent and subagent management for pi.
+ *
+ * Replaces pi-agent-mode and pi-subagents with a single, coherent system.
+ * OpenCode-compatible agent definitions.
+ *
+ * F1: Foundation (types, parser, schema, discovery) ✅
+ * F4: Permission engine (parser, matcher, evaluator) ✅
+ * F2: Primary agents (this phase) ✅
+ * F3: Subagent engine (planned)
+ * F5: OpenCode compat (planned)
+ * F6: Polish (planned)
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import type { AgentDefinition, ThinkingLevel } from "./types.ts";
+import { loadAgents, selectableAgents, spawnableAgents } from "./discovery/loader.ts";
+import { AgentManager } from "./primary/manager.ts";
+import { refreshAgentTools, buildSystemPrompt } from "./primary/executor.ts";
+import { updateBanner } from "./tui/banner.ts";
+import { registerTuiControls } from "./tui/selector.ts";
+import { registerAgentTools } from "./tui/tools.ts";
+import { registerSubagentTool } from "./subagent/tool.ts";
+import { isSubagentReplaceSystemPrompt } from "./subagent/env.ts";
+
+// ─── Settings ────────────────────────────────────────────────────────────────
+
+interface Settings {
+  defaultAgent?: string;
+  defaultThinkingLevel?: ThinkingLevel;
+}
+
+function loadSettings(cwd: string): Settings {
+  const globalPath = join(getAgentDir(), "settings.json");
+  const projectPath = join(cwd, ".pi", "settings.json");
+
+  let settings: Settings = {};
+
+  for (const p of [globalPath, projectPath]) {
+    if (existsSync(p)) {
+      try {
+        const content = readFileSync(p, "utf-8");
+        const parsed = JSON.parse(content) as Settings;
+        settings = { ...settings, ...parsed };
+      } catch {
+        // ignore invalid json
+      }
+    }
+  }
+
+  return settings;
+}
+
+// ─── Extension Entry Point ───────────────────────────────────────────────────
+
+export default function piOpenAgents(pi: ExtensionAPI): void {
+  const manager = new AgentManager();
+
+  // ── Register CLI flag immediately (before session_start) ──────────────────
+  // Extension flags are parsed during startup, before session_start fires.
+  // Must register here, not inside session_start.
+  pi.registerFlag("agent", {
+    description: "Default agent to use at startup",
+    type: "string",
+  });
+
+  // ── Session Start: Load agents and apply default ───────────────────────────
+
+  pi.on("session_start", async (event, ctx) => {
+    // Load settings for thinking fallback
+    const settings = loadSettings(ctx.cwd);
+
+    // Load all agent definitions from discovery paths
+    const result = await loadAgents({
+      cwd: ctx.cwd,
+      agentDir: getAgentDir(),
+      defaults: { thinking: settings.defaultThinkingLevel ?? "off" },
+    });
+
+    // Log any parse warnings
+    for (const w of result.warnings) {
+      ctx.ui.notify(`Agent parse warning: ${w.filePath}: ${w.message}`, "warning");
+    }
+
+    manager.setAgents(result.agents);
+
+    // Register TUI controls + tools + subagent tool
+    registerTuiControls(manager, pi);
+    registerAgentTools(manager, pi);
+    registerSubagentTool(pi, {
+      agents: result.agents,
+      agentDir: getAgentDir(),
+      getActiveAgent: () => manager.getActive(),
+    });
+
+    // Check for --agent CLI flag first (highest priority)
+    const agentFlag = pi.getFlag("agent");
+    if (typeof agentFlag === "string" && agentFlag) {
+      const agent = manager.getAgent(agentFlag);
+      if (agent) {
+        await manager.apply(agentFlag, pi, ctx);
+      }
+      updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+      return;
+    }
+
+    // Try to restore from session state (if resuming)
+    if (event.reason === "resume" || event.reason === "fork") {
+      const entries = ctx.sessionManager.getEntries();
+      const agentEntry = entries
+        .filter((e: { type: string; customType?: string }) =>
+          e.type === "custom" && e.customType === "open-agents-state")
+        .pop() as { data?: { name: string } } | undefined;
+
+      if (agentEntry?.data?.name) {
+        manager.restoreFromSession(agentEntry.data.name);
+        // Re-apply tools on resume (model preserved from session)
+        const active = manager.getActive();
+        if (active) {
+          refreshAgentTools(active, pi);
+        }
+        updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+        return;
+      }
+    }
+
+    // Try to load from settings (defaultAgent)
+    if (settings.defaultAgent) {
+      const agent = manager.getAgent(settings.defaultAgent);
+      if (agent) {
+        await manager.apply(settings.defaultAgent, pi, ctx);
+      }
+    }
+
+    // Show status
+    updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
+  });
+
+  // ── Before Agent Start: Inject system prompt + refresh tools ───────────────
+
+  pi.on("before_agent_start", async (event) => {
+    const active = manager.getActive();
+    if (!active) return;
+
+    // Re-evaluate tool set (catches async-registered tools like MCP)
+    refreshAgentTools(active, pi);
+
+    // Inject system prompt
+    const modifiedPrompt = buildSystemPrompt(active, event.systemPrompt);
+    if (modifiedPrompt) {
+      return { systemPrompt: modifiedPrompt };
+    }
+  });
+
+  // ── Before Agent Start (subagent replace mode): Inject available subagents ─
+
+  pi.on("before_agent_start", async (event) => {
+    if (!isSubagentReplaceSystemPrompt(process.env)) return;
+    // In replace mode, append available subagent list to the system prompt
+    const agents = manager.getAgents();
+    const spawnable = spawnableAgents(agents);
+    if (spawnable.length === 0) return;
+    const names = spawnable.map((a: AgentDefinition) => a.name).sort().join(", ");
+    const block = `\n\nAvailable subagents:\n- ${names.split(", ").join("\n- ")}`;
+    return { systemPrompt: event.systemPrompt + block };
+  });
+
+  // ── Turn Start: Persist agent state (only on change) ───────────────────────
+
+  pi.on("turn_start", async () => {
+    if (manager.shouldPersist()) {
+      pi.appendEntry("open-agents-state", { name: manager.getActiveName() });
+      manager.markPersisted();
+    }
+  });
+}
+
+// ─── Re-exports ──────────────────────────────────────────────────────────────
+
+export * from "./types.ts";
+export { parseFrontmatter } from "./config/frontmatter.ts";
+export type { ParsedFrontmatter } from "./config/frontmatter.ts";
+export { parseAgentDefinition, AgentParseError, SCHEMA_DEFAULTS } from "./config/schema.ts";
+export type { SchemaDefaults } from "./config/schema.ts";
+export { getDiscoveryPaths, deriveAgentName } from "./config/paths.ts";
+export type { DiscoveryPath } from "./config/paths.ts";
+export { loadAgents, selectableAgents, spawnableAgents, agentsAvailableTo } from "./discovery/loader.ts";
+export type { LoadAgentsOptions } from "./discovery/loader.ts";
+export { parsePermissionRules, mergePermissionConfigs } from "./permission/parser.ts";
+export { matchPattern, isWildcardPattern } from "./permission/matcher.ts";
+export { evaluate, toolToPermission, getDisabledTools, filterDisabledTools } from "./permission/evaluator.ts";
+
+// Subagent re-exports
+export { runSubagent, resolveSubagentSession, resolvePiEntryPoint } from "./subagent/executor.ts";
+export type { AgentProgress, AgentResult, RunSubagentOptions, SubagentSessionInfo, SubagentSessionMode } from "./subagent/executor.ts";
+export { resolveSkills } from "./subagent/skills.ts";
+export type { ResolvedSkill } from "./subagent/skills.ts";
+export { buildSubagentPrompt } from "./subagent/prompt.ts";
+export { formatResultLines, formatUsage } from "./subagent/render.ts";