@aliou/pi-guardrails 0.11.2 → 0.12.0

package/src/lib/model-resolver.ts

@@ -1,47 +0,0 @@
-/**
- * Model resolution helper for subagents.
- *
- * Resolves a model by provider + ID from the model registry.
- */
-
-import type { Model } from "@mariozechner/pi-ai";
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-
-/**
- * Find a model by provider and ID.
- *
- * @param provider - Provider name (e.g., "openrouter", "anthropic", "openai-codex")
- * @param modelId - Model ID (e.g., "anthropic/claude-haiku-4.5")
- * @param ctx - Extension context with modelRegistry
- * @returns The resolved model
- * @throws Error if model not found or API key not configured
- */
-export function resolveModel(
-  provider: string,
-  modelId: string,
-  ctx: ExtensionContext,
-  // biome-ignore lint/suspicious/noExplicitAny: Model type requires any for generic API
-): Model<any> {
-  const available = ctx.modelRegistry.getAvailable();
-  const model = available.find(
-    (m) => m.id === modelId && m.provider === provider,
-  );
-
-  if (model) {
-    return model;
-  }
-
-  // Check if the model exists but the API key is missing
-  const all = ctx.modelRegistry.getAll();
-  const existsWithoutKey = all.some(
-    (m) => m.id === modelId && m.provider === provider,
-  );
-
-  if (existsWithoutKey) {
-    throw new Error(
-      `Model "${modelId}" exists on ${provider} but no valid API key is configured.`,
-    );
-  }
-
-  throw new Error(`Model "${modelId}" not found on provider "${provider}".`);
-}

package/src/lib/timing.ts

@@ -1,42 +0,0 @@
-/**
- * Shared timing utilities for tool and subagent execution.
- */
-
-/** Minimal shape that supports timing fields. */
-export interface TimedExecution {
-  startedAt?: number;
-  endedAt?: number;
-  durationMs?: number;
-}
-
-/** Mark execution start time (epoch ms). */
-export function markExecutionStart<T extends TimedExecution>(
-  target: T,
-  startedAt = Date.now(),
-): T {
-  target.startedAt = startedAt;
-  return target;
-}
-
-/** Mark execution end time and compute duration (epoch ms / ms). */
-export function markExecutionEnd<T extends TimedExecution>(
-  target: T,
-  endedAt = Date.now(),
-): T {
-  target.endedAt = endedAt;
-  if (target.startedAt !== undefined) {
-    target.durationMs = Math.max(0, endedAt - target.startedAt);
-  }
-  return target;
-}
-
-/** Simple wall-clock timer for a full operation (e.g., subagent call). */
-export function createExecutionTimer(startedAt = Date.now()): {
-  startedAt: number;
-  getDurationMs: (endedAt?: number) => number;
-} {
-  return {
-    startedAt,
-    getDurationMs: (endedAt = Date.now()) => Math.max(0, endedAt - startedAt),
-  };
-}

package/src/lib/types.ts

@@ -1,115 +0,0 @@
-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

@@ -1,32 +0,0 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-
-export const GUARDRAILS_BLOCKED_EVENT = "guardrails:blocked";
-export const GUARDRAILS_DANGEROUS_EVENT = "guardrails:dangerous";
-
-export interface GuardrailsBlockedEvent {
-  feature: "policies" | "permissionGate" | "pathAccess";
-  toolName: string;
-  input: Record<string, unknown>;
-  reason: string;
-  userDenied?: boolean;
-}
-
-export interface GuardrailsDangerousEvent {
-  command: string;
-  description: string;
-  pattern: string;
-}
-
-export function emitBlocked(
-  pi: ExtensionAPI,
-  event: GuardrailsBlockedEvent,
-): void {
-  pi.events.emit(GUARDRAILS_BLOCKED_EVENT, event);
-}
-
-export function emitDangerous(
-  pi: ExtensionAPI,
-  event: GuardrailsDangerousEvent,
-): void {
-  pi.events.emit(GUARDRAILS_DANGEROUS_EVENT, event);
-}

package/src/utils/migration.test.ts

