@imolko/ultra-agent 0.1.0-beta

package/pi/extensions/qa-guardrail/config.ts

@@ -0,0 +1,189 @@
+/**
+ * Loads, parses, and validates `.pi/qa-guardrail.json`.
+ *
+ * The config is selection-only: it declares which whitelisted adapter covers
+ * which files. It never declares binaries, args, or formatters (cerco).
+ *
+ * Contract: absent or invalid config → a warning and the gate off. Never a
+ * crash, never silence.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { QaGuardrailConfig, ToolEntry } from "./types.js";
+
+/** Config file path relative to the project root. */
+export const CONFIG_FILE = ".pi/qa-guardrail.json";
+
+export type ParseResult =
+  | { ok: true; config: QaGuardrailConfig }
+  | { ok: false; errors: string[] };
+
+export type ConfigLoadResult =
+  | { ok: true; config: QaGuardrailConfig }
+  | { ok: false; reason: string };
+
+/** Small I/O surface so tests can inject in-memory fakes. */
+export interface ConfigIO {
+  exists(path: string): boolean;
+  read(path: string): string;
+}
+
+export const defaultConfigIO: ConfigIO = {
+  exists: (p) => existsSync(p),
+  read: (p) => readFileSync(p, "utf8"),
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Validate one tool entry. Returns the normalized entry and any errors for it.
+ */
+function parseToolEntry(value: unknown, index: number): { entry: ToolEntry | null; errors: string[] } {
+  const errors: string[] = [];
+  const where = `tools[${index}]`;
+
+  if (!isRecord(value)) {
+    return { entry: null, errors: [`${where}: debe ser un objeto`] };
+  }
+
+  const entry: ToolEntry = {
+    id: "",
+    include: [],
+    exclude: [],
+    rootMarkers: [],
+  };
+
+  const id = value.id;
+  if (typeof id !== "string" || id.trim() === "") {
+    errors.push(`${where}.id: debe ser un string no vacío`);
+  } else {
+    entry.id = id;
+  }
+
+  for (const field of ["include", "exclude", "rootMarkers"] as const) {
+    const raw = value[field];
+    if (raw === undefined) continue;
+    if (!Array.isArray(raw) || raw.some((item) => typeof item !== "string")) {
+      errors.push(`${where}.${field}: debe ser un array de strings`);
+    } else {
+      entry[field] = raw as string[];
+    }
+  }
+
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
+    errors.push(`${where}.enabled: debe ser un boolean`);
+  } else if (typeof value.enabled === "boolean") {
+    entry.enabled = value.enabled;
+  }
+
+  // Fail-fast: un campo desconocido (bin/args/formatter, o un typo como
+  // «includes») no se ignora en silencio; se rechaza el config entero.
+  const allowedFields = new Set(["id", "include", "exclude", "rootMarkers", "enabled"]);
+  for (const field of Object.keys(value)) {
+    if (!allowedFields.has(field)) {
+      errors.push(
+        `${where}.${field}: campo no permitido (la configuración es de solo selección: id, include, exclude, rootMarkers, enabled)`,
+      );
+    }
+  }
+
+  return errors.length === 0 ? { entry, errors } : { entry: null, errors };
+}
+
+/**
+ * Parse and validate the raw config text. Pure: no filesystem access.
+ */
+export function parseConfig(raw: string): ParseResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (err) {
+    return { ok: false, errors: [`JSON inválido: ${errorMessage(err)}`] };
+  }
+
+  if (!isRecord(value)) {
+    return { ok: false, errors: ["La raíz del config debe ser un objeto"] };
+  }
+
+  if (!Array.isArray(value.tools)) {
+    return { ok: false, errors: ["tools: debe ser un array"] };
+  }
+
+  const config: QaGuardrailConfig = { tools: [] };
+  const errors: string[] = [];
+
+  for (const field of Object.keys(value)) {
+    if (field !== "tools") {
+      errors.push(`campo no permitido en la raíz: ${field} (solo se admite «tools»)`);
+    }
+  }
+
+  for (let i = 0; i < value.tools.length; i++) {
+    const { entry, errors: entryErrors } = parseToolEntry(value.tools[i], i);
+    if (entry) {
+      config.tools.push(entry);
+    } else {
+      errors.push(...entryErrors);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+  return { ok: true, config };
+}
+
+/**
+ * Load the config from `cwd`. Absent or invalid → `{ ok: false, reason }`.
+ */
+export function loadConfig(cwd: string, io: ConfigIO = defaultConfigIO): ConfigLoadResult {
+  const path = join(cwd, CONFIG_FILE);
+
+  if (!io.exists(path)) {
+    return { ok: false, reason: `Config ausente: ${path}` };
+  }
+
+  let raw: string;
+  try {
+    raw = io.read(path);
+  } catch (err) {
+    return { ok: false, reason: `No se pudo leer ${path}: ${errorMessage(err)}` };
+  }
+
+  const parsed = parseConfig(raw);
+  if (!parsed.ok) {
+    return { ok: false, reason: `Config inválido (${path}): ${parsed.errors.join("; ")}` };
+  }
+  return { ok: true, config: parsed.config };
+}
+
+/**
+ * Walk up from `startDir` looking for the first directory that contains one of
+ * `markers`. Returns `null` when no ancestor matches (caller falls back to cwd).
+ */
+export function findProjectRoot(
+  startDir: string,
+  markers: string[],
+  exists: (p: string) => boolean = existsSync,
+): string | null {
+  let dir = resolve(startDir);
+  for (;;) {
+    for (const marker of markers) {
+      if (exists(join(dir, marker))) {
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}

package/pi/extensions/qa-guardrail/delta.ts

@@ -0,0 +1,52 @@
+/**
+ * Delta-scoped feedback: `current − baseline`.
+ *
+ * The baseline is the set of violations the file had «as the agent found it»
+ * (see baseline.ts). The delta is the set of violations *introduced* by the
+ * agent's edit: everything in `current` that is not already accounted for in
+ * `baseline`. Removals are never reported — the agent only answers for what it
+ * adds, never for inherited violations it happened to fix.
+ */
+
+import type { Violation } from "./types.js";
+
+/**
+ * Canonical identity of a violation, used for set difference.
+ *
+ * A violation is identified by (rule, location). Message and severity are
+ * deliberately excluded: making an already-non-conforming function worse keeps
+ * the same location and is the documented structural blind spot of delta
+ * scoping (A-049). `parse-error` stands in for a missing rule id.
+ */
+function violationKey(v: Violation): string {
+  const rule = v.ruleId ?? "parse-error";
+  return `${rule}\u0000${v.line}\u0000${v.column}`;
+}
+
+/**
+ * Compute the introduced violations as a multiset difference: each baseline
+ * violation cancels one matching current violation. Order follows `current`.
+ */
+export function computeDelta(current: Violation[], baseline: Violation[]): Violation[] {
+  if (baseline.length === 0) {
+    return [...current];
+  }
+
+  const remaining = new Map<string, number>();
+  for (const item of baseline) {
+    const key = violationKey(item);
+    remaining.set(key, (remaining.get(key) ?? 0) + 1);
+  }
+
+  const delta: Violation[] = [];
+  for (const item of current) {
+    const key = violationKey(item);
+    const count = remaining.get(key) ?? 0;
+    if (count > 0) {
+      remaining.set(key, count - 1);
+    } else {
+      delta.push(item);
+    }
+  }
+  return delta;
+}

package/pi/extensions/qa-guardrail/feedback.ts

@@ -0,0 +1,26 @@
+/**
+ * Compact, agent-facing feedback summary appended to a tool_result.
+ *
+ * The summary is the only thing the agent sees after an edit, so it must be
+ * short and scannable: one header line + one line per violation.
+ */
+
+import type { Violation } from "./types.js";
+
+/**
+ * Build the compact summary, or `null` when there is nothing to report.
+ */
+export function buildSummary(file: string, violations: Violation[]): string | null {
+  if (violations.length === 0) {
+    return null;
+  }
+
+  const label = violations.length === 1 ? "violación" : "violaciones";
+  const header = `qa-guardrail: ${violations.length} ${label} en ${file}`;
+  const lines = violations.map((v) => {
+    const rule = v.ruleId ?? "parse-error";
+    const location = `${v.line}:${v.column}`;
+    return `- ${rule} (${location}) ${v.message}`;
+  });
+  return [header, ...lines].join("\n");
+}

package/pi/extensions/qa-guardrail/index.ts

@@ -0,0 +1,311 @@
+/**
+ * qa-guardrail extension — delta-scoping (#318) + corte en N (#319) + cerco (#320)
+ * + barrido completo `/qa-guardrail check` (#321).
+ *
+ * Wires config → adapter → tool_call/tool_result:
+ *
+ * - On `tool_call` of `write`/`edit`, the baseline for the file is frozen
+ *   (linted before the first edit; empty for new files), and files that hit
+ *   the N-failure cutoff are blocked.
+ * - On `tool_result` of `write`/`edit`, the file is linted again and only the
+ *   delta (`current − baseline`) is appended as a compact summary, so the agent
+ *   sees — and only answers for — the violations it introduces. Consecutive
+ *   delta-fails are counted; the Nth failure blocks the file and appends a
+ *   STOP report.
+ *
+ * The cerco (protected paths + eslint-disable detection) runs on `tool_call`
+ * before the baseline and blocks protected paths and new directives (#320).
+ *
+ * `/qa-guardrail check` runs a full, non-blocking sweep: it lists all matching
+ * files' violations and inherited directives (#321).
+ */
+
+import { resolve } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolCallEvent,
+  ToolCallEventResult,
+  ToolResultEvent,
+  ToolResultEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { findProjectRoot, loadConfig, type ConfigLoadResult } from "./config.js";
+import { buildSummary } from "./feedback.js";
+import { selectAdapterId } from "./selection.js";
+import { getAdapter, registerAdapter, setUnknownIdWarn } from "./adapters/registry.js";
+import { createEslintAdapter } from "./adapters/eslint.js";
+import { createBaselineStore, type BaselineStore } from "./baseline.js";
+import { computeDelta } from "./delta.js";
+import { createNStopStore, type NStopStore } from "./nstop.js";
+import { checkCerco } from "./cerco.js";
+import { defaultCheckDeps, formatCheckReport, runCheck } from "./check.js";
+import type { LintAdapter, QaGuardrailConfig, Violation } from "./types.js";
+
+export interface GuardrailDeps {
+  loadConfig: (cwd: string) => ConfigLoadResult;
+  selectAdapterId: (file: string, config: QaGuardrailConfig, cwd: string) => string | undefined;
+  getAdapter: (id: string) => LintAdapter | undefined;
+  findRoot: (cwd: string, markers: string[]) => string | null;
+  buildSummary: (file: string, violations: Violation[]) => string | null;
+  warn: (message: string) => void;
+  baseline: BaselineStore;
+  nstop: NStopStore;
+  computeDelta: (current: Violation[], baseline: Violation[]) => Violation[];
+  resolvePath: (cwd: string, file: string) => string;
+}
+
+const defaultDeps: Omit<GuardrailDeps, "baseline" | "nstop"> = {
+  loadConfig,
+  selectAdapterId,
+  getAdapter,
+  findRoot: (cwd, markers) => findProjectRoot(cwd, markers),
+  buildSummary,
+  warn: (message) => console.warn(message),
+  computeDelta,
+  resolvePath: (cwd, file) => resolve(cwd, file),
+};
+
+export interface Guardrail {
+  onToolCall: (
+    event: ToolCallEvent,
+    ctx: ExtensionContext,
+  ) => Promise<ToolCallEventResult | undefined>;
+  onToolResult: (
+    event: ToolResultEvent,
+    ctx: ExtensionContext,
+  ) => Promise<ToolResultEventResult | undefined>;
+}
+
+interface LintTarget {
+  adapter: LintAdapter;
+  root: string;
+}
+
+export function createGuardrail(deps: Partial<GuardrailDeps> = {}): Guardrail {
+  // One frozen baseline store and one n-stop store per guardrail instance
+  // (= per session).
+  const d: GuardrailDeps = {
+    baseline: createBaselineStore(),
+    nstop: createNStopStore(),
+    ...defaultDeps,
+    ...deps,
+  };
+
+  const configCache = new Map<string, ConfigLoadResult>();
+  const warnedKeys = new Set<string>();
+
+  function getConfigResult(cwd: string): ConfigLoadResult {
+    if (!configCache.has(cwd)) {
+      configCache.set(cwd, d.loadConfig(cwd));
+    }
+    return configCache.get(cwd)!;
+  }
+
+  function warnOnce(key: string, message: string, ctx: ExtensionContext): void {
+    if (warnedKeys.has(key)) {
+      return;
+    }
+    warnedKeys.add(key);
+    d.warn(message);
+    ctx.ui?.notify?.(message, "warning");
+  }
+
+  function filePath(eventInput: unknown): string | undefined {
+    const file = (eventInput as { path?: unknown }).path;
+    if (typeof file !== "string" || file.trim() === "") {
+      return undefined;
+    }
+    return file;
+  }
+
+  function resolveTarget(file: string, ctx: ExtensionContext): LintTarget | undefined {
+    const result = getConfigResult(ctx.cwd);
+    if (!result.ok) {
+      warnOnce(`config:${ctx.cwd}`, `qa-guardrail: gate off — ${result.reason}`, ctx);
+      return undefined;
+    }
+    const config = result.config;
+
+    const adapterId = d.selectAdapterId(file, config, ctx.cwd);
+    if (!adapterId) {
+      return undefined;
+    }
+
+    // Unknown ids are rejected by the registry (which warns); nothing to lint.
+    const adapter = d.getAdapter(adapterId);
+    if (!adapter) {
+      return undefined;
+    }
+
+    const entry = config.tools.find((tool) => tool.id === adapterId);
+    const root = d.findRoot(ctx.cwd, entry?.rootMarkers ?? []) ?? ctx.cwd;
+    return { adapter, root };
+  }
+
+  type LintOutcome = { ok: true; violations: Violation[] } | { ok: false };
+
+  async function lintFile(
+    target: LintTarget,
+    file: string,
+    ctx: ExtensionContext,
+  ): Promise<LintOutcome> {
+    try {
+      const violations = await target.adapter.lint(file, { root: target.root, cwd: ctx.cwd });
+      return { ok: true, violations };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      warnOnce(`lint:${file}`, `qa-guardrail: no se pudo lintear ${file} — ${message}`, ctx);
+      return { ok: false };
+    }
+  }
+
+  async function onToolCall(
+    event: ToolCallEvent,
+    ctx: ExtensionContext,
+  ): Promise<ToolCallEventResult | undefined> {
+    if (event.toolName !== "write" && event.toolName !== "edit") {
+      return undefined;
+    }
+    const file = filePath(event.input);
+    if (!file) {
+      return undefined;
+    }
+
+    const cerco = checkCerco(event.toolName, event.input, file, ctx.cwd);
+    if (cerco.blocked) {
+      return { block: true, reason: cerco.reason };
+    }
+
+    const absolutePath = d.resolvePath(ctx.cwd, file);
+    if (d.nstop.isBlocked(absolutePath)) {
+      return {
+        block: true,
+        reason: `qa-guardrail: ${file} está bloqueado tras el corte en N. Desbloquéalo con /qa-guardrail reset ${file}`,
+      };
+    }
+
+    const target = resolveTarget(file, ctx);
+    if (!target) {
+      return undefined;
+    }
+
+    await d.baseline.capture(absolutePath, async () => {
+      const outcome = await lintFile(target, file, ctx);
+      return outcome.ok ? outcome.violations : [];
+    });
+    return undefined;
+  }
+
+  async function onToolResult(
+    event: ToolResultEvent,
+    ctx: ExtensionContext,
+  ): Promise<ToolResultEventResult | undefined> {
+    if (event.toolName !== "write" && event.toolName !== "edit") {
+      return undefined;
+    }
+    if (event.isError) {
+      return undefined;
+    }
+
+    const file = filePath(event.input);
+    if (!file) {
+      return undefined;
+    }
+
+    const target = resolveTarget(file, ctx);
+    if (!target) {
+      return undefined;
+    }
+
+    const linted = await lintFile(target, file, ctx);
+    if (!linted.ok) {
+      return undefined;
+    }
+    const violations = linted.violations;
+
+    const absolutePath = d.resolvePath(ctx.cwd, file);
+    const baseline = d.baseline.get(absolutePath) ?? [];
+    const delta = d.computeDelta(violations, baseline);
+
+    // Delta limpio: el agente no introdujo violaciones → reinicia el contador.
+    if (delta.length === 0) {
+      d.nstop.recordClean(absolutePath);
+      return undefined;
+    }
+
+    const outcome = d.nstop.recordFailure(absolutePath);
+
+    const summary = d.buildSummary(file, delta);
+    const appended: Array<{ type: "text"; text: string }> = [];
+    if (summary) {
+      appended.push({ type: "text", text: summary });
+    }
+
+    if (outcome.blocked) {
+      const stop = `qa-guardrail: STOP — ${outcome.failures} deltas-fallo consecutivos en ${file}; reportar a la persona.`;
+      appended.push({ type: "text", text: stop });
+      ctx.ui?.notify?.(
+        `qa-guardrail: ${file} bloqueado tras ${outcome.failures} deltas-fallo consecutivos — reportar a la persona.`,
+        "error",
+      );
+    }
+
+    return {
+      content: [...event.content, ...appended],
+    };
+  }
+
+  return { onToolCall, onToolResult };
+}
+
+export default function (pi: ExtensionAPI) {
+  registerAdapter(createEslintAdapter());
+  setUnknownIdWarn((message) => console.warn(message));
+
+  const nstop = createNStopStore();
+  const { onToolCall, onToolResult } = createGuardrail({ nstop });
+  pi.on("tool_call", onToolCall);
+  pi.on("tool_result", onToolResult);
+
+  pi.registerCommand("qa-guardrail", {
+    description:
+      "qa-guardrail: reset <archivo> desbloquea un archivo; check barre violaciones y directivas heredadas",
+    handler: async (args, ctx) => {
+      const normalized = args.trim();
+
+      const resetMatch = normalized.match(/^reset\s+(\S+)\s*$/);
+      if (resetMatch) {
+        const file = resetMatch[1];
+        const absolutePath = resolve(ctx.cwd, file);
+        nstop.reset(absolutePath);
+        ctx.ui?.notify?.(`qa-guardrail: ${file} desbloqueado`, "info");
+        return;
+      }
+
+      if (normalized === "check") {
+        const report = await runCheck(ctx.cwd, {
+          ...defaultCheckDeps,
+          warn: (message) => ctx.ui?.notify?.(message, "warning"),
+        });
+        const text = formatCheckReport(ctx.cwd, report);
+        ctx.ui?.notify?.(
+          report.ok
+            ? `qa-guardrail: check — ${report.findings.length} hallazgos`
+            : "qa-guardrail: check no disponible",
+          report.ok ? "info" : "warning",
+        );
+        pi.sendMessage({
+          customType: "qa-guardrail-check",
+          content: text,
+          display: true,
+        });
+        return;
+      }
+
+      ctx.ui?.notify?.(
+        "qa-guardrail: uso — /qa-guardrail reset <archivo> | /qa-guardrail check",
+        "warning",
+      );
+    },
+  });
+}

package/pi/extensions/qa-guardrail/nstop.ts

@@ -0,0 +1,82 @@
+/**
+ * N-failure cutoff for qa-guardrail (corte en N).
+ *
+ * Prevents infinite correction loops: every *consecutive* delta-fail on the
+ * same file increments a counter. A clean delta (no introduced violations)
+ * resets it. When the counter reaches `N`, the file is added to a blocklist
+ * that blocks future `write`/`edit` calls until a human runs
+ * `/qa-guardrail reset <archivo>`.
+ *
+ * The counter and blocklist are keyed by the *absolute* file path, matching
+ * the path used by `index.ts` (and the rest of the extension) for baseline and
+ * linting. Pure module: no filesystem access.
+ */
+
+/** Hard cutoff. Fixed by A-045/A-049: three consecutive delta-fails. */
+export const DEFAULT_MAX_FAILURES = 3;
+
+/** Result of recording a failing delta. */
+export interface NStopResult {
+  /** Consecutive delta-fail count for the file *after* this failure. */
+  failures: number;
+  /** True when this failure reached the cutoff and the file is now blocked. */
+  blocked: boolean;
+}
+
+export interface NStopStore {
+  /**
+   * Record one delta-fail for `file` and return the new count plus whether
+   * the cutoff was just reached (which adds the file to the blocklist).
+   */
+  recordFailure(file: string): NStopResult;
+  /** Record a clean delta: resets the consecutive-fail counter to zero. */
+  recordClean(file: string): void;
+  /** Whether `file` is in the blocklist (write/edit must be blocked). */
+  isBlocked(file: string): boolean;
+  /** Current consecutive delta-fail count for `file` (0 if none). */
+  failures(file: string): number;
+  /** Human unblock: remove from blocklist and reset the counter. */
+  reset(file: string): void;
+  /** Forget every counter and blocklist entry (tests / teardown). */
+  clear(): void;
+}
+
+export function createNStopStore(maxFailures: number = DEFAULT_MAX_FAILURES): NStopStore {
+  const cutoff = Math.max(1, Math.floor(maxFailures));
+  const counters = new Map<string, number>();
+  const blocklist = new Set<string>();
+
+  return {
+    recordFailure(file) {
+      const next = (counters.get(file) ?? 0) + 1;
+      counters.set(file, next);
+      const blocked = next >= cutoff;
+      if (blocked) {
+        blocklist.add(file);
+      }
+      return { failures: next, blocked };
+    },
+
+    recordClean(file) {
+      counters.set(file, 0);
+    },
+
+    isBlocked(file) {
+      return blocklist.has(file);
+    },
+
+    failures(file) {
+      return counters.get(file) ?? 0;
+    },
+
+    reset(file) {
+      counters.delete(file);
+      blocklist.delete(file);
+    },
+
+    clear() {
+      counters.clear();
+      blocklist.clear();
+    },
+  };
+}

package/pi/extensions/qa-guardrail/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "qa-guardrail-extension",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  }
+}