pi-harness-runtime 1.1.349 → 1.1.351

package/README.md

@@ -30,10 +30,13 @@ pi install npm:pi-harness-runtime
 This runtime works best with these extensions (auto-installed by pi-harness-runtime):
 
 ```bash
+pi install npm:pi-subagents     # Sub-agent orchestration for large refactors
 pi install npm:pi-mcp-adapter    # MCP protocol adapter for external tools
 pi install npm:@juicesharp/rpiv-todo  # Task tracking with bd sync
 ```
 
+The `pi-subagents` extension enables delegation assessment and parallel task execution for large refactoring work (10+ files, 50+ call sites).
+
 Requires Pi v0.37.3+.
 
 ### Headless Server Setup (herdr clipboard bridge)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-harness-runtime",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "[BETA] Codex-style /usage status + autonomous coding harness for pi. Not production ready — expect breaking changes.",
   "type": "module",
   "scripts": {

package/packages/a2a-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/a2a-adapter",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "description": "Google Agent-to-Agent (A2A) protocol adapter for pi-harness",
   "main": "dist/index.js",

package/packages/agent-policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/agent-policy",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Agent policy runtime for pi-harness - enforces mandatory rule delivery and mutation gating",
   "type": "module",
   "main": "./dist/index.js",

package/packages/architecture-generator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/architecture-generator",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Generate ADR and Mermaid diagrams from project analysis",
   "type": "module",
   "main": "./dist/index.js",

package/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/auth",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "pi-harness-runtime — auth",
   "type": "module",
   "main": "./dist/index.js",

package/packages/autonomous-refactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/autonomous-refactor",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "description": "Autonomous refactoring engine",
   "main": "dist/index.js",

package/packages/autonomous-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/autonomous-runtime",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Autonomous Operations Runtime — task inbox, lease management, and worker lifecycle (RFC-0101)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cache-strategy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/cache-strategy",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "description": "Smart caching with TTL and invalidation strategies (RFC-0022)",
   "main": "dist/index.js",

package/packages/capability-registry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/capability-registry",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Capability Registry for pi-harness-runtime — tracks model capabilities and enables capability-based routing",
   "type": "module",
   "main": "./dist/index.js",

package/packages/checkpoint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/checkpoint",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Enhanced checkpoint system with incremental snapshots, diff-based storage, and recovery strategies",
   "type": "module",
   "main": "./dist/index.js",

package/packages/cli-plugin-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/cli-plugin-sdk",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "description": "CLI Plugin SDK for pi-harness — install, list, remove, update, invoke plugins",
   "main": "dist/index.js",

package/packages/clipboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/clipboard",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/clipboard-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/clipboard-plugin",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/code-generation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/code-generation",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Code generation pipeline for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/code-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/code-review",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Automated code review engine for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/codex-adapter",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "description": "OpenAI Codex provider adapter for pi-harness",
   "main": "dist/index.js",

package/packages/codex-watcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/codex-watcher",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Watches Codex CLI sessions and emits visible messages for PING-PONG monitoring",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/config-capture/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/config-capture",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Auto-capture API-fetched configuration values to AGENTS.md",
   "type": "module",
   "main": "src/index.ts",

package/packages/connection-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/connection-runtime",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "description": "Connection management with jittered exponential backoff for pi-harness",
   "main": "./dist/index.js",

package/packages/context-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/context-compiler",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Bounded context selection engine for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/context-discovery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/context-discovery",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

package/packages/context-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/context-manager",
-  "version": "1.1.349",
+  "version": "1.1.351",
   "description": "Context Window Manager — prevents model context overflow via compaction and resume prompts (RFC-0010)",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -0,0 +1,27 @@
+/**
+ * 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, DelegationTriggerConfig, ExtensionCapability } from "./delegation.js";
+/**
+ * Discover extension capabilities for delegation
+ */
+export declare function discoverDelegationCapability(pi: ExtensionAPI): Promise<ExtensionCapability | null>;
+/**
+ * Estimate scope from file analysis
+ */
+export declare function estimateScope(_pi: ExtensionAPI, patterns: string[]): Promise<ScopeFacts>;
+/**
+ * Make deterministic assessment without Jev
+ */
+export declare function makeDeterministicAssessment(facts: ScopeFacts, capability: ExtensionCapability | null): DelegationDecision;
+/**
+ * Assess delegation need
+ */
+export declare function assessDelegation(pi: ExtensionAPI, facts: ScopeFacts, config?: DelegationTriggerConfig): Promise<DelegationDecision | null>;
+/**
+ * Validate assessment is still valid
+ */
+export declare function isAssessmentStale(decision: DelegationDecision, currentFacts: ScopeFacts, originalFacts: ScopeFacts): boolean;

package/packages/contracts/dist/delegation-assessor.js

@@ -0,0 +1,210 @@
+/**
+ * Delegation Assessor
+ *
+ * Assesses whether work should be delegated to sub-agents based on scope.
+ */
+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) {
+    // 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 = [];
+    // 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, patterns) {
+    // 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, capability) {
+    // 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) {
+    const groups = [];
+    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, facts, config = { minFiles: 10, minCallSites: 50, minIndependentComponents: 2, assessOnDiscovery: true }) {
+    // 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, currentFacts, originalFacts) {
+    // 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;
+    });
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Delegation Store
+ *
+ * Durable storage for delegation receipts.
+ * Stores in ignored harness state directory.
+ */
+import type { DelegationReceipt } from "./delegation.js";
+/**
+ * Save delegation receipt
+ */
+export declare function saveDelegationReceipt(receipt: DelegationReceipt): void;
+/**
+ * Load delegation receipt
+ */
+export declare function loadDelegationReceipt(workspacePath: string, taskId: string): DelegationReceipt | null;
+/**
+ * Delete delegation receipt
+ */
+export declare function deleteDelegationReceipt(workspacePath: string, taskId: string): void;
+/**
+ * List all receipts for a workspace
+ */
+export declare function listDelegationReceipts(workspacePath: string): DelegationReceipt[];
+/**
+ * Update receipt status
+ */
+export declare function updateReceiptStatus(workspacePath: string, taskId: string, status: DelegationReceipt["status"], updates?: Partial<DelegationReceipt>): DelegationReceipt | null;
+/**
+ * Check if receipt exists for task
+ */
+export declare function hasReceipt(workspacePath: string, taskId: string): boolean;
+/**
+ * Compact receipt for storage after compaction
+ */
+export declare function compactReceipt(receipt: DelegationReceipt): DelegationReceipt;