@@ -1,58 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { GuardrailsConfig } from "../config";
-import {
-  migrateAllowedPaths,
-  needsAllowedPathsMigration,
-  normalizeAllowedPaths,
-} from "./migration";
-
-describe("allowedPaths migration", () => {
-  it("normalizes strings and legacy pattern objects", () => {
-    expect(
-      normalizeAllowedPaths([
-        "/dev/null",
-        { pattern: "~/Downloads/" },
-        { pattern: " /tmp/file " },
-        { pattern: "" },
-        { regex: true },
-        42,
-        null,
-        "/dev/null",
-      ]),
-    ).toEqual(["/dev/null", "~/Downloads/", "/tmp/file"]);
-  });
-
-  it("detects legacy object-shaped allowed paths", () => {
-    const config = {
-      pathAccess: {
-        allowedPaths: [{ pattern: "/dev/null" }],
-      },
-    } as unknown as GuardrailsConfig;
-
-    expect(needsAllowedPathsMigration(config)).toBe(true);
-  });
-
-  it("does not migrate valid string allowed paths", () => {
-    const config: GuardrailsConfig = {
-      pathAccess: {
-        allowedPaths: ["/dev/null"],
-      },
-    };
-
-    expect(needsAllowedPathsMigration(config)).toBe(false);
-  });
-
-  it("converts legacy object-shaped allowed paths to strings", () => {
-    const config = {
-      pathAccess: {
-        mode: "block",
-        allowedPaths: [{ pattern: "/dev/null" }, "~/Downloads/"],
-      },
-    } as unknown as GuardrailsConfig;
-
-    expect(migrateAllowedPaths(config).pathAccess?.allowedPaths).toEqual([
-      "/dev/null",
-      "~/Downloads/",
-    ]);
-  });
-});

package/src/utils/migration.ts

