@aliou/pi-guardrails 0.7.6 → 0.8.0

package/src/lib/types.ts

@@ -0,0 +1,115 @@
+import type { AgentTool, ThinkingLevel } from "@mariozechner/pi-agent-core";
+import type { Model } from "@mariozechner/pi-ai";
+import type { Skill, ToolDefinition } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Configuration for a subagent.
+ */
+export interface SubagentConfig {
+  /** Subagent name (for logging and run ID) */
+  name: string;
+
+  /** Model instance to use */
+  // biome-ignore lint/suspicious/noExplicitAny: Model type requires any for generic API
+  model: Model<any>;
+
+  /** System prompt for the subagent */
+  systemPrompt: string;
+
+  /** Built-in tools (AgentTool[]) - e.g., from createReadOnlyTools() */
+  tools?: AgentTool[];
+
+  /** Custom tools (ToolDefinition[]) - e.g., GitHub tools */
+  customTools?: ToolDefinition[];
+
+  /** Skills to load into system prompt */
+  skills?: Skill[];
+
+  /** Thinking level. Default: "low" */
+  thinkingLevel?: ThinkingLevel;
+
+  /** Logging options */
+  logging?: {
+    /** Enable logging. Default: false */
+    enabled: boolean;
+    /** Include raw events in debug.jsonl. Default: false */
+    debug?: boolean;
+  };
+}
+
+/**
+ * Tool call state for tracking subagent tool executions.
+ */
+export interface SubagentToolCall {
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+  status: "running" | "done" | "error";
+  /** Epoch ms when tool execution started */
+  startedAt?: number;
+  /** Epoch ms when tool execution ended */
+  endedAt?: number;
+  /** Duration in milliseconds (set when ended) */
+  durationMs?: number;
+  result?: unknown;
+  error?: string;
+  /** Partial result from tool updates (for progress display) */
+  partialResult?: {
+    content: Array<{ type: string; text?: string }>;
+    details?: unknown;
+  };
+}
+
+/**
+ * Usage/cost information from the model response.
+ */
+export interface SubagentUsage {
+  /** Input tokens from API (if available) */
+  inputTokens?: number;
+  /** Output tokens from API (if available) */
+  outputTokens?: number;
+  /** Cache read tokens (if available) */
+  cacheReadTokens?: number;
+  /** Cache write tokens (if available) */
+  cacheWriteTokens?: number;
+  /** Estimated tokens from response length (chars/4) */
+  estimatedTokens: number;
+  /** LLM cost in USD (if available) */
+  llmCost?: number;
+  /** Tool/API cost in USD (e.g., Exa, GitHub) */
+  toolCost?: number;
+  /** Total cost in USD (llmCost + toolCost) */
+  totalCost?: number;
+}
+
+/**
+ * Result from executing a subagent.
+ */
+export interface SubagentResult {
+  /** Final text content from the subagent */
+  content: string;
+
+  /** Whether the subagent was aborted */
+  aborted: boolean;
+
+  /** Final tool call states */
+  toolCalls: SubagentToolCall[];
+
+  /** Total subagent execution duration in milliseconds */
+  totalDurationMs: number;
+
+  /** Error message if the subagent failed */
+  error?: string;
+
+  /** Unique run identifier */
+  runId: string;
+
+  /** Usage/cost information */
+  usage: SubagentUsage;
+}
+
+/** Callback for text streaming updates */
+export type OnTextUpdate = (delta: string, accumulated: string) => void;
+
+/** Callback for tool execution updates */
+export type OnToolUpdate = (toolCalls: SubagentToolCall[]) => void;

package/src/utils/events.ts

