pi-harness-runtime 1.1.349 → 1.1.351

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

@@ -0,0 +1,142 @@
+/**
+ * Delegation Assessment Types
+ *
+ * Types for consistent delegation assessment for large refactors.
+ */
+/**
+ * Scope estimation for a refactoring task
+ */
+export interface ScopeFacts {
+    /** Estimated number of relevant files affected */
+    estimatedFiles: number;
+    /** Actual observed number of files (after scanning) */
+    observedFiles: number;
+    /** Estimated number of call sites/changes */
+    estimatedCallSites: number;
+    /** Actual observed call sites */
+    observedCallSites: number;
+    /** Number of independent components/groups */
+    independentComponents: number;
+    /** Whether changes are tightly coupled (shared APIs) */
+    tightlyCoupled: boolean;
+    /** Whether transformation is mechanical (safe for scripts) */
+    isMechanical: boolean;
+    /** Whether transformation is complex (needs reasoning) */
+    isComplex: boolean;
+    /** File type breakdown */
+    fileTypes: Record<string, number>;
+    /** Scope fingerprint for change detection */
+    fingerprint: string;
+}
+/**
+ * Delegation strategy decision
+ */
+export type DelegationStrategy = "delegate" | "script_then_delegate" | "script_only" | "single_agent" | "unavailable";
+/**
+ * Work group for delegation
+ */
+export interface WorkGroup {
+    /** Unique group ID */
+    groupId: string;
+    /** Human-readable description */
+    description: string;
+    /** Files owned by this group */
+    ownedPaths: string[];
+    /** Whether this group is mechanical (script-friendly) */
+    isMechanical: boolean;
+    /** Assigned child agent ID (if delegated) */
+    childId?: string;
+    /** Status of this group */
+    status: "pending" | "dispatched" | "running" | "completed" | "failed" | "cancelled";
+    /** Validation evidence */
+    validation?: {
+        passed: boolean;
+        details: string;
+    };
+}
+/**
+ * Delegation decision from Jev or fallback
+ */
+export interface DelegationDecision {
+    /** Strategy selected */
+    strategy: DelegationStrategy;
+    /** Reason for the decision */
+    reason: string;
+    /** Proposed work groups (for delegate strategies) */
+    workGroups: WorkGroup[];
+    /** Validation expectations */
+    validationExpectations: string;
+    /** Confidence level */
+    confidence: "high" | "medium" | "low";
+    /** Whether Jev was used */
+    jevUsed: boolean;
+    /** Reassessment triggers */
+    reassessmentTriggers: string[];
+}
+/**
+ * Delegation receipt for persistence
+ */
+export interface DelegationReceipt {
+    /** Version for schema compatibility */
+    version: number;
+    /** Workspace canonical path */
+    workspacePath: string;
+    /** Session ID */
+    sessionId: string;
+    /** Parent task ID */
+    parentTaskId: string;
+    /** Scope fingerprint */
+    scopeFingerprint: string;
+    /** Decision made */
+    decision: DelegationDecision;
+    /** Created timestamp */
+    createdAt: number;
+    /** Last updated timestamp */
+    updatedAt: number;
+    /** Status */
+    status: "assessing" | "in_progress" | "completed" | "failed" | "cancelled";
+    /** Active child IDs */
+    childIds: string[];
+    /** Outstanding validation items */
+    pendingValidation: string[];
+    /** User constraints (e.g., no delegation) */
+    userConstraints: string[];
+}
+/**
+ * Delegation assessment trigger config
+ */
+export interface DelegationTriggerConfig {
+    /** Minimum files to trigger assessment */
+    minFiles: number;
+    /** Minimum call sites to trigger assessment */
+    minCallSites: number;
+    /** Minimum independent components to suggest delegation */
+    minIndependentComponents: number;
+    /** Whether to assess on scope discovery vs mutation */
+    assessOnDiscovery: boolean;
+}
+/**
+ * Default trigger config
+ */
+export declare const DEFAULT_DELEGATION_TRIGGERS: DelegationTriggerConfig;
+/**
+ * Extension capability for delegation
+ */
+export interface ExtensionCapability {
+    /** Extension name */
+    name: string;
+    /** Whether it supports sub-agents */
+    supportsSubagents: boolean;
+    /** Whether it supports work isolation */
+    supportsWorkIsolation: boolean;
+    /** Whether it supports cancellation */
+    supportsCancellation: boolean;
+    /** Supported tool names */
+    availableTools: string[];
+    /** Verified working */
+    verified: boolean;
+}
+/**
+ * Check if delegation should be triggered
+ */
+export declare function shouldTriggerAssessment(facts: ScopeFacts, config?: DelegationTriggerConfig): boolean;