@@ -1,340 +0,0 @@
-/**
- * Config migration from v0 (no version field) to current format.
- *
- * v0 configs store patterns as plain strings (regex). The migration
- * converts them to PatternConfig objects with `regex: true` to preserve
- * existing behavior.
- */
-
-import { copyFile, stat } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import type {
-  DangerousPattern,
-  GuardrailsConfig,
-  PatternConfig,
-} from "../config";
-import { pendingWarnings } from "./warnings";
-
-/**
- * Config schema version.
- *
- * Keep this independent from package.json version.
- * Bump only when config schema/default migration markers change.
- */
-export const CURRENT_VERSION = "0.9.0-20260327";
-
-/**
- * Check if a config needs migration (no version field = v0).
- */
-export function needsMigration(config: GuardrailsConfig): boolean {
-  return config.version === undefined;
-}
-
-/**
- * Migrate a v0 config to the current format.
- * All string patterns become `{ pattern, regex: true }` to preserve behavior.
- */
-export function migrateV0(config: GuardrailsConfig): GuardrailsConfig {
-  const migrated = structuredClone(config);
-
-  // Migrate envFiles patterns
-  if (migrated.envFiles) {
-    if (migrated.envFiles.protectedPatterns) {
-      migrated.envFiles.protectedPatterns = migrateStringArray(
-        migrated.envFiles.protectedPatterns,
-      );
-    }
-    if (migrated.envFiles.allowedPatterns) {
-      migrated.envFiles.allowedPatterns = migrateStringArray(
-        migrated.envFiles.allowedPatterns,
-      );
-    }
-    if (migrated.envFiles.protectedDirectories) {
-      migrated.envFiles.protectedDirectories = migrateStringArray(
-        migrated.envFiles.protectedDirectories,
-      );
-    }
-  }
-
-  // Migrate permissionGate patterns
-  if (migrated.permissionGate) {
-    if (migrated.permissionGate.patterns) {
-      migrated.permissionGate.patterns = migrateDangerousPatterns(
-        migrated.permissionGate.patterns,
-      );
-    }
-    if (migrated.permissionGate.customPatterns) {
-      migrated.permissionGate.customPatterns = migrateDangerousPatterns(
-        migrated.permissionGate.customPatterns,
-      );
-    }
-    if (migrated.permissionGate.allowedPatterns) {
-      migrated.permissionGate.allowedPatterns = migrateStringArray(
-        migrated.permissionGate.allowedPatterns,
-      );
-    }
-    if (migrated.permissionGate.autoDenyPatterns) {
-      migrated.permissionGate.autoDenyPatterns = migrateStringArray(
-        migrated.permissionGate.autoDenyPatterns,
-      );
-    }
-  }
-
-  migrated.version = CURRENT_VERSION;
-  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;
-}
-
-/**
- * Check if config needs applyBuiltinDefaults bridge migration.
- * This runs only for existing config files loaded by ConfigLoader.
- */
-export function needsApplyBuiltinDefaultsMigration(
-  config: GuardrailsConfig,
-): boolean {
-  return config.applyBuiltinDefaults === undefined;
-}
-
-/**
- * Bridge migration for defaults deprecation.
- * Existing config files get applyBuiltinDefaults=true to preserve behavior.
- */
-export function migrateApplyBuiltinDefaults(
-  config: GuardrailsConfig,
-): GuardrailsConfig {
-  const migrated = structuredClone(config);
-  migrated.applyBuiltinDefaults = true;
-  migrated.version = CURRENT_VERSION;
-
-  pendingWarnings.push(
-    "Guardrails config was migrated. `applyBuiltinDefaults` was set to `true` to preserve current behavior.",
-  );
-
-  return migrated;
-}
-
-export function needsOnboardingDoneMigration(
-  config: GuardrailsConfig,
-): boolean {
-  return (
-    config.onboarding?.completed === undefined &&
-    config.applyBuiltinDefaults !== undefined
-  );
-}
-
-export function migrateMarkOnboardingDone(
-  config: GuardrailsConfig,
-): GuardrailsConfig {
-  const migrated = structuredClone(config);
-  pendingWarnings.push(
-    "Guardrails config was migrated. Existing setup marked as onboarding-complete.",
-  );
-  migrated.onboarding = {
-    ...(migrated.onboarding ?? {}),
-    completed: true,
-    completedAt: migrated.onboarding?.completedAt ?? new Date().toISOString(),
-    version: migrated.onboarding?.version ?? CURRENT_VERSION,
-  };
-  migrated.version = CURRENT_VERSION;
-  return migrated;
-}
-
-/**
- * Migrate allowedPaths entries accidentally written as PatternConfig objects.
- */
-export function needsAllowedPathsMigration(config: GuardrailsConfig): boolean {
-  const raw = config as Record<string, unknown>;
-  const pathAccess = raw.pathAccess as Record<string, unknown> | undefined;
-  if (!Array.isArray(pathAccess?.allowedPaths)) return false;
-  return pathAccess.allowedPaths.some((item) => typeof item !== "string");
-}
-
-export function normalizeAllowedPaths(items: unknown): string[] {
-  if (!Array.isArray(items)) return [];
-
-  const paths = new Set<string>();
-  for (const item of items) {
-    let path: string | null = null;
-    if (typeof item === "string") {
-      path = item;
-    } else if (typeof item === "object" && item !== null) {
-      const pattern = (item as Record<string, unknown>).pattern;
-      if (typeof pattern === "string") path = pattern;
-    }
-
-    const normalized = path?.trim();
-    if (normalized) paths.add(normalized);
-  }
-
-  return [...paths];
-}
-
-export function migrateAllowedPaths(
-  config: GuardrailsConfig,
-): GuardrailsConfig {
-  const migrated = structuredClone(config) as Record<string, unknown>;
-  const pathAccess = migrated.pathAccess as Record<string, unknown> | undefined;
-  if (!pathAccess) return migrated as GuardrailsConfig;
-
-  pathAccess.allowedPaths = normalizeAllowedPaths(pathAccess.allowedPaths);
-  migrated.version = CURRENT_VERSION;
-  pendingWarnings.push(
-    "[guardrails] pathAccess.allowedPaths was migrated from pattern objects to path strings.",
-  );
-  return migrated as GuardrailsConfig;
-}
-
-/**
- * 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).
- */
-function migrateStringArray(
-  items: (string | PatternConfig)[],
-): PatternConfig[] {
-  return items.map((item) => {
-    if (typeof item === "string") {
-      return { pattern: item, regex: true };
-    }
-    // Already a PatternConfig, ensure regex is set
-    if (item.regex === undefined) {
-      return { ...item, regex: true };
-    }
-    return item;
-  });
-}
-
-/**
- * Migrate dangerous pattern arrays. Handles both legacy
- * `{ pattern: string, description: string }` and already-migrated formats.
- */
-function migrateDangerousPatterns(
-  items: (DangerousPattern | { pattern: string; description: string })[],
-): DangerousPattern[] {
-  return items.map((item) => {
-    if ("regex" in item && item.regex !== undefined) {
-      return item as DangerousPattern;
-    }
-    return { ...item, regex: true };
-  });
-}
-
-/**
- * Back up a config file before migration.
- * Creates `<name>.v0.json` in the same directory.
- * Skips if backup already exists.
- */
-export async function backupConfig(configPath: string): Promise<void> {
-  const dir = dirname(configPath);
-  const basename = configPath.split("/").pop() ?? "guardrails.json";
-  const backupName = basename.replace(".json", ".v0.json");
-  const backupPath = resolve(dir, backupName);
-
-  try {
-    await stat(backupPath);
-    // Backup already exists, skip
-  } catch {
-    try {
-      await copyFile(configPath, backupPath);
-    } catch (err) {
-      pendingWarnings.push(`guardrails: could not back up config: ${err}`);
-    }
-  }
-}

package/src/utils/warnings.ts

@@ -1,7 +0,0 @@
-/**
- * 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[] = [];