@@ -4,7 +4,7 @@ export const GUARDRAILS_BLOCKED_EVENT = "guardrails:blocked";
 export const GUARDRAILS_DANGEROUS_EVENT = "guardrails:dangerous";
 
 export interface GuardrailsBlockedEvent {
-  feature: "protectEnvFiles" | "permissionGate";
+  feature: "policies" | "permissionGate";
   toolName: string;
   input: Record<string, unknown>;
   reason: string;

package/src/utils/matching.ts

@@ -9,6 +9,7 @@
  */
 
 import type { PatternConfig } from "../config";
+import { pendingWarnings } from "./warnings";
 
 export interface CompiledPattern {
   test: (input: string) => boolean;
@@ -62,7 +63,9 @@ export function compileFilePattern(config: PatternConfig): CompiledPattern {
       const re = new RegExp(config.pattern, "i");
       return { test: (input) => re.test(input), source: config };
     } catch {
-      console.error(`Invalid regex in guardrails config: ${config.pattern}`);
+      pendingWarnings.push(
+        `Invalid regex in guardrails config: ${config.pattern}`,
+      );
       return { test: () => false, source: config };
     }
   }
@@ -89,7 +92,9 @@ export function compileCommandPattern(config: PatternConfig): CompiledPattern {
       const re = new RegExp(config.pattern);
       return { test: (input) => re.test(input), source: config };
     } catch {
-      console.error(`Invalid regex in guardrails config: ${config.pattern}`);
+      pendingWarnings.push(
+        `Invalid regex in guardrails config: ${config.pattern}`,
+      );
       return { test: () => false, source: config };
     }
   }

package/src/utils/migration.ts

@@ -13,8 +13,15 @@ import type {
   GuardrailsConfig,
   PatternConfig,
 } from "../config";
+import { pendingWarnings } from "./warnings";
 
-export const CURRENT_VERSION = "0.6.0-20260204";
+/**
+ * Config schema version.
+ *
+ * Keep this independent from package.json version.
+ * Bump only when config schema/default migration markers change.
+ */
+export const CURRENT_VERSION = "0.8.0-20260228";
 
 /**
  * Check if a config needs migration (no version field = v0).
@@ -77,6 +84,105 @@ export function migrateV0(config: GuardrailsConfig): GuardrailsConfig {
   return migrated;
 }
 
+/**
+ * Check if a config still uses deprecated envFiles/protectEnvFiles fields.
+ */
+export function needsEnvFilesToPoliciesMigration(
+  config: GuardrailsConfig,
+): boolean {
+  const raw = config as Record<string, unknown>;
+  if (raw.envFiles !== undefined) return true;
+
+  const features = raw.features as Record<string, unknown> | undefined;
+  return features?.protectEnvFiles !== undefined;
+}
+
+/**
+ * Migrate deprecated envFiles/protectEnvFiles fields to policies.
+ */
+export function migrateEnvFilesToPolicies(
+  config: GuardrailsConfig,
+): GuardrailsConfig {
+  const migrated = structuredClone(config);
+  const raw = migrated as Record<string, unknown>;
+  const features = raw.features as Record<string, unknown> | undefined;
+  const envFiles = raw.envFiles as Record<string, unknown> | undefined;
+
+  if (features?.protectEnvFiles !== undefined) {
+    features.policies = features.protectEnvFiles;
+    delete features.protectEnvFiles;
+  }
+
+  if (envFiles) {
+    const rule: Record<string, unknown> = {
+      id: "secret-files",
+      description: "Files containing secrets (migrated from envFiles)",
+      protection: "noAccess",
+    };
+
+    if (envFiles.protectedPatterns) {
+      rule.patterns = envFiles.protectedPatterns;
+    }
+    if (envFiles.allowedPatterns) {
+      rule.allowedPatterns = envFiles.allowedPatterns;
+    }
+    if (envFiles.onlyBlockIfExists !== undefined) {
+      rule.onlyIfExists = envFiles.onlyBlockIfExists;
+    }
+    if (typeof envFiles.blockMessage === "string") {
+      rule.blockMessage = envFiles.blockMessage;
+    }
+
+    if (Array.isArray(envFiles.protectedDirectories)) {
+      const dirs = envFiles.protectedDirectories as Array<
+        Record<string, unknown>
+      >;
+      const patterns = Array.isArray(rule.patterns)
+        ? ([...rule.patterns] as Array<Record<string, unknown>>)
+        : [];
+
+      for (const dir of dirs) {
+        const dirPattern = dir.pattern;
+        if (typeof dirPattern !== "string" || dirPattern.trim() === "") {
+          continue;
+        }
+
+        const normalized = dirPattern.endsWith("/**")
+          ? dirPattern
+          : `${dirPattern}/**`;
+        patterns.push({ pattern: normalized, regex: dir.regex });
+      }
+
+      if (patterns.length > 0) {
+        rule.patterns = patterns;
+      }
+    }
+
+    if (Array.isArray(envFiles.protectedTools)) {
+      pendingWarnings.push(
+        "[guardrails] envFiles.protectedTools is deprecated and has no direct policies equivalent. " +
+          "The migrated secret-files rule uses protection=noAccess.",
+      );
+    }
+
+    if (!Array.isArray(rule.patterns) || rule.patterns.length === 0) {
+      rule.patterns = [
+        { pattern: ".env" },
+        { pattern: ".env.local" },
+        { pattern: ".env.production" },
+        { pattern: ".env.prod" },
+        { pattern: ".dev.vars" },
+      ];
+    }
+
+    raw.policies = { rules: [rule] };
+    delete raw.envFiles;
+  }
+
+  raw.version = CURRENT_VERSION;
+  return migrated as GuardrailsConfig;
+}
+
 /**
  * Migrate a string[] or PatternConfig[] to PatternConfig[] with regex: true.
  * Handles mixed arrays (some already migrated, some still strings).
@@ -129,7 +235,7 @@ export async function backupConfig(configPath: string): Promise<void> {
     try {
       await copyFile(configPath, backupPath);
     } catch (err) {
-      console.warn(`guardrails: could not back up config: ${err}`);
+      pendingWarnings.push(`guardrails: could not back up config: ${err}`);
     }
   }
 }

package/src/utils/warnings.ts

@@ -0,0 +1,7 @@
+/**
+ * Module-level warnings queue for messages that arise before any session
+ * context is available (config loading, migration, pattern compilation).
+ *
+ * Drained and reported via ctx.ui.notify in the session_start handler.
+ */
+export const pendingWarnings: string[] = [];

