pi-open-agents 0.1.0

package/src/permission/evaluator.ts

@@ -0,0 +1,160 @@
+/**
+ * Permission evaluator.
+ *
+ * Implements last-match-wins evaluation (like CSS specificity).
+ *
+ * Given a tool name and its argument, walks the rule list in order.
+ * The last matching rule determines the action.
+ * If no rule matches, the default action is "ask".
+ *
+ * Also provides:
+ * - Tool → permission category mapping (write → edit, etc.)
+ * - disabled() — tools that should never be sent to the LLM
+ */
+
+import type { PermissionAction, PermissionRule } from "../types.ts";
+import { matchPattern } from "./matcher.ts";
+
+// ─── Tool → Permission Mapping ───────────────────────────────────────────────
+
+/**
+ * Map a tool name to its permission category.
+ *
+ * Multiple tools can share a permission category:
+ *   write, edit, apply_patch  → "edit"
+ *   list_mcp_resources, read_mcp_resource → "read"
+ *
+ * Everything else maps by tool name directly.
+ */
+export function toolToPermission(toolName: string): string {
+  // File-editing tools all map to "edit"
+  if (toolName === "write" || toolName === "edit" || toolName === "apply_patch") {
+    return "edit";
+  }
+
+  // MCP read tools map to "read"
+  if (toolName === "list_mcp_resources" || toolName === "read_mcp_resource") {
+    return "read";
+  }
+
+  // Everything else uses its own name as the permission key
+  return toolName;
+}
+
+// ─── Evaluation ──────────────────────────────────────────────────────────────
+
+export interface EvalResult {
+  /** The action to take: allow, deny, or ask */
+  action: PermissionAction;
+  /** The permission category that was matched */
+  permission: string;
+  /** The pattern that was matched, or "*" if no rule matched */
+  pattern: string;
+  /** Whether any rule matched (false = default action applied) */
+  matched: boolean;
+}
+
+/**
+ * Evaluate permission for a tool call.
+ *
+ * @param toolName    The tool being called (e.g. "edit", "bash")
+ * @param arg         The primary argument (file path, command, etc.)
+ * @param rules       Ordered permission rules (last-match-wins)
+ * @returns           Evaluation result
+ */
+export function evaluate(
+  toolName: string,
+  arg: string | undefined,
+  rules: PermissionRule[],
+): EvalResult {
+  const permission = toolToPermission(toolName);
+  const value = arg ?? "";
+
+  // Walk all rules, keep track of the last match
+  let lastMatch: PermissionRule | undefined;
+
+  for (const rule of rules) {
+    // Permission must match (with wildcard support on the permission key too)
+    if (!matchPermissionKey(rule.permission, permission)) continue;
+
+    // Pattern must match the argument
+    if (!matchPattern(rule.pattern, value)) continue;
+
+    lastMatch = rule;
+  }
+
+  if (lastMatch) {
+    return {
+      action: lastMatch.action,
+      permission: lastMatch.permission,
+      pattern: lastMatch.pattern,
+      matched: true,
+    };
+  }
+
+  // No rule matched — default to "ask"
+  return {
+    action: "ask",
+    permission,
+    pattern: "*",
+    matched: false,
+  };
+}
+
+/**
+ * Match a permission key, with wildcard support.
+ *
+ * "edit" matches "edit"
+ * "*" matches anything
+ * "edit" matches "e*" (not typical, but supported)
+ */
+function matchPermissionKey(rulePermission: string, toolPermission: string): boolean {
+  if (rulePermission === "*") return true;
+  return matchPattern(rulePermission, toolPermission);
+}
+
+// ─── Disabled Tools ──────────────────────────────────────────────────────────
+
+/**
+ * Determine which tools are disabled (should never be sent to the LLM).
+ *
+ * A tool is disabled if the last matching rule for it (with pattern "*")
+ * is "deny". This means the tool is globally forbidden for this agent.
+ *
+ * Tools that are "ask" or "allow" with pattern "*" are NOT disabled —
+ * they may be used, just with or without confirmation.
+ *
+ * @param toolNames  All available tool names
+ * @param rules      Permission rules to evaluate against
+ * @returns          Set of tool names that should be disabled
+ */
+export function getDisabledTools(
+  toolNames: string[],
+  rules: PermissionRule[],
+): Set<string> {
+  const disabled = new Set<string>();
+
+  for (const toolName of toolNames) {
+    const result = evaluate(toolName, undefined, rules);
+    if (result.action === "deny" && result.pattern === "*") {
+      disabled.add(toolName);
+    }
+  }
+
+  return disabled;
+}
+
+/**
+ * Filter a list of tools, removing disabled ones.
+ */
+export function filterDisabledTools<T extends { name: string }>(
+  tools: T[],
+  rules: PermissionRule[],
+): T[] {
+  const disabled = getDisabledTools(
+    tools.map((t) => t.name),
+    rules,
+  );
+
+  return tools.filter((t) => !disabled.has(t.name));
+}

