pi-harness-runtime 1.1.348 → 1.1.350

package/packages/contracts/dist/index.d.ts

@@ -18,3 +18,6 @@ export * from './sessions.js';
 export * from './projects.js';
 export * from './notifications.js';
 export * from './approvals.js';
+export * from './delegation.js';
+export * from './delegation-assessor.js';
+export * from './scope-discovery.js';

package/packages/contracts/dist/index.js

@@ -18,3 +18,6 @@ export * from './sessions.js';
 export * from './projects.js';
 export * from './notifications.js';
 export * from './approvals.js';
+export * from './delegation.js';
+export * from './delegation-assessor.js';
+export * from './scope-discovery.js';

package/packages/contracts/dist/scope-discovery.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Scope Discovery
+ *
+ * Discovers and estimates the scope of refactoring work.
+ */
+/**
+ * File pattern matcher
+ */
+export interface FilePattern {
+    /** Glob pattern or exact extension */
+    pattern: string;
+    /** Whether to recurse into directories */
+    recursive?: boolean;
+}
+/**
+ * Scope discovery configuration
+ */
+export interface ScopeDiscoveryConfig {
+    /** File extensions to consider relevant */
+    relevantExtensions: string[];
+    /** Directories to exclude (vendored, generated, etc.) */
+    excludeDirs: string[];
+    /** Files to exclude by name */
+    excludeFiles: string[];
+    /** Whether to scan for call sites */
+    scanCallSites: boolean;
+    /** Call site patterns to count */
+    callSitePatterns: string[];
+}
+/**
+ * Default scope discovery config
+ */
+export declare const DEFAULT_SCOPE_CONFIG: ScopeDiscoveryConfig;
+/**
+ * Discovered scope result
+ */
+export interface DiscoveredScope {
+    /** Total relevant files found */
+    totalFiles: number;
+    /** Files matching the refactoring pattern */
+    matchingFiles: number;
+    /** Estimated call sites */
+    callSites: number;
+    /** Independent components found */
+    components: string[];
+    /** File breakdown by type */
+    fileTypes: Record<string, number>;
+    /** Whether shared APIs were detected */
+    hasSharedApis: boolean;
+    /** Whether transformation appears mechanical */
+    isMechanical: boolean;
+    /** Scope fingerprint for change detection */
+    fingerprint: string;
+}
+/**
+ * Discover scope by scanning files
+ */
+export declare function discoverScope(workspacePath: string, searchPattern: string, config?: Partial<ScopeDiscoveryConfig>): DiscoveredScope;
+/**
+ * Quick scope estimate using git grep
+ */
+export declare function quickScopeEstimate(workspacePath: string, pattern: string): {
+    fileCount: number;
+    lineCount: number;
+};

package/packages/contracts/dist/scope-discovery.js

