pi-harness-runtime 1.1.150 → 1.1.152

package/packages/agent-policy/src/policy-renderer.ts

@@ -0,0 +1,362 @@
+/**
+ * PolicyRenderer - Renders compact system contract for agent injection.
+ *
+ * Responsibilities:
+ * - Render a compact, deterministic contract for before_agent_start injection
+ * - Render full rule text for the harness_rules tool
+ * - Render policy status for display
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import type { PolicyManifest, PolicySection, HarnessRulesOutput, MinimaxFindingEnvelope } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// System Contract Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the compact mandatory contract for system prompt injection.
+ */
+export function renderSystemContract(manifest: PolicyManifest): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`PI-HARNESS POLICY revision=${manifest.revision} coverage=${manifest.coverage}`);
+  lines.push("");
+
+  // Mandatory rules
+  lines.push("Mandatory:");
+  lines.push("- Read and follow the active harness and scoped project rules.");
+  lines.push("- Before mutation, call harness_rules when the current revision is not loaded.");
+  lines.push("- Treat [BLOCKING] code findings as completion gates.");
+  lines.push("- Treat [DEGRADED] as incomplete evidence, never as clean.");
+  lines.push("- Re-read a file after the harness reports an automatic mutation.");
+  lines.push("");
+
+  // Tool reference
+  lines.push("Use harness_rules for full text and source attribution.");
+  lines.push("");
+
+  // Trust indicator
+  if (manifest.trust === "untrusted") {
+    lines.push("WARNING: Project is not trusted. Project rules are advisory only.");
+    lines.push("");
+  }
+
+  // Coverage warning
+  if (manifest.coverage !== "complete") {
+    lines.push(`WARNING: Policy coverage is ${manifest.coverage}. Some rules may be missing.`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Rule Section Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse markdown content into sections.
+ */
+export function parseSections(content: string, source: string, scope: string, priority: "mandatory" | "advisory"): PolicySection[] {
+  const sections: PolicySection[] = [];
+  const lines = content.split("\n");
+  
+  let currentSection: {
+    id: string;
+    title: string;
+    content: string[];
+    offset: number;
+  } | null = null;
+
+  let sectionIndex = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineOffset = content.split("\n").slice(0, i).join("\n").length;
+
+    // Check for markdown heading
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      // Save previous section
+      if (currentSection) {
+        sections.push({
+          id: currentSection.id,
+          title: currentSection.title,
+          content: currentSection.content.join("\n").trim(),
+          source,
+          scope,
+          priority,
+          offset: currentSection.offset,
+          truncated: false,
+        });
+      }
+
+      // Start new section
+      const level = headingMatch[1].length;
+      const title = headingMatch[2].trim();
+      currentSection = {
+        id: `section-${sectionIndex++}`,
+        title,
+        content: [],
+        offset: lineOffset,
+      };
+    } else if (currentSection) {
+      currentSection.content.push(line);
+    }
+  }
+
+  // Save last section
+  if (currentSection) {
+    sections.push({
+      id: currentSection.id,
+      title: currentSection.title,
+      content: currentSection.content.join("\n").trim(),
+      source,
+      scope,
+      priority,
+      offset: currentSection.offset,
+      truncated: false,
+    });
+  }
+
+  // If no sections found, create a single section with the whole content
+  if (sections.length === 0) {
+    sections.push({
+      id: "section-0",
+      title: "Full Content",
+      content: content.trim(),
+      source,
+      scope,
+      priority,
+      offset: 0,
+      truncated: false,
+    });
+  }
+
+  return sections;
+}
+
+// ---------------------------------------------------------------------------
+// Full Rules Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render full rules for the harness_rules tool.
+ */
+export function renderFullRules(
+  manifest: PolicyManifest,
+  options: {
+    source?: string;
+    section?: string;
+    maxBytes?: number;
+  } = {}
+): HarnessRulesOutput {
+  const sections: PolicySection[] = [];
+  const maxBytes = options.maxBytes ?? 50 * 1024; // Default 50KB cap
+
+  // Filter sources
+  let sources = manifest.sources;
+  if (options.source) {
+    sources = sources.filter(s => s.path.includes(options.source!));
+  }
+
+  // Parse sections from each source
+  for (const source of sources) {
+    const content = readSourceContent(source.path);
+    if (!content) continue;
+
+    const sourceSections = parseSections(content, source.path, source.scope, source.priority);
+    
+    // Filter by section if requested
+    const filteredSections = options.section
+      ? sourceSections.filter(s => 
+          s.title.toLowerCase().includes(options.section!.toLowerCase()) ||
+          s.id === options.section
+        )
+      : sourceSections;
+
+    sections.push(...filteredSections);
+  }
+
+  // Truncate if needed
+  let totalBytes = 0;
+  let truncated = false;
+  const truncatedSections: PolicySection[] = [];
+
+  for (const section of sections) {
+    const sectionBytes = Buffer.byteLength(section.content, "utf8");
+    
+    if (totalBytes + sectionBytes > maxBytes) {
+      // Check if we can fit a partial section
+      const remainingBytes = maxBytes - totalBytes;
+      if (remainingBytes > 100) {
+        // Fit as much as possible
+        truncatedSections.push({
+          ...section,
+          content: section.content.slice(0, remainingBytes),
+          truncated: true,
+        });
+      }
+      truncated = true;
+      break;
+    }
+    
+    truncatedSections.push(section);
+    totalBytes += sectionBytes;
+  }
+
+  return {
+    sections: truncatedSections,
+  };
+}
+
+/**
+ * Render a manifest summary.
+ */
+export function renderManifestSummary(manifest: PolicyManifest): string {
+  const lines: string[] = [];
+
+  lines.push(`Policy Manifest`);
+  lines.push(`================`);
+  lines.push(`Revision: ${manifest.revision}`);
+  lines.push(`Project: ${manifest.projectRoot}`);
+  lines.push(`Trust: ${manifest.trust}`);
+  lines.push(`Coverage: ${manifest.coverage}`);
+  lines.push(`Loaded: ${new Date(manifest.loadedAt).toISOString()}`);
+  lines.push("");
+  lines.push("Sources:");
+
+  for (const source of manifest.sources) {
+    const scope = source.scope || "(root)";
+    const priority = source.priority;
+    const owner = source.harnessOwned ? "[harness]" : "[project]";
+    lines.push(`  ${owner} ${scope} ${priority} ${source.path}`);
+  }
+
+  if (manifest.loadError) {
+    lines.push("");
+    lines.push(`ERROR: ${manifest.loadError}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Finding Envelope Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a finding envelope for display.
+ */
+export function renderFindingEnvelope(envelope: MinimaxFindingEnvelope): string {
+  const lines: string[] = [];
+
+  // Header with verdict
+  const verdictPrefix = {
+    blocking: "[BLOCKING]",
+    advisory: "[ADVISORY]",
+    clean: "[CLEAN]",
+    degraded: "[DEGRADED]",
+  }[envelope.verdict];
+
+  lines.push(`${verdictPrefix} Code Analysis (${envelope.coverage} coverage, ${envelope.freshness})`);
+  lines.push("");
+
+  // Summary
+  if (envelope.summary) {
+    lines.push(envelope.summary);
+    lines.push("");
+  }
+
+  // Individual findings
+  if (envelope.findings.length > 0) {
+    for (const finding of envelope.findings) {
+      const severity = {
+        error: "ERROR",
+        warning: "WARN",
+        information: "INFO",
+        hint: "HINT",
+      }[finding.severity];
+
+      const location = finding.line ? `${finding.path}:${finding.line}` : finding.path;
+      const blocking = finding.blocking ? " [BLOCKING]" : "";
+
+      lines.push(`${severity} ${location}: ${finding.message}${blocking}`);
+      
+      if (finding.fix) {
+        lines.push(`  Fix: ${finding.fix}`);
+      }
+    }
+    lines.push("");
+  }
+
+  // Next action
+  if (envelope.nextAction) {
+    const actionText = {
+      fix: "Required: fix these issues before reporting completion.",
+      reread: "Required: re-read affected files to get updated analysis.",
+      run_full: "Required: do not report the project clean; run a full analysis.",
+      continue: "No blocking issues found.",
+    }[envelope.nextAction];
+
+    lines.push(actionText);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Create a clean finding envelope.
+ */
+export function createCleanEnvelope(coverage: "delta" | "targeted" | "full" = "full"): MinimaxFindingEnvelope {
+  return {
+    verdict: "clean",
+    coverage,
+    freshness: "fresh",
+    findings: [],
+    nextAction: "continue",
+    summary: "No blocking issues found in code analysis.",
+  };
+}
+
+/**
+ * Create a degraded finding envelope.
+ */
+export function createDegradedEnvelope(
+  reason: string,
+  coverage: "delta" | "targeted" | "full" = "delta"
+): MinimaxFindingEnvelope {
+  return {
+    verdict: "degraded",
+    coverage,
+    freshness: "indeterminate",
+    findings: [],
+    nextAction: "run_full",
+    summary: `Analysis degraded: ${reason}. Do not claim the project is clean.`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read source content from a path.
+ */
+function readSourceContent(path: string): string | null {
+  // Handle file:// URLs
+  const normalizedPath = path.startsWith("file://") 
+    ? path.slice(7) 
+    : path;
+  
+  if (existsSync(normalizedPath)) {
+    try {
+      return readFileSync(normalizedPath, "utf8");
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

package/packages/agent-policy/src/policy-store.ts

@@ -0,0 +1,319 @@
+/**
+ * PolicyStore - Session receipt tracking and validation.
+ *
+ * Responsibilities:
+ * - Record when a policy revision was delivered to a session
+ * - Validate receipts against current manifest
+ * - Invalidate receipts when rules change
+ * - Track delivery method (system_prompt vs tool)
+ */
+
+import type { PolicyManifest, PolicyReceipt } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// PolicyStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Policy store configuration.
+ */
+export interface PolicyStoreConfig {
+  /** Maximum receipts to keep per session (prevents memory leaks) */
+  maxReceiptsPerSession?: number;
+  /** Receipt TTL in milliseconds (default: 24 hours) */
+  receiptTtlMs?: number;
+}
+
+/**
+ * Stores policy receipts and validates delivery.
+ */
+export class PolicyStore {
+  private receipts: Map<string, PolicyReceipt> = new Map();
+  private sessionScopes: Map<string, Set<string>> = new Map();
+  private lastKnownManifests: Map<string, PolicyManifest> = new Map();
+  private config: Required<PolicyStoreConfig>;
+
+  constructor(config: PolicyStoreConfig = {}) {
+    this.config = {
+      maxReceiptsPerSession: config.maxReceiptsPerSession ?? 100,
+      receiptTtlMs: config.receiptTtlMs ?? 24 * 60 * 60 * 1000, // 24 hours
+    };
+  }
+
+  /**
+   * Record a policy delivery for a session.
+   */
+  noteDelivered(
+    sessionId: string,
+    manifest: PolicyManifest,
+    deliveryMethod: "system_prompt" | "tool" = "system_prompt",
+    sectionsDelivered: string[] = ["*"]
+  ): PolicyReceipt {
+    // Invalidate any existing receipt for this session+scope
+    const existingKey = this.getReceiptKey(sessionId, manifest.projectRoot, "");
+    this.receipts.delete(existingKey);
+
+    const receipt: PolicyReceipt = {
+      sessionId,
+      projectRoot: manifest.projectRoot,
+      revision: manifest.revision,
+      scope: this.getScopeFromManifest(manifest),
+      deliveredAt: Date.now(),
+      sectionsDelivered,
+      deliveryMethod,
+    };
+
+    this.receipts.set(existingKey, receipt);
+
+    // Track scope for this session
+    if (!this.sessionScopes.has(sessionId)) {
+      this.sessionScopes.set(sessionId, new Set());
+    }
+    this.sessionScopes.get(sessionId)!.add(manifest.projectRoot);
+
+    // Store manifest for later validation
+    this.lastKnownManifests.set(existingKey, manifest);
+
+    // Cleanup old receipts if needed
+    this.cleanupOldReceipts();
+
+    return receipt;
+  }
+
+  /**
+   * Get receipt for a session, if it exists.
+   */
+  getReceipt(sessionId: string, projectRoot?: string, scope?: string): PolicyReceipt | null {
+    const key = this.getReceiptKey(sessionId, projectRoot ?? "", scope ?? "");
+    const receipt = this.receipts.get(key);
+
+    if (!receipt) return null;
+
+    // Check TTL
+    if (Date.now() - receipt.deliveredAt > this.config.receiptTtlMs) {
+      this.receipts.delete(key);
+      return null;
+    }
+
+    return receipt;
+  }
+
+  /**
+   * Check if a session has a valid receipt for the given manifest.
+   */
+  hasValidReceipt(sessionId: string, manifest: PolicyManifest): boolean {
+    const receipt = this.getReceipt(sessionId, manifest.projectRoot);
+    if (!receipt) return false;
+
+    // Check revision match
+    if (receipt.revision !== manifest.revision) {
+      return false;
+    }
+
+    // Check scope coverage
+    const receiptScope = receipt.scope;
+    const manifestScope = this.getScopeFromManifest(manifest);
+    
+    if (receiptScope && manifestScope && !receiptScope.startsWith(manifestScope)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate a receipt against the current manifest.
+   */
+  validateReceipt(sessionId: string, manifest: PolicyManifest): {
+    valid: boolean;
+    reason?: string;
+  } {
+    const receipt = this.getReceipt(sessionId, manifest.projectRoot);
+
+    if (!receipt) {
+      return { valid: false, reason: "No receipt found for this session" };
+    }
+
+    if (receipt.revision !== manifest.revision) {
+      return {
+        valid: false,
+        reason: `Receipt revision ${receipt.revision} does not match current ${manifest.revision}`,
+      };
+    }
+
+    if (Date.now() - receipt.deliveredAt > this.config.receiptTtlMs) {
+      return { valid: false, reason: "Receipt has expired" };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Invalidate receipts when a rule file changes.
+   */
+  invalidateOnChange(changedPath: string): string[] {
+    const invalidatedSessions: string[] = [];
+
+    for (const [key, manifest] of this.lastKnownManifests) {
+      // Check if the changed path affects any of our sources
+      const affectedSource = manifest.sources.find(s => 
+        s.path === changedPath || s.path.includes(changedPath)
+      );
+
+      if (affectedSource) {
+        // Extract session ID from key
+        const sessionId = key.split("|")[0];
+        this.receipts.delete(key);
+        invalidatedSessions.push(sessionId);
+      }
+    }
+
+    return invalidatedSessions;
+  }
+
+  /**
+   * Invalidate all receipts for a project root.
+   */
+  invalidateProject(projectRoot: string): void {
+    for (const [key, receipt] of this.receipts) {
+      if (receipt.projectRoot === projectRoot) {
+        this.receipts.delete(key);
+      }
+    }
+
+    // Also clean up last known manifests for this project
+    for (const [key, manifest] of this.lastKnownManifests) {
+      if (manifest.projectRoot === projectRoot) {
+        this.lastKnownManifests.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Invalidate all receipts (e.g., after compaction).
+   */
+  invalidateAll(): void {
+    this.receipts.clear();
+    this.sessionScopes.clear();
+  }
+
+  /**
+   * Clear receipts for a specific session.
+   */
+  clearSession(sessionId: string): void {
+    for (const [key, receipt] of this.receipts) {
+      if (receipt.sessionId === sessionId) {
+        this.receipts.delete(key);
+      }
+    }
+    this.sessionScopes.delete(sessionId);
+  }
+
+  /**
+   * Get all receipts for a session.
+   */
+  getSessionReceipts(sessionId: string): PolicyReceipt[] {
+    const receipts: PolicyReceipt[] = [];
+    for (const receipt of this.receipts.values()) {
+      if (receipt.sessionId === sessionId) {
+        receipts.push(receipt);
+      }
+    }
+    return receipts;
+  }
+
+  /**
+   * Get statistics about stored receipts.
+   */
+  getStats(): {
+    totalReceipts: number;
+    sessionsTracked: number;
+    projectsTracked: number;
+    oldestReceipt: number | null;
+    newestReceipt: number | null;
+  } {
+    let oldest: number | null = null;
+    let newest: number | null = null;
+    const projects = new Set<string>();
+
+    for (const receipt of this.receipts.values()) {
+      if (oldest === null || receipt.deliveredAt < oldest) {
+        oldest = receipt.deliveredAt;
+      }
+      if (newest === null || receipt.deliveredAt > newest) {
+        newest = receipt.deliveredAt;
+      }
+      projects.add(receipt.projectRoot);
+    }
+
+    return {
+      totalReceipts: this.receipts.size,
+      sessionsTracked: this.sessionScopes.size,
+      projectsTracked: projects.size,
+      oldestReceipt: oldest,
+      newestReceipt: newest,
+    };
+  }
+
+  /**
+   * Generate receipt key for storage.
+   */
+  private getReceiptKey(sessionId: string, projectRoot: string, scope: string): string {
+    return `${sessionId}|${projectRoot}|${scope}`;
+  }
+
+  /**
+   * Extract scope from manifest.
+   */
+  private getScopeFromManifest(manifest: PolicyManifest): string {
+    const mandatorySources = manifest.sources.filter(s => s.priority === "mandatory");
+    if (mandatorySources.length === 0) return "";
+    
+    // Get the most specific (longest) scope
+    mandatorySources.sort((a, b) => b.scope.length - a.scope.length);
+    return mandatorySources[0]?.scope ?? "";
+  }
+
+  /**
+   * Cleanup old receipts to prevent memory leaks.
+   */
+  private cleanupOldReceipts(): void {
+    if (this.receipts.size <= this.config.maxReceiptsPerSession) {
+      return;
+    }
+
+    // Sort by delivery time, oldest first
+    const sorted = [...this.receipts.entries()].sort(
+      (a, b) => a[1].deliveredAt - b[1].deliveredAt
+    );
+
+    // Remove oldest entries until under limit
+    const toRemove = sorted.slice(0, sorted.length - this.config.maxReceiptsPerSession);
+    for (const [key] of toRemove) {
+      this.receipts.delete(key);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton instance (for use in extension)
+// ---------------------------------------------------------------------------
+
+let globalPolicyStore: PolicyStore | null = null;
+
+/**
+ * Get the global policy store instance.
+ */
+export function getPolicyStore(): PolicyStore {
+  if (!globalPolicyStore) {
+    globalPolicyStore = new PolicyStore();
+  }
+  return globalPolicyStore;
+}
+
+/**
+ * Reset the global policy store (for testing).
+ */
+export function resetPolicyStore(): void {
+  globalPolicyStore = null;
+}