package/src/permission/matcher.ts

@@ -0,0 +1,99 @@
+//
+// Glob/wildcard pattern matching for permission evaluation.
+//
+// Supports:
+// - star: matches any number of characters (except /)
+// - double-star: matches any number of characters including /
+// - ?: matches exactly one character
+// - Literal characters match themselves
+//
+// Examples:
+//   match("star.env", "secret.env")     → true (star matches)
+//   match("star.env", "dir/secret.env") → false (star doesn't cross /)
+//   match("double-star.env", "a/b.env") → true (double-star crosses /)
+//
+
+//
+// Match a glob pattern against a string.
+//
+// @param pattern  Glob pattern (e.g. star.env, double-star.ts, exact-match)
+// @param value    String to test (e.g. a file path, tool argument)
+// @returns        true if the pattern matches the entire string
+//
+export function matchPattern(pattern: string, value: string): boolean {
+  // Fast path: * matches everything
+  if (pattern === "*") return true;
+
+  // Fast path: exact match
+  if (pattern === value) return true;
+
+  // No wildcard characters — must be exact
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return pattern === value;
+  }
+
+  // Convert glob to regex
+  const regexStr = globToRegex(pattern);
+  const regex = new RegExp(`^${regexStr}$`);
+  return regex.test(value);
+}
+
+/**
+ * Convert a glob pattern to a regex string.
+ *
+ * Handles * (non-greedy, no /), ** (greedy, includes /), ? (single char).
+ */
+function globToRegex(pattern: string): string {
+  let result = "";
+  let i = 0;
+
+  while (i < pattern.length) {
+    const char = pattern[i];
+
+    // Check for ** (must come before single *)
+    if (char === "*" && pattern[i + 1] === "*") {
+      // ** matches everything including /
+      // Also handle **/ (match zero or more path segments)
+      if (pattern[i + 2] === "/") {
+        result += "(?:.*/)?"; // match "a/b/" or ""
+        i += 3;
+      } else {
+        result += ".*";
+        i += 2;
+      }
+    } else if (char === "*") {
+      // * matches any chars except /
+      result += "[^/]*";
+      i++;
+    } else if (char === "?") {
+      // ? matches exactly one char (except /)
+      result += "[^/]";
+      i++;
+    } else {
+      // Escape regex special characters
+      result += escapeRegexChar(char);
+      i++;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Escape a character for use in a regex.
+ * Only escapes characters that have special meaning.
+ */
+function escapeRegexChar(char: string): string {
+  const special = ".+^${}()|[]\\";
+  if (special.includes(char)) {
+    return "\\" + char;
+  }
+  return char;
+}
+
+/**
+ * Check if a pattern contains wildcards.
+ */
+export function isWildcardPattern(pattern: string): boolean {
+  return pattern.includes("*") || pattern.includes("?");
+}

package/src/permission/parser.ts

@@ -0,0 +1,81 @@
+/**
+ * Permission config parser.
+ *
+ * Flattens a PermissionConfig (from frontmatter) into a flat list of
+ * PermissionRule objects that the evaluator can process.
+ *
+ * Input:
+ *   bash: allow
+ *   edit:
+ *     "*.env": deny
+ *     "*.md": allow
+ *   read: allow
+ *
+ * Output:
+ *   [
+ *     { permission: "bash",  pattern: "*",    action: "allow" },
+ *     { permission: "edit",  pattern: "*.env", action: "deny"  },
+ *     { permission: "edit",  pattern: "*.md",  action: "allow" },
+ *     { permission: "read",  pattern: "*",    action: "allow" },
+ *   ]
+ */
+
+import type { PermissionConfig, PermissionRule } from "../types.ts";
+import { toolToPermission } from "./evaluator.ts";
+
+/**
+ * Flatten a PermissionConfig into ordered PermissionRule[].
+ *
+ * Rules from nested objects are expanded with their pattern.
+ * Simple string values get pattern "*".
+ *
+ * Permission keys are normalized via toolToPermission (write → edit, etc.)
+ * so that both "write: deny" and "edit: deny" affect the edit tool.
+ *
+ * Order is preserved as written (object key order).
+ */
+export function parsePermissionRules(config: PermissionConfig): PermissionRule[] {
+  const rules: PermissionRule[] = [];
+
+  for (const [permission, value] of Object.entries(config)) {
+    // Normalize tool name to permission category (write -> edit, etc.)
+    const normalizedPerm = toolToPermission(permission);
+
+    if (typeof value === "string") {
+      // Simple form: bash: allow
+      rules.push({
+        permission: normalizedPerm,
+        pattern: "*",
+        action: value,
+      });
+    } else if (typeof value === "object" && value !== null) {
+      // Pattern form: edit: { "*.env": deny, "*.md": allow }
+      for (const [pattern, action] of Object.entries(value)) {
+        if (typeof action === "string") {
+          rules.push({
+            permission: normalizedPerm,
+            pattern,
+            action,
+          });
+        }
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Merge multiple permission configs into a single rule list.
+ * Later configs take precedence (appended last, last-match-wins).
+ */
+export function mergePermissionConfigs(...configs: (PermissionConfig | undefined)[]): PermissionRule[] {
+  const rules: PermissionRule[] = [];
+
+  for (const config of configs) {
+    if (!config) continue;
+    rules.push(...parsePermissionRules(config));
+  }
+
+  return rules;
+}

package/src/primary/executor.ts

@@ -0,0 +1,167 @@
+/**
+ * Agent executor — applies agent configuration to the current session.
+ *
+ * Handles:
+ * - Model switching (provider/model-id resolution)
+ * - Thinking level (per-agent, with fallback to session default)
+ * - Tool filtering via permission engine
+ * - System prompt injection (via before_agent_start hook)
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentDefinition, ModelRef, PermissionRule } from "../types.ts";
+import { parsePermissionRules } from "../permission/parser.ts";
+import { getDisabledTools } from "../permission/evaluator.ts";
+
+// ─── Model Resolution ────────────────────────────────────────────────────────
+
+/**
+ * Parse a model reference string "provider/model-id" into components.
+ */
+export function parseModelRef(ref: string): ModelRef | undefined {
+  const slashIdx = ref.indexOf("/");
+  if (slashIdx === -1) return undefined;
+  return {
+    provider: ref.slice(0, slashIdx),
+    modelId: ref.slice(slashIdx + 1),
+  };
+}
+
+/**
+ * Apply model override if the agent specifies one.
+ */
+async function applyModel(agent: AgentDefinition, pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  if (!agent.model) return;
+
+  const ref = parseModelRef(agent.model);
+  if (!ref) return;
+
+  const model = ctx.modelRegistry.find(ref.provider, ref.modelId);
+  if (!model) return;
+
+  const success = await pi.setModel(model);
+  if (!success) {
+    ctx.ui.notify(
+      `Agent "${agent.name}": No API key for ${ref.provider}/${ref.modelId}`,
+      "warning",
+    );
+  }
+}
+
+// ─── Thinking Level ──────────────────────────────────────────────────────────
+
+/**
+ * Apply thinking level override.
+ * Falls back to the session's current thinking level if agent doesn't specify one.
+ */
+function applyThinking(agent: AgentDefinition, pi: ExtensionAPI): void {
+  pi.setThinkingLevel(agent.thinking);
+}
+
+// ─── Tool Filtering ──────────────────────────────────────────────────────────
+
+/**
+ * Apply tool restrictions based on agent configuration.
+ *
+ * Logic:
+ * 1. If agent has permission rules → filter via permission engine
+ * 2. Else if agent has tools whitelist → filter to only those (builtin only)
+ * 3. Otherwise → all tools active
+ *
+ * Extension-provided tools (MCP, SDK) always remain active.
+ */
+function applyTools(agent: AgentDefinition, pi: ExtensionAPI): void {
+  const allTools = pi.getAllTools();
+
+  // Case 1: Permission-based filtering
+  if (agent.permission) {
+    const rules = parsePermissionRules(agent.permission);
+    const disabled = getDisabledTools(
+      allTools.map((t) => t.name),
+      rules,
+    );
+    const filtered = allTools
+      .filter((t) => {
+        // Always keep non-builtin tools (extensions, MCP)
+        if (t.sourceInfo?.source !== "builtin") return true;
+        return !disabled.has(t.name);
+      })
+      .map((t) => t.name);
+    pi.setActiveTools(filtered);
+    return;
+  }
+
+  // Case 2: Simple tools whitelist (builtin only)
+  if (agent.tools && agent.tools.length > 0) {
+    const whitelist = new Set(agent.tools.map((t) => t.toLowerCase()));
+    const filtered = allTools
+      .filter((t) => {
+        if (t.sourceInfo?.source !== "builtin") return true;
+        return whitelist.has(t.name.toLowerCase());
+      })
+      .map((t) => t.name);
+    pi.setActiveTools(filtered);
+    return;
+  }
+
+  // Case 3: No restrictions — keep all tools
+  pi.setActiveTools(allTools.map((t) => t.name));
+}
+
+// ─── Main Entry Point ────────────────────────────────────────────────────────
+
+/**
+ * Apply an agent's model, thinking, and tools configuration.
+ * System prompt injection happens in the before_agent_start hook.
+ */
+export async function applyAgentConfig(
+  agent: AgentDefinition,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  await applyModel(agent, pi, ctx);
+  applyThinking(agent, pi);
+  applyTools(agent, pi);
+}
+
+/**
+ * Re-evaluate tool restrictions.
+ * Called from before_agent_start to catch async-registered tools.
+ */
+export function refreshAgentTools(agent: AgentDefinition, pi: ExtensionAPI): void {
+  applyTools(agent, pi);
+}
+
+/**
+ * Build the system prompt injection for the active agent.
+ *
+ * Returns the modified system prompt (agent body prepended),
+ * or undefined if no injection is needed.
+ */
+export function buildSystemPrompt(
+  agent: AgentDefinition,
+  currentPrompt: string,
+): string | undefined {
+  if (!agent.prompt) return undefined;
+
+  switch (agent.systemPrompt) {
+    case "append":
+      // Prepend agent body to system prompt
+      return `${agent.prompt}\n\n${currentPrompt}`;
+
+    case "replace":
+      // Replace the provider prompt but keep context files
+      // In inline mode, we can only append — full replace requires
+      // the subprocess executor (subagent path)
+      // For primary agents, "replace" behaves like append for now
+      return `${agent.prompt}\n\n${currentPrompt}`;
+
+    case "replace-all":
+      // Full replacement — only agent body
+      return agent.prompt;
+
+    default:
+      return undefined;
+  }
+}

package/src/primary/manager.ts

@@ -0,0 +1,147 @@
+/**
+ * Agent state management.
+ *
+ * Tracks the active agent, handles apply/clear/restore lifecycle,
+ * and coordinates with the executor for model/thinking/tools/prompt.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentDefinition, ThinkingLevel } from "../types.ts";
+import { applyAgentConfig } from "./executor.ts";
+
+interface OriginalState {
+  model: Model<any> | undefined;
+  thinkingLevel: ThinkingLevel;
+  toolNames: string[];
+}
+
+export class AgentManager {
+  private agents: Map<string, AgentDefinition> = new Map();
+  private activeName: string | undefined;
+  private active: AgentDefinition | undefined;
+  private originalState: OriginalState | undefined;
+  private lastPersistedName: string | undefined;
+
+  /** Reload agent definitions from the registry */
+  setAgents(agents: AgentDefinition[]): void {
+    this.agents = new Map(agents.map((a) => [a.name, a]));
+  }
+
+  getAgents(): AgentDefinition[] {
+    return [...this.agents.values()];
+  }
+
+  getAgent(name: string): AgentDefinition | undefined {
+    return this.agents.get(name);
+  }
+
+  getActive(): AgentDefinition | undefined {
+    return this.active;
+  }
+
+  getActiveName(): string | undefined {
+    return this.activeName;
+  }
+
+  isActive(name: string): boolean {
+    return this.activeName === name;
+  }
+
+  /**
+   * Apply an agent configuration to the current session.
+   * Applies model, thinking level, tools, and stores the active agent.
+   */
+  async apply(name: string, pi: ExtensionAPI, ctx: ExtensionContext): Promise<boolean> {
+    const agent = this.agents.get(name);
+    if (!agent) return false;
+
+    // Snapshot state on first apply (for restore on clear)
+    if (this.activeName === undefined) {
+      this.originalState = {
+        model: ctx.model,
+        thinkingLevel: pi.getThinkingLevel() as ThinkingLevel,
+        toolNames: pi.getAllTools().map((t) => t.name),
+      };
+    }
+
+    this.activeName = name;
+    this.active = agent;
+
+    await applyAgentConfig(agent, pi, ctx);
+
+    return true;
+  }
+
+  /**
+   * Clear the active agent and restore original state.
+   */
+  async clear(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+    if (this.originalState) {
+      // Restore model
+      if (this.originalState.model) {
+        await pi.setModel(this.originalState.model);
+      }
+      // Restore thinking level
+      pi.setThinkingLevel(this.originalState.thinkingLevel);
+      // Restore tools
+      pi.setActiveTools(this.originalState.toolNames);
+    } else {
+      // No snapshot — just restore all tools
+      pi.setActiveTools(pi.getAllTools().map((t) => t.name));
+    }
+
+    this.activeName = undefined;
+    this.active = undefined;
+  }
+
+  /**
+   * Cycle to the next selectable agent (primary|all only).
+   * Includes "(none)" to allow clearing.
+   */
+  async cycle(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+    const selectable = [...this.agents.values()]
+      .filter((a) => !a.hidden && (a.mode === "primary" || a.mode === "all"))
+      .map((a) => a.name)
+      .sort();
+
+    if (selectable.length === 0) return;
+
+    const cycleList = ["(none)", ...selectable];
+    const current = this.activeName ?? "(none)";
+    const idx = cycleList.indexOf(current);
+    const next = cycleList[idx === -1 ? 0 : (idx + 1) % cycleList.length];
+
+    if (next === "(none)") {
+      await this.clear(pi, ctx);
+    } else {
+      await this.apply(next, pi, ctx);
+    }
+  }
+
+  // ─── Persistence ───────────────────────────────────────────────────────────
+
+  /**
+   * Check if agent state should be persisted (only on change).
+   */
+  shouldPersist(): boolean {
+    return this.activeName !== undefined && this.activeName !== this.lastPersistedName;
+  }
+
+  markPersisted(): void {
+    this.lastPersistedName = this.activeName;
+  }
+
+  /**
+   * Restore agent from session state (without re-applying model/tools).
+   * Used on session resume.
+   */
+  restoreFromSession(name: string): void {
+    const agent = this.agents.get(name);
+    if (agent) {
+      this.activeName = name;
+      this.active = agent;
+      this.lastPersistedName = name;
+    }
+  }
+}