package/packages/contracts/dist/delegation-store.js

@@ -0,0 +1,172 @@
+/**
+ * Delegation Store
+ *
+ * Durable storage for delegation receipts.
+ * Stores in ignored harness state directory.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+/**
+ * Store directory path
+ */
+const STORE_DIR = join(process.env.HOME || "/home/frappe", ".pi-harness-runtime", "delegation-state");
+/**
+ * Ensure store directory exists
+ */
+function ensureStoreDir() {
+    if (!existsSync(STORE_DIR)) {
+        mkdirSync(STORE_DIR, { recursive: true });
+    }
+}
+/**
+ * Get receipt file path for workspace + task
+ */
+function getReceiptPath(workspacePath, taskId) {
+    // Sanitize path for use as filename
+    const safePath = workspacePath.replace(/[^a-zA-Z0-9_-]/g, "_").slice(-100);
+    const safeTask = taskId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join(STORE_DIR, `${safePath}__${safeTask}.json`);
+}
+/**
+ * Save delegation receipt
+ */
+export function saveDelegationReceipt(receipt) {
+    ensureStoreDir();
+    const path = getReceiptPath(receipt.workspacePath, receipt.parentTaskId);
+    // Atomic write: write to temp, then rename
+    const tempPath = path + ".tmp";
+    writeFileSync(tempPath, JSON.stringify(receipt, null, 2), "utf8");
+    // Rename is atomic on POSIX
+    try {
+        const { renameSync } = require("fs");
+        renameSync(tempPath, path);
+    }
+    catch {
+        // Fallback: just move the file
+        try {
+            writeFileSync(path, JSON.stringify(receipt, null, 2), "utf8");
+        }
+        catch {
+            // Ignore write errors
+        }
+    }
+}
+/**
+ * Load delegation receipt
+ */
+export function loadDelegationReceipt(workspacePath, taskId) {
+    const path = getReceiptPath(workspacePath, taskId);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(path, "utf8");
+        const receipt = JSON.parse(content);
+        // Validate version
+        if (receipt.version !== 1) {
+            // Future migration logic would go here
+            return null;
+        }
+        return receipt;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete delegation receipt
+ */
+export function deleteDelegationReceipt(workspacePath, taskId) {
+    const path = getReceiptPath(workspacePath, taskId);
+    if (existsSync(path)) {
+        try {
+            const { unlinkSync } = require("fs");
+            unlinkSync(path);
+        }
+        catch {
+            // Ignore delete errors
+        }
+    }
+}
+/**
+ * List all receipts for a workspace
+ */
+export function listDelegationReceipts(workspacePath) {
+    ensureStoreDir();
+    const receipts = [];
+    try {
+        const { readdirSync } = require("fs");
+        const files = readdirSync(STORE_DIR);
+        const safePathPrefix = workspacePath.replace(/[^a-zA-Z0-9_-]/g, "_").slice(-100) + "__";
+        for (const file of files) {
+            if (!file.startsWith(safePathPrefix) || !file.endsWith(".json")) {
+                continue;
+            }
+            try {
+                const content = readFileSync(join(STORE_DIR, file), "utf8");
+                const receipt = JSON.parse(content);
+                if (receipt.workspacePath === workspacePath) {
+                    receipts.push(receipt);
+                }
+            }
+            catch {
+                // Skip invalid files
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or not readable
+    }
+    return receipts;
+}
+/**
+ * Update receipt status
+ */
+export function updateReceiptStatus(workspacePath, taskId, status, updates) {
+    const receipt = loadDelegationReceipt(workspacePath, taskId);
+    if (!receipt) {
+        return null;
+    }
+    const updated = {
+        ...receipt,
+        ...updates,
+        status,
+        updatedAt: Date.now(),
+    };
+    saveDelegationReceipt(updated);
+    return updated;
+}
+/**
+ * Check if receipt exists for task
+ */
+export function hasReceipt(workspacePath, taskId) {
+    const path = getReceiptPath(workspacePath, taskId);
+    return existsSync(path);
+}
+/**
+ * Compact receipt for storage after compaction
+ */
+export function compactReceipt(receipt) {
+    return {
+        version: receipt.version,
+        workspacePath: receipt.workspacePath,
+        sessionId: receipt.sessionId,
+        parentTaskId: receipt.parentTaskId,
+        scopeFingerprint: receipt.scopeFingerprint,
+        decision: {
+            strategy: receipt.decision.strategy,
+            reason: receipt.decision.reason,
+            workGroups: receipt.decision.workGroups.filter((g) => g.status === "pending" || g.status === "dispatched" || g.status === "running"),
+            validationExpectations: receipt.decision.validationExpectations,
+            confidence: receipt.decision.confidence,
+            jevUsed: receipt.decision.jevUsed,
+            reassessmentTriggers: receipt.decision.reassessmentTriggers,
+        },
+        createdAt: receipt.createdAt,
+        updatedAt: Date.now(),
+        status: receipt.status,
+        childIds: receipt.childIds,
+        pendingValidation: receipt.pendingValidation,
+        userConstraints: receipt.userConstraints,
+    };
+}