@@ -0,0 +1,247 @@
+/**
+ * Scope Discovery
+ *
+ * Discovers and estimates the scope of refactoring work.
+ */
+import { readFileSync, readdirSync } from "fs";
+import { join, extname, relative } from "path";
+import { execSync } from "child_process";
+/**
+ * Default scope discovery config
+ */
+export const DEFAULT_SCOPE_CONFIG = {
+    relevantExtensions: [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
+    excludeDirs: [
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        ".next",
+        "__pycache__",
+        "vendor",
+        "generated",
+        ".venv",
+        "coverage",
+    ],
+    excludeFiles: [
+        "package-lock.json",
+        "yarn.lock",
+        "pnpm-lock.yaml",
+        "bun.lockb",
+        "*.min.js",
+        "*.bundle.js",
+    ],
+    scanCallSites: true,
+    callSitePatterns: [
+        "TODO:",
+        "FIXME:",
+        "console.log",
+        "throw new",
+        "await this",
+        "// @ts-ignore",
+    ],
+};
+/**
+ * Discover scope by scanning files
+ */
+export function discoverScope(workspacePath, searchPattern, config = {}) {
+    const cfg = { ...DEFAULT_SCOPE_CONFIG, ...config };
+    const files = [];
+    const fileTypes = {};
+    const callSites = [];
+    const components = new Set();
+    // Scan directory recursively
+    scanDirectory(workspacePath, files, fileTypes, cfg, 0);
+    // Filter to relevant files
+    const relevantFiles = files.filter((f) => cfg.relevantExtensions.includes(extname(f)));
+    // Count matching files and call sites
+    let matchingCount = 0;
+    for (const file of relevantFiles) {
+        const content = readFileSync(file, "utf8").slice(0, 10000); // First 10KB
+        // Check if file matches search pattern
+        if (content.toLowerCase().includes(searchPattern.toLowerCase())) {
+            matchingCount++;
+            // Count call sites
+            if (cfg.scanCallSites) {
+                for (const pattern of cfg.callSitePatterns) {
+                    const matches = content.match(new RegExp(pattern, "gi"));
+                    if (matches) {
+                        callSites.push(...matches.map((m) => `${file}:${m}`));
+                    }
+                }
+            }
+            // Identify component (directory)
+            const relPath = relative(workspacePath, file);
+            const parts = relPath.split("/");
+            if (parts.length > 1) {
+                components.add(parts.slice(0, -1).join("/"));
+            }
+        }
+    }
+    // Detect shared APIs (files that are imported by multiple components)
+    const hasSharedApis = detectSharedApis(relevantFiles);
+    // Detect if transformation is mechanical (simple replacements)
+    const isMechanical = detectMechanicalPattern(relevantFiles, searchPattern);
+    // Generate fingerprint
+    const fingerprint = generateFingerprint(matchingCount, callSites.length, components.size);
+    return {
+        totalFiles: relevantFiles.length,
+        matchingFiles: matchingCount,
+        callSites: callSites.slice(0, 100).length,
+        components: Array.from(components),
+        fileTypes,
+        hasSharedApis,
+        isMechanical,
+        fingerprint,
+    };
+}
+/**
+ * Recursively scan directory
+ */
+function scanDirectory(dir, files, fileTypes, config, depth) {
+    if (depth > 10)
+        return; // Max depth guard
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            // Skip excluded
+            if (config.excludeDirs.includes(entry.name))
+                continue;
+            if (config.excludeFiles.some((f) => entry.name.includes(f)))
+                continue;
+            if (entry.isDirectory()) {
+                scanDirectory(fullPath, files, fileTypes, config, depth + 1);
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+                const ext = extname(entry.name);
+                fileTypes[ext] = (fileTypes[ext] || 0) + 1;
+            }
+        }
+    }
+    catch {
+        // Skip inaccessible directories
+    }
+}
+/**
+ * Detect if files have shared API patterns
+ */
+function detectSharedApis(files) {
+    // Look for common export patterns
+    const exportCounts = new Map();
+    for (const file of files.slice(0, 50)) {
+        // Sample first 50 files
+        try {
+            const content = readFileSync(file, "utf8").slice(0, 5000);
+            // Count exports
+            const exportMatches = content.match(/export\s+(const|function|class|type|interface)/g);
+            if (exportMatches) {
+                exportCounts.set(file, (exportCounts.get(file) || 0) + exportMatches.length);
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    // Multiple files with exports suggests shared APIs
+    let filesWithExports = 0;
+    for (const count of exportCounts.values()) {
+        if (count > 0)
+            filesWithExports++;
+    }
+    return filesWithExports > 3;
+}
+/**
+ * Detect if transformation is mechanical (simple replacements)
+ */
+function detectMechanicalPattern(files, searchPattern) {
+    // Mechanical = simple string replacement, no complex logic
+    // Look for consistent patterns
+    let mechanicalCount = 0;
+    let totalMatches = 0;
+    for (const file of files.slice(0, 20)) {
+        try {
+            const content = readFileSync(file, "utf8");
+            const matches = content.match(new RegExp(searchPattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi"));
+            if (matches) {
+                totalMatches += matches.length;
+                // Check if each match is a simple replacement (same context)
+                // Mechanical if: same indentation, same surrounding code pattern
+                const uniqueContexts = new Set();
+                for (const match of matches.slice(0, 5)) {
+                    const idx = content.indexOf(match);
+                    const before = content.slice(Math.max(0, idx - 20), idx);
+                    const after = content.slice(idx + match.length, idx + match.length + 20);
+                    uniqueContexts.add(before.trim() + "|" + after.trim());
+                }
+                // Single context = mechanical
+                if (uniqueContexts.size === 1) {
+                    mechanicalCount++;
+                }
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    // More than half mechanical = likely mechanical
+    return totalMatches > 0 && mechanicalCount / totalMatches > 0.5;
+}
+/**
+ * Generate scope fingerprint
+ */
+function generateFingerprint(fileCount, callSiteCount, componentCount) {
+    // Simple fingerprint based on counts
+    const data = `${fileCount}:${callSiteCount}:${componentCount}`;
+    let hash = 0;
+    for (let i = 0; i < data.length; i++) {
+        const char = data.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Quick scope estimate using git grep
+ */
+export function quickScopeEstimate(workspacePath, pattern) {
+    // Validate inputs to prevent command injection
+    const safePath = validatePath(workspacePath);
+    if (!safePath)
+        return { fileCount: 0, lineCount: 0 };
+    const safePattern = escapeForGrep(pattern);
+    if (!safePattern)
+        return { fileCount: 0, lineCount: 0 };
+    try {
+        const result = execSync(`grep -r "${safePattern}" "${safePath}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -l 2>/dev/null | wc -l`, { encoding: "utf8", timeout: 10000 });
+        const fileCount = parseInt(result.trim(), 10) || 0;
+        const lineResult = execSync(`grep -r "${safePattern}" "${safePath}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | wc -l`, { encoding: "utf8", timeout: 10000 });
+        const lineCount = parseInt(lineResult.trim(), 10) || 0;
+        return { fileCount, lineCount };
+    }
+    catch {
+        return { fileCount: 0, lineCount: 0 };
+    }
+}
+/**
+ * Validate and sanitize a file path
+ */
+function validatePath(path) {
+    // Only allow alphanumeric, hyphen, underscore, dot, and forward slash
+    if (!/^[\w./-]+$/.test(path)) {
+        return null;
+    }
+    // Prevent path traversal
+    if (path.includes("..")) {
+        return null;
+    }
+    return path;
+}
+/**
+ * Escape a string for safe use in grep pattern
+ */
+function escapeForGrep(pattern) {
+    // Remove any shell metacharacters
+    return pattern.replace(/[|;&$`\\"'<>\(\)\[\]\{\}]/g, "");
+}

package/packages/contracts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/contracts",
-  "version": "1.1.348",
+  "version": "1.1.350",
   "type": "module",
   "description": "RPC schema definitions for pi-harness runtime",
   "main": "./dist/index.js",

package/packages/contracts/src/delegation-assessor.ts

@@ -0,0 +1,268 @@
+/**
+ * Delegation Assessor
+ * 
+ * Assesses whether work should be delegated to sub-agents based on scope.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ScopeFacts,
+  DelegationDecision,
+  DelegationStrategy,
+  WorkGroup,
+  DelegationTriggerConfig,
+  ExtensionCapability,
+  DEFAULT_DELEGATION_TRIGGERS,
+} from "./delegation.js";
+import { shouldTriggerAssessment } from "./delegation.js";
+
+/**
+ * Sub-agent extension names to check for
+ */
+const SUBAGENT_EXTENSIONS = [
+  "pi-subagents",
+  "@earendil-works/pi-subagents",
+  "subagent",
+  "spawn",
+  "delegate",
+];
+
+/**
+ * Tool names that indicate sub-agent capability
+ */
+const SUBAGENT_TOOLS = [
+  "subagent",
+  "spawn",
+  "delegate",
+  "run_subagent",
+  "run_agent",
+];
+
+/**
+ * Discover extension capabilities for delegation
+ */
+export async function discoverDelegationCapability(
+  pi: ExtensionAPI
+): Promise<ExtensionCapability | null> {
+  // Get all available tools
+  const allTools = pi.getAllTools();
+  const toolNames = allTools.map((t) => t.name);
+  const activeTools = pi.getActiveTools();
+
+  // Check for sub-agent tools
+  const hasSubagentTool = SUBAGENT_TOOLS.some(
+    (tool) => toolNames.includes(tool) || activeTools.includes(tool)
+  );
+
+  // Check for subagent extension registration
+  // The extension might register tools under different names
+  const possibleCapabilities: ExtensionCapability[] = [];
+
+  // Verify by attempting a capability check
+  // If subagent tools exist, assume capability
+  if (hasSubagentTool) {
+    return {
+      name: "subagent-extension",
+      supportsSubagents: true,
+      supportsWorkIsolation: true, // Assume based on tool presence
+      supportsCancellation: true,
+      availableTools: activeTools.filter((t) =>
+        SUBAGENT_TOOLS.some((st) => t.includes(st))
+      ),
+      verified: true,
+    };
+  }
+
+  // Check if pi-subagents skill is mentioned in available tools
+  const subagentMentioned = toolNames.some(
+    (t) => t.includes("subagent") || t.includes("spawn")
+  );
+
+  if (subagentMentioned) {
+    return {
+      name: "pi-subagents",
+      supportsSubagents: true,
+      supportsWorkIsolation: true,
+      supportsCancellation: true,
+      availableTools: toolNames.filter((t) => t.includes("subagent")),
+      verified: false, // Not verified - just mentioned
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Estimate scope from file analysis
+ */
+export async function estimateScope(
+  _pi: ExtensionAPI,
+  patterns: string[]
+): Promise<ScopeFacts> {
+  // TODO: Implement actual file discovery
+  // For now, return placeholder
+  return {
+    estimatedFiles: patterns.length,
+    observedFiles: 0,
+    estimatedCallSites: 0,
+    observedCallSites: 0,
+    independentComponents: 1,
+    tightlyCoupled: false,
+    isMechanical: true,
+    isComplex: false,
+    fileTypes: {},
+    fingerprint: "",
+  };
+}
+
+/**
+ * Make deterministic assessment without Jev
+ */
+export function makeDeterministicAssessment(
+  facts: ScopeFacts,
+  capability: ExtensionCapability | null
+): DelegationDecision {
+  // No capability - must use single agent
+  if (!capability?.verified) {
+    return {
+      strategy: "unavailable",
+      reason: "No verified sub-agent capability available",
+      workGroups: [],
+      validationExpectations: "Parent handles all validation",
+      confidence: "high",
+      jevUsed: false,
+      reassessmentTriggers: ["Extension becomes available"],
+    };
+  }
+
+  // Small scope - single agent
+  if (facts.observedFiles < 5 && facts.observedCallSites < 20) {
+    return {
+      strategy: "single_agent",
+      reason: "Small scope - delegation overhead not justified",
+      workGroups: [],
+      validationExpectations: "Standard parent validation",
+      confidence: "high",
+      jevUsed: false,
+      reassessmentTriggers: [],
+    };
+  }
+
+  // Mechanical transformation with reliable script
+  if (facts.isMechanical && !facts.isComplex) {
+    return {
+      strategy: "script_only",
+      reason: "Mechanical transformation - script approach is reliable",
+      workGroups: [],
+      validationExpectations: "Script output validation + test run",
+      confidence: "high",
+      jevUsed: false,
+      reassessmentTriggers: ["Transformation proves unreliable"],
+    };
+  }
+
+  // Multiple independent components
+  if (facts.independentComponents >= 2 && !facts.tightlyCoupled) {
+    const groups = partitionIntoGroups(facts);
+    return {
+      strategy: "delegate",
+      reason: `${facts.independentComponents} independent components - delegation recommended`,
+      workGroups: groups,
+      validationExpectations: "Each group validated independently, then integrated",
+      confidence: "medium",
+      jevUsed: false,
+      reassessmentTriggers: ["Scope expands significantly", "Component coupling discovered"],
+    };
+  }
+
+  // Tightly coupled - sequential or single agent
+  if (facts.tightlyCoupled) {
+    return {
+      strategy: "script_then_delegate",
+      reason: "Coupled components - script shared parts, delegate isolated changes",
+      workGroups: [],
+      validationExpectations: "Script validates shared API, delegate validates components",
+      confidence: "medium",
+      jevUsed: false,
+      reassessmentTriggers: ["Coupling reduced after refactoring"],
+    };
+  }
+
+  // Default - single agent with monitoring
+  return {
+    strategy: "single_agent",
+    reason: "Default to single agent for bounded scope",
+    workGroups: [],
+    validationExpectations: "Parent validates all changes",
+    confidence: "low",
+    jevUsed: false,
+    reassessmentTriggers: ["Scope exceeds threshold"],
+  };
+}
+
+/**
+ * Partition work into groups
+ */
+function partitionIntoGroups(facts: ScopeFacts): WorkGroup[] {
+  const groups: WorkGroup[] = [];
+  const filesPerGroup = Math.ceil(facts.observedFiles / facts.independentComponents);
+
+  for (let i = 0; i < facts.independentComponents; i++) {
+    groups.push({
+      groupId: `group-${i + 1}`,
+      description: `Component ${i + 1} of ${facts.independentComponents}`,
+      ownedPaths: [], // TODO: Populate with actual files
+      isMechanical: facts.isMechanical,
+      status: "pending",
+    });
+  }
+
+  return groups;
+}
+
+/**
+ * Assess delegation need
+ */
+export async function assessDelegation(
+  pi: ExtensionAPI,
+  facts: ScopeFacts,
+  config: DelegationTriggerConfig = { minFiles: 10, minCallSites: 50, minIndependentComponents: 2, assessOnDiscovery: true }
+): Promise<DelegationDecision | null> {
+  // Check if assessment should trigger
+  if (!shouldTriggerAssessment(facts, config)) {
+    return null; // No assessment needed
+  }
+
+  // Discover capability
+  const capability = await discoverDelegationCapability(pi);
+
+  // Make deterministic assessment
+  return makeDeterministicAssessment(facts, capability);
+}
+
+/**
+ * Validate assessment is still valid
+ */
+export function isAssessmentStale(
+  decision: DelegationDecision,
+  currentFacts: ScopeFacts,
+  originalFacts: ScopeFacts
+): boolean {
+  // Scope significantly expanded
+  if (currentFacts.observedFiles > originalFacts.observedFiles * 1.5) {
+    return true;
+  }
+
+  // New coupling discovered
+  if (currentFacts.tightlyCoupled && !originalFacts.tightlyCoupled) {
+    return true;
+  }
+
+  // Reassessment triggers
+  return decision.reassessmentTriggers.some((trigger) => {
+    if (trigger.includes("scope expands")) {
+      return currentFacts.observedFiles > originalFacts.observedFiles * 1.5;
+    }
+    return false;
+  });
+}