pi-harness-runtime 1.1.451 → 1.1.452

package/packages/jev-judge/dist/delegation-scope.js

@@ -0,0 +1,218 @@
+/**
+ * The measured scope of a task.
+ *
+ * A delegation decision is only worth something when it is based on the
+ * work that really has to be done. The numbers of a request are not a
+ * measurement: "refactor everything" says nothing about how many files
+ * are affected. This module measures the scope in the workspace:
+ *
+ * - The files of the workspace that the request actually names.
+ * - The files the session has already changed.
+ * - The groups those files form (one group per package or directory).
+ * - The tracked files that reference the measured groups.
+ *
+ * Every number in the result is a count of something real. When nothing
+ * can be measured the result is empty, and the caller has to say so
+ * instead of inventing a scope.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+/** The default upper bound of the files of one measurement. */
+const DEFAULT_LIMIT = 400;
+/** The maximum number of groups that are searched for references. */
+const MAX_REFERENCE_GROUPS = 10;
+/**
+ * Run a git command in the workspace and return its output.
+ *
+ * A command that fails is not a measurement: the caller gets an empty
+ * result instead of a guess.
+ */
+function git(workspacePath, args) {
+    try {
+        return execFileSync("git", args, {
+            cwd: workspacePath,
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The tracked files of the workspace.
+ */
+function trackedFiles(workspacePath) {
+    const out = git(workspacePath, ["ls-files", "-z"]);
+    if (!out)
+        return [];
+    return out.split("\0").filter(Boolean);
+}
+/**
+ * The files the working tree has changed.
+ */
+export function changedFiles(workspacePath) {
+    const out = git(workspacePath, ["status", "--porcelain", "-z"]);
+    if (!out)
+        return [];
+    const files = [];
+    for (const entry of out.split("\0")) {
+        if (!entry)
+            continue;
+        // The porcelain format is "XY path"; a rename carries two paths.
+        const path = entry.slice(3).trim();
+        if (!path)
+            continue;
+        if (path.includes(" -> ")) {
+            const parts = path.split(" -> ");
+            files.push(parts[0].trim(), parts[1].trim());
+            continue;
+        }
+        files.push(path);
+    }
+    return files.filter(Boolean);
+}
+/**
+ * The group a file belongs to: its package, or its top directory.
+ */
+export function moduleOf(file) {
+    const parts = file.split("/");
+    if (parts[0] === "packages" && parts.length > 1)
+        return `packages/${parts[1]}`;
+    return parts[0];
+}
+/**
+ * The extension of a file, without the dot.
+ */
+export function extensionOf(file) {
+    const name = file.split("/").pop() ?? file;
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0)
+        return "";
+    return name.slice(dot + 1).toLowerCase();
+}
+/**
+ * Compare two paths.
+ */
+function comparePaths(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/**
+ * Group the measured files.
+ */
+export function groupFiles(files) {
+    const groups = new Map();
+    for (const file of files) {
+        const id = moduleOf(file);
+        const list = groups.get(id) ?? [];
+        list.push(file);
+        groups.set(id, list);
+    }
+    return [...groups.entries()]
+        .map(([id, groupFiles]) => ({ id, files: groupFiles.sort(comparePaths) }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * The number of tracked files that reference the groups.
+ *
+ * The count is a real count of the files that mention the path of the
+ * group, so it is a lower bound of the coupling, not a guess.
+ */
+function countCallSites(workspacePath, groups) {
+    let count = 0;
+    for (const group of groups.slice(0, MAX_REFERENCE_GROUPS)) {
+        const out = git(workspacePath, ["grep", "-l", "-F", "--", group.id]);
+        if (!out)
+            continue;
+        const files = out.split("\n").filter(Boolean);
+        // The files of the group mention their own path: they are not
+        // references to the group.
+        count += files.filter((file) => moduleOf(file) !== group.id).length;
+    }
+    return count;
+}
+/**
+ * A stable fingerprint of a set of files.
+ */
+export function fingerprintOf(files) {
+    const hash = createHash("sha256");
+    hash.update([...files].sort(comparePaths).join("\n"));
+    return hash.digest("hex").slice(0, 16);
+}
+/**
+ * The path fragments of a request.
+ *
+ * A hint is a place in the repository that the request names: a path with
+ * a separator, or a file name with a known extension. The measurement
+ * checks every hint against the tracked files, so a hint that names
+ * nothing is simply not used.
+ */
+export function scopeHintsFromText(text) {
+    const hints = new Set();
+    for (const match of text.match(/[\w.-]+(?:\/[\w.-]+)+/g) ?? []) {
+        hints.add(match.replace(/^\.\//, ""));
+    }
+    for (const match of text.match(/[\w-]+\.(?:ts|tsx|mts|cts|js|mjs|cjs|json|md|py|sh|yaml|yml)\b/g) ?? []) {
+        hints.add(match);
+    }
+    return [...hints].slice(0, 8);
+}
+/**
+ * Measure the scope of a task in the workspace.
+ */
+export function measureScope(options) {
+    const workspacePath = options.workspacePath;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const tracked = trackedFiles(workspacePath);
+    const hints = (options.hints ?? []).map((hint) => hint.trim()).filter(Boolean);
+    // The files the request names: a real match against the tracked paths.
+    const matchedHints = [];
+    const named = new Set();
+    for (const hint of hints) {
+        const needle = hint.toLowerCase();
+        let matched = false;
+        for (const file of tracked) {
+            if (!file.toLowerCase().includes(needle))
+                continue;
+            matched = true;
+            if (named.size < limit)
+                named.add(file);
+        }
+        if (matched)
+            matchedHints.push(hint);
+    }
+    // The files the session has changed: the scope that is already real.
+    const changed = (options.changedFiles ?? changedFiles(workspacePath)).filter((file) => tracked.includes(file));
+    let files = [];
+    let source = "none";
+    if (named.size > 0) {
+        files = [...named];
+        source = "request";
+    }
+    else if (changed.length > 0) {
+        files = changed.slice(0, limit);
+        source = "working-tree";
+    }
+    const groups = groupFiles(files);
+    const fileTypes = {};
+    for (const file of files) {
+        const extension = extensionOf(file);
+        if (!extension)
+            continue;
+        fileTypes[extension] = (fileTypes[extension] ?? 0) + 1;
+    }
+    return {
+        files: files.sort(comparePaths),
+        groups,
+        workspaceFiles: tracked.length,
+        callSites: countCallSites(workspacePath, groups),
+        fileTypes,
+        fingerprint: fingerprintOf(files),
+        matchedHints,
+        source,
+    };
+}
+//# sourceMappingURL=delegation-scope.js.map

package/packages/jev-judge/dist/delegation-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-scope.js","sourceRoot":"","sources":["../src/delegation-scope.ts"],"names":[],"mappings":"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"}

package/packages/jev-judge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/jev-judge",
-  "version": "1.1.451",
+  "version": "1.1.452",
   "description": "Jev Judge - Structured decision model for agent routing, E2E testing, and automated decisions",
   "type": "module",
   "main": "./dist/index.js",

package/packages/jev-judge/src/continuation-status.ts

@@ -0,0 +1,41 @@
+/**
+ * The lifecycle of a continuation that the harness dispatched.
+ *
+ * A continuation is a turn that the harness started itself. While that
+ * turn runs, the status says so: a timer that clears the status while the
+ * agent is still working would claim that nothing runs any more.
+ *
+ * The gate is the only thing that decides whether a continuation is still
+ * pending, so it can be read and tested without a session.
+ */
+export class ContinuationGate {
+	private inFlight = false;
+
+	/**
+	 * A continuation was dispatched.
+	 *
+	 * The status stays "RUN" from here until the turn settles.
+	 */
+	begin(): void {
+		this.inFlight = true;
+	}
+
+	/**
+	 * The turn settled.
+	 *
+	 * @returns True when a continuation was still pending, so the caller
+	 *   has to clear the status. False when there was nothing to clear.
+	 */
+	settle(): boolean {
+		if (!this.inFlight) return false;
+		this.inFlight = false;
+		return true;
+	}
+
+	/**
+	 * Whether a continuation is still running.
+	 */
+	get pending(): boolean {
+		return this.inFlight;
+	}
+}

package/packages/jev-judge/src/delegation-harness.ts

@@ -9,17 +9,34 @@ import { homedir as osHomedir } from "node:os";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+import type { ScopeMeasurement, ScopeWorkGroup } from "./delegation-scope.js";
 
 /**
  * Extension capability for delegation (inline to avoid dependency)
  */
 export interface ExtensionCapability {
-  name: string;
-  supportsSubagents: boolean;
-  supportsWorkIsolation: boolean;
-  supportsCancellation: boolean;
-  availableTools: string[];
-  verified: boolean;
+	name: string;
+	/** The tool that can dispatch a child. */
+	toolName: string;
+	supportsSubagents: boolean;
+	/**
+	 * The schema of the tool carries a parameter that isolates the work of
+	 * a child. Without such a parameter the claim is not made.
+	 */
+	supportsWorkIsolation: boolean;
+	/**
+	 * The schema of the tool carries a parameter that stops a child. Without
+	 * such a parameter the claim is not made.
+	 */
+	supportsCancellation: boolean;
+	availableTools: string[];
+	/**
+	 * The schema of the tool was read and the tool is active.
+	 *
+	 * This is not a proof that a child ever ran: it says that the session
+	 * can ask for one. Only a dispatch that was really sent proves that.
+	 */
+	verified: boolean;
 }
 
 /**
@@ -36,29 +53,52 @@ export type DelegationStrategy =
  * Delegation decision
  */
 export interface DelegationDecision {
-  strategy: DelegationStrategy;
-  reason: string;
-  workGroups: unknown[];
-  validationExpectations: string;
-  confidence: "high" | "medium" | "low";
-  jevUsed: boolean;
-  reassessmentTriggers: string[];
+	strategy: DelegationStrategy;
+	reason: string;
+	/**
+	 * The groups the work falls into. They are empty unless the scope was
+	 * measured: a decision without groups is not a delegation plan.
+	 */
+	workGroups: ScopeWorkGroup[];
+	validationExpectations: string;
+	confidence: "high" | "medium" | "low";
+	jevUsed: boolean;
+	/**
+	 * Whether a child was really dispatched.
+	 *
+	 * The harness assesses the work, it does not run it: the agent is the
+	 * one that sends the groups to the sub-agent tool.
+	 */
+	dispatched: boolean;
+	/**
+	 * The name of the active tool that can dispatch a child.
+	 *
+	 * It is empty when no such tool is active. The name is the proof that
+	 * the dispatch is possible, not the proof that it happened.
+	 */
+	dispatchTool?: string;
+	reassessmentTriggers: string[];
 }
 
 /**
  * Scope facts
  */
 export interface ScopeFacts {
-  estimatedFiles: number;
-  observedFiles: number;
-  estimatedCallSites: number;
-  observedCallSites: number;
-  independentComponents: number;
-  tightlyCoupled: boolean;
-  isMechanical: boolean;
-  isComplex: boolean;
-  fileTypes: Record<string, number>;
-  fingerprint: string;
+	estimatedFiles: number;
+	observedFiles: number;
+	estimatedCallSites: number;
+	observedCallSites: number;
+	independentComponents: number;
+	tightlyCoupled: boolean;
+	isMechanical: boolean;
+	isComplex: boolean;
+	fileTypes: Record<string, number>;
+	fingerprint: string;
+	/**
+	 * The measured groups of the work. A delegation decision needs them:
+	 * without groups there is nothing to hand to a child.
+	 */
+	workGroups: ScopeWorkGroup[];
 }
 
 /**
@@ -150,9 +190,149 @@ interface DelegationState {
 }
 
 /**
- * Sub-agent tool names
+ * The number of groups that can be handed to children at once.
+ *
+ * More groups than that is not a delegation plan: it is a list of files
+ * that still needs a decision about the order.
  */
-const SUBAGENT_TOOLS = ["subagent", "spawn", "delegate", "run_subagent"];
+const MAX_DELEGATED_GROUPS = 8;
+
+/**
+ * Build the scope facts from a measurement.
+ *
+ * Every number is a count of something the measurement found. The
+ * estimate is the size of the workspace: it is a real number, and it says
+ * how much of the repository the measured files are.
+ */
+export function scopeFactsFromMeasurement(measurement: ScopeMeasurement): ScopeFacts {
+	const groups = measurement.groups;
+	const extensions = Object.keys(measurement.fileTypes);
+	return {
+		estimatedFiles: measurement.workspaceFiles,
+		observedFiles: measurement.files.length,
+		estimatedCallSites: measurement.callSites,
+		observedCallSites: measurement.callSites,
+		independentComponents: groups.length,
+		tightlyCoupled: groups.length <= 1,
+		// A mechanical change touches one kind of file, and there is more
+		// than one of them: a rename across many files is mechanical, a
+		// single file is just work.
+		isMechanical: extensions.length === 1 && measurement.files.length >= 3,
+		// A complex change spans more than one module.
+		isComplex: groups.length > 1,
+		fileTypes: measurement.fileTypes,
+		fingerprint: measurement.fingerprint,
+		workGroups: groups,
+	};
+}
+
+/**
+ * The reason why the work stays in the session.
+ */
+function singleAgentReason(groups: ScopeWorkGroup[]): string {
+  if (groups.length === 1) {
+    return `One measured group (${groups[0].id}): the work stays in this session`;
+  }
+  if (groups.length > MAX_DELEGATED_GROUPS) {
+    return `${groups.length} measured groups: too many to hand out at once, the work stays in this session`;
+  }
+  return "No measured group of work: the work stays in this session";
+}
+
+/**
+ * Build the message that hands a delegation plan to the agent.
+ *
+ * The message names the measured groups and the tool that can dispatch a
+ * child. It does not claim that anything was dispatched: the harness
+ * measured the work, the agent is the one that sends the groups out.
+ *
+ * @param decision The decision of the assessment.
+ * @returns The message, or null when there is nothing to hand out.
+ */
+export function buildDelegationSteer(
+  decision: {
+    strategy: string;
+    workGroups?: { id: string; files: string[] }[];
+    dispatchTool?: string;
+  } | null,
+): string | null {
+  if (!decision) return null;
+  if (decision.strategy !== "delegate") return null;
+  const groups = decision.workGroups ?? [];
+  if (groups.length === 0) return null;
+
+  const lines = [
+    `[Delegation plan] The measured scope of this request falls into ${groups.length} independent group(s):`,
+    ...groups.map((group) => `- ${group.id} (${group.files.length} file(s))`),
+  ];
+  if (decision.dispatchTool) {
+    lines.push(
+      `Send each group to a child agent with the ${decision.dispatchTool} tool, then integrate the results and validate them.`,
+    );
+  } else {
+    lines.push("Send each group to a child agent, then integrate the results and validate them.");
+  }
+  lines.push("The harness measured the scope; it did not dispatch the groups itself.");
+  return lines.join("\n");
+}
+
+/**
+ * The parameters of a tool that dispatch a child.
+ *
+ * A tool that takes the task of a child can dispatch one. The name of the
+ * tool says nothing about that: only the schema does.
+ */
+const DISPATCH_PARAMETERS = ["task", "prompt", "instructions", "description"];
+
+/**
+ * The parameters of a tool that isolate the work of a child.
+ */
+const ISOLATION_PARAMETERS = ["cwd", "worktree", "isolation", "sandbox", "branch"];
+
+/**
+ * The parameters of a tool that stop a child.
+ */
+const CANCELLATION_PARAMETERS = ["timeout", "timeoutMs", "cancel", "signal", "abort"];
+
+/**
+ * The words that name a child agent.
+ */
+const CHILD_WORDS = ["subagent", "sub-agent", "child agent", "delegate", "spawn"];
+
+/**
+ * The property names of a tool schema.
+ *
+ * A schema is a plain object: the properties of the object, of every
+ * branch of a union, and of every item of an array.
+ */
+export function schemaPropertyNames(schema: unknown): Set<string> {
+	const names = new Set<string>();
+	const visit = (node: unknown): void => {
+		if (!node || typeof node !== "object") return;
+		const record = node as Record<string, unknown>;
+		const properties = record.properties;
+		if (properties && typeof properties === "object") {
+			for (const name of Object.keys(properties as Record<string, unknown>)) {
+				names.add(name);
+			}
+		}
+		for (const branch of ["anyOf", "oneOf", "allOf"]) {
+			const list = record[branch];
+			if (Array.isArray(list)) for (const entry of list) visit(entry);
+		}
+		const items = record.items;
+		if (items) visit(items);
+	};
+	visit(schema);
+	return names;
+}
+
+/**
+ * The text of a tool that names what the tool is for.
+ */
+function toolText(tool: { name?: string; description?: string }): string {
+	return `${tool.name ?? ""} ${tool.description ?? ""}`.toLowerCase();
+}
 
 /**
  * Create delegation harness integration
@@ -173,29 +353,42 @@ export function createDelegationHarness(
 
   /**
    * Discover and cache delegation capability
+   *
+   * The capability is read from the schema of the tools, not from their
+   * names: a tool that carries the task of a child can dispatch one, and
+   * only a schema that carries a working directory or a timeout proves
+   * that the work can be isolated or stopped.
    */
   async function discoverCapability(): Promise<ExtensionCapability | null> {
     if (state.capability) return state.capability;
 
     try {
       const allTools = pi.getAllTools();
-      const toolNames = allTools.map((t) => t.name);
-      const activeTools = pi.getActiveTools();
+      const activeTools = new Set(pi.getActiveTools());
 
-      const hasSubagentTool = SUBAGENT_TOOLS.some(
-        (tool) => toolNames.includes(tool) || activeTools.includes(tool)
-      );
+      for (const tool of allTools) {
+        const properties = schemaPropertyNames(tool.parameters);
+        const dispatches = DISPATCH_PARAMETERS.some((parameter) => properties.has(parameter));
+        if (!dispatches) continue;
+        // The tool has to be about a child agent: a schema that takes a
+        // task is not enough when the tool is something else entirely.
+        const text = toolText(tool);
+        if (!CHILD_WORDS.some((word) => text.includes(word))) continue;
+
+        const isolation = ISOLATION_PARAMETERS.find((parameter) => properties.has(parameter));
+        const cancellation = CANCELLATION_PARAMETERS.find((parameter) => properties.has(parameter));
+        const isActive = activeTools.has(tool.name);
 
-      if (hasSubagentTool) {
         state.capability = {
-          name: "subagent-extension",
+          name: tool.name,
+          toolName: tool.name,
           supportsSubagents: true,
-          supportsWorkIsolation: true,
-          supportsCancellation: true,
-          availableTools: activeTools.filter((t) =>
-            SUBAGENT_TOOLS.some((st) => t.includes(st))
-          ),
-          verified: true,
+          supportsWorkIsolation: isolation !== undefined,
+          supportsCancellation: cancellation !== undefined,
+          availableTools: isActive ? [tool.name] : [],
+          // The capability is verified when the tool is active: an inactive
+          // tool cannot dispatch anything.
+          verified: isActive,
         };
         return state.capability;
       }
@@ -208,8 +401,13 @@ export function createDelegationHarness(
 
   /**
    * Check if delegation assessment should be triggered
+   *
+   * The thresholds are compared with the measured scope. A scope that was
+   * not measured is never assessed: an empty measurement is not a small
+   * task, it is an unknown one.
    */
   function shouldAssess(facts: ScopeFacts): boolean {
+    if (facts.observedFiles <= 0) return false;
     if (facts.observedFiles >= minFiles) return true;
     if (facts.observedCallSites >= minCallSites) return true;
     if (facts.independentComponents >= minComponents) return true;
@@ -218,6 +416,10 @@ export function createDelegationHarness(
 
   /**
    * Make deterministic assessment
+   *
+   * The decision is built from the measured scope and from the schema of
+   * the tools. A strategy that claims a delegation needs the groups of the
+   * measurement: without them there is nothing to hand to a child.
    */
   function makeDeterministicAssessment(
     facts: ScopeFacts,
@@ -226,11 +428,12 @@ export function createDelegationHarness(
     if (!capability?.verified) {
       return {
         strategy: "unavailable",
-        reason: "No verified sub-agent capability",
+        reason: "No active tool can dispatch a child agent",
         workGroups: [],
         validationExpectations: "Parent handles validation",
         confidence: "high",
         jevUsed: false,
+        dispatched: false,
         reassessmentTriggers: ["Extension available"],
       };
     }
@@ -238,34 +441,40 @@ export function createDelegationHarness(
     if (facts.isMechanical && !facts.isComplex) {
       return {
         strategy: "script_only",
-        reason: "Mechanical transformation",
+        reason: `Mechanical transformation of ${facts.observedFiles} measured file(s)`,
         workGroups: [],
         validationExpectations: "Script output validation",
         confidence: "high",
         jevUsed: false,
+        dispatched: false,
         reassessmentTriggers: ["Transformation unreliable"],
       };
     }
 
-    if (facts.independentComponents >= 2 && !facts.tightlyCoupled) {
+    const groups = facts.workGroups ?? [];
+    if (groups.length >= 2 && groups.length <= MAX_DELEGATED_GROUPS && !facts.tightlyCoupled) {
       return {
         strategy: "delegate",
-        reason: `${facts.independentComponents} independent components`,
-        workGroups: [],
+        reason: `${groups.length} measured groups over ${facts.observedFiles} file(s); the agent dispatches the groups`,
+        workGroups: groups,
         validationExpectations: "Each group validated, then integrated",
         confidence: "medium",
         jevUsed: false,
+        // The harness measured the groups, it did not dispatch them.
+        dispatched: false,
+        dispatchTool: capability.toolName,
         reassessmentTriggers: ["Scope expands", "Coupling discovered"],
       };
     }
 
     return {
       strategy: "single_agent",
-      reason: "Default to single agent",
-      workGroups: [],
+      reason: singleAgentReason(groups),
+      workGroups: groups,
       validationExpectations: "Parent validates",
       confidence: "low",
       jevUsed: false,
+      dispatched: false,
       reassessmentTriggers: ["Scope exceeds threshold"],
     };
   }