package/src/hooks/protect-env-files.ts

@@ -1,220 +0,0 @@
-import { stat } from "node:fs/promises";
-import { resolve } from "node:path";
-import { parse } from "@aliou/sh";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { ResolvedConfig } from "../config";
-import { emitBlocked } from "../utils/events";
-import { expandGlob, hasGlobChars } from "../utils/glob-expander";
-import { type CompiledPattern, compileFilePatterns } from "../utils/matching";
-import { walkCommands, wordToString } from "../utils/shell-utils";
-
-/**
- * Prevents accessing .env files unless they match an allowed pattern.
- * Protects sensitive environment files from being accessed accidentally.
- *
- * Uses AST-based parsing for bash commands to extract file references,
- * with glob expansion via `fd` when args contain shell glob characters.
- */
-
-async function fileExists(filePath: string): Promise<boolean> {
-  try {
-    await stat(resolve(filePath));
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function isProtectedEnvFile(
-  filePath: string,
-  protectedPatterns: CompiledPattern[],
-  allowedPatterns: CompiledPattern[],
-  dirPatterns: CompiledPattern[],
-  onlyBlockIfExists: boolean,
-): Promise<boolean> {
-  const isProtected = protectedPatterns.some((p) => p.test(filePath));
-  if (!isProtected) return false;
-
-  const isAllowed = allowedPatterns.some((p) => p.test(filePath));
-  if (isAllowed) return false;
-
-  // Check protected directories (if any configured)
-  if (dirPatterns.length > 0) {
-    const inProtectedDir = dirPatterns.some((p) => p.test(filePath));
-    if (inProtectedDir) {
-      return onlyBlockIfExists ? await fileExists(filePath) : true;
-    }
-  }
-
-  return onlyBlockIfExists ? await fileExists(filePath) : true;
-}
-
-/**
- * Extract file references from a bash command using AST parsing.
- * Falls back to regex extraction on parse failure.
- */
-async function extractBashFileTargets(command: string): Promise<string[]> {
-  try {
-    const { ast } = parse(command);
-    const files: string[] = [];
-
-    walkCommands(ast, (cmd) => {
-      const words = (cmd.words ?? []).map(wordToString);
-      // Skip command name (words[0]), check args for env file references
-      for (let i = 1; i < words.length; i++) {
-        const arg = words[i] as string;
-        if (isEnvLikeReference(arg)) {
-          files.push(arg);
-        }
-      }
-
-      // Also check redirect targets
-      for (const redir of cmd.redirects ?? []) {
-        const target = wordToString(redir.target);
-        if (isEnvLikeReference(target)) {
-          files.push(target);
-        }
-      }
-      return false;
-    });
-
-    // Expand globs
-    const expanded: string[] = [];
-    for (const file of files) {
-      if (hasGlobChars(file)) {
-        const matches = await expandGlob(file);
-        if (matches.length > 0) {
-          expanded.push(...matches);
-        } else {
-          // Expansion returned nothing -- could be fd not found or no matches.
-          // Keep original as-is so pattern matching can still catch it.
-          expanded.push(file);
-        }
-      } else {
-        expanded.push(file);
-      }
-    }
-
-    return expanded;
-  } catch {
-    // Fallback: regex extraction from raw string
-    return extractEnvFilesRegex(command);
-  }
-}
-
-/**
- * Check if a string looks like an env file reference.
- * Matches anything containing ".env" as a path component.
- */
-function isEnvLikeReference(arg: string): boolean {
-  // Must contain ".env" somewhere
-  if (!arg.includes(".env") && !arg.includes(".dev.vars")) return false;
-  // Skip flags
-  if (arg.startsWith("-") && !arg.startsWith("-/") && !arg.startsWith("-."))
-    return false;
-  return true;
-}
-
-/**
- * Fallback regex extraction for env file references in bash commands.
- */
-function extractEnvFilesRegex(command: string): string[] {
-  const files: string[] = [];
-  const envFileRegex =
-    /(?:^|\s|[<>|;&"'`])([^\s<>|;&"'`]*\.env[^\s<>|;&"'`]*)(?:\s|$|[<>|;&"'`])/gi;
-
-  for (const match of command.matchAll(envFileRegex)) {
-    const file = match[1];
-    if (file) files.push(file);
-  }
-
-  return files;
-}
-
-interface ToolProtectionRule {
-  tools: string[];
-  extractTargets: (input: Record<string, unknown>) => Promise<string[]>;
-  shouldBlock: (target: string) => Promise<boolean>;
-  blockMessage: (target: string) => string;
-}
-
-export function setupProtectEnvFilesHook(
-  pi: ExtensionAPI,
-  config: ResolvedConfig,
-) {
-  if (!config.features.protectEnvFiles) return;
-
-  const protectedPatterns = compileFilePatterns(
-    config.envFiles.protectedPatterns,
-  );
-  const allowedPatterns = compileFilePatterns(config.envFiles.allowedPatterns);
-  const dirPatterns = compileFilePatterns(config.envFiles.protectedDirectories);
-
-  const shouldBlock = (target: string) =>
-    isProtectedEnvFile(
-      target,
-      protectedPatterns,
-      allowedPatterns,
-      dirPatterns,
-      config.envFiles.onlyBlockIfExists,
-    );
-
-  const protectionRules: ToolProtectionRule[] = [
-    {
-      tools: config.envFiles.protectedTools.filter((t) =>
-        ["read", "write", "edit", "grep", "find", "ls"].includes(t),
-      ),
-      extractTargets: async (input) => {
-        const path = String(input.file_path ?? input.path ?? "");
-        return path ? [path] : [];
-      },
-      shouldBlock,
-      blockMessage: (target) =>
-        config.envFiles.blockMessage.replace("{file}", target),
-    },
-    {
-      tools: config.envFiles.protectedTools.includes("bash") ? ["bash"] : [],
-      extractTargets: async (input) => {
-        const command = String(input.command ?? "");
-        return extractBashFileTargets(command);
-      },
-      shouldBlock,
-      blockMessage: (target) =>
-        `Command references protected file ${target}. ` +
-        config.envFiles.blockMessage.replace("{file}", target),
-    },
-  ];
-
-  // Build lookup: tool name -> rule
-  const rulesByTool = new Map<string, ToolProtectionRule>();
-  for (const rule of protectionRules) {
-    for (const tool of rule.tools) {
-      rulesByTool.set(tool, rule);
-    }
-  }
-
-  pi.on("tool_call", async (event, ctx) => {
-    const rule = rulesByTool.get(event.toolName);
-    if (!rule) return;
-
-    const targets = await rule.extractTargets(event.input);
-
-    for (const target of targets) {
-      if (await rule.shouldBlock(target)) {
-        ctx.ui.notify(`Blocked access to protected file: ${target}`, "warning");
-
-        const reason = rule.blockMessage(target);
-
-        emitBlocked(pi, {
-          feature: "protectEnvFiles",
-          toolName: event.toolName,
-          input: event.input,
-          reason,
-        });
-
-        return { block: true, reason };
-      }
-    }
-    return;
-  });
-}