package/packages/contracts/dist/delegation.js

@@ -0,0 +1,33 @@
+/**
+ * Delegation Assessment Types
+ *
+ * Types for consistent delegation assessment for large refactors.
+ */
+/**
+ * Default trigger config
+ */
+export const DEFAULT_DELEGATION_TRIGGERS = {
+    minFiles: 10,
+    minCallSites: 50,
+    minIndependentComponents: 2,
+    assessOnDiscovery: true,
+};
+/**
+ * Check if delegation should be triggered
+ */
+export function shouldTriggerAssessment(facts, config = DEFAULT_DELEGATION_TRIGGERS) {
+    // Check file count
+    if (facts.observedFiles >= config.minFiles)
+        return true;
+    if (facts.estimatedFiles >= config.minFiles)
+        return true;
+    // Check call sites
+    if (facts.observedCallSites >= config.minCallSites)
+        return true;
+    if (facts.estimatedCallSites >= config.minCallSites)
+        return true;
+    // Check independent components
+    if (facts.independentComponents >= config.minIndependentComponents)
+        return true;
+    return false;
+}

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

@@ -18,3 +18,8 @@ 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 './delegation-store.js';
+export * from './scope-discovery.js';
+export * from './work-partitioner.js';

package/packages/contracts/dist/index.js

@@ -18,3 +18,8 @@ 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 './delegation-store.js';
+export * from './scope-discovery.js';
+export * from './work-partitioner.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/dist/work-partitioner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Work Partitioner
+ *
+ * Partitions work into disjoint file ownership groups.
+ */
+import type { WorkGroup, ScopeFacts } from "./delegation.js";
+/**
+ * File dependency info
+ */
+export interface FileDependency {
+    path: string;
+    imports: string[];
+    exports: string[];
+}
+/**
+ * Partition configuration
+ */
+export interface PartitionConfig {
+    /** Maximum files per group */
+    maxFilesPerGroup: number;
+    /** Whether to group by directory */
+    groupByDirectory: boolean;
+    /** Shared files that shouldn't be partitioned */
+    sharedPaths: string[];
+}
+/**
+ * Default partition config
+ */
+export declare const DEFAULT_PARTITION_CONFIG: PartitionConfig;
+/**
+ * Partition files into ownership groups
+ */
+export declare function partitionWork(files: string[], facts: ScopeFacts, config?: Partial<PartitionConfig>): WorkGroup[];
+/**
+ * Detect ownership conflicts
+ */
+export declare function detectOwnershipConflicts(groups: WorkGroup[], newPaths: string[]): string[];
+/**
+ * Assign work to group
+ */
+export declare function assignWorkToGroup(groups: WorkGroup[], groupId: string, paths: string[]): WorkGroup | null;
+/**
+ * Get unowned files
+ */
+export declare function getUnownedFiles(allFiles: string[], groups: WorkGroup[]): string[];
+/**
+ * Update group status
+ */
+export declare function updateGroupStatus(groups: WorkGroup[], groupId: string, status: WorkGroup["status"], childId?: string): WorkGroup[];
+/**
+ * Check if all groups are complete
+ */
+export declare function areAllGroupsComplete(groups: WorkGroup[]): boolean;
+/**
+ * Get pending groups
+ */
+export declare function getPendingGroups(groups: WorkGroup[]): WorkGroup[];