@martinloop/mcp 0.3.3 → 0.3.5

package/dist/vendor/core/policy.js

@@ -78,7 +78,8 @@ export function classifyFailure(input) {
             failureClass: "environment_mismatch",
             rationale: "The adapter could not access the required local runtime or CLI tooling.",
             retryable: false,
-            recommendedIntervention: "switch_adapter"
+            recommendedIntervention: "switch_adapter",
+            diagnosticHint: diagnoseEnvironmentIssue(message)
         };
     }
     if (containsPositive(message, ["syntax error", "parse error", "typescript error"])) {
@@ -86,7 +87,8 @@ export function classifyFailure(input) {
             failureClass: "syntax_error",
             rationale: "The attempt failed on a parser or compiler-style issue.",
             retryable: true,
-            recommendedIntervention: "compress_context"
+            recommendedIntervention: "compress_context",
+            diagnosticHint: "Check for malformed edits — the verifier found a syntax or parse error in the changed files."
         };
     }
     if (containsPositive(message, [
@@ -104,7 +106,8 @@ export function classifyFailure(input) {
             failureClass: "repo_grounding_failure",
             rationale: "The attempt referenced modules, symbols, or files that are not grounded in the repo or approved docs.",
             retryable: true,
-            recommendedIntervention: repeatedFailure === "repo_grounding_failure" ? "tighten_task" : "run_verifier"
+            recommendedIntervention: repeatedFailure === "repo_grounding_failure" ? "tighten_task" : "run_verifier",
+            diagnosticHint: diagnoseGroundingIssue(message)
         };
     }
     if (containsPositive(message, [
@@ -118,7 +121,8 @@ export function classifyFailure(input) {
             failureClass: "verification_failure",
             rationale: "The proposed fix did not satisfy the verification gate.",
             retryable: true,
-            recommendedIntervention: repeatedFailure === "verification_failure" ? "tighten_task" : "run_verifier"
+            recommendedIntervention: repeatedFailure === "verification_failure" ? "tighten_task" : "run_verifier",
+            diagnosticHint: diagnoseVerificationIssue(message)
         };
     }
     if (containsPositive(message, [
@@ -192,6 +196,19 @@ export function evaluateCostGovernor(input) {
         remainingTokens
     };
 }
+export function calculateCostPerOutcome(input) {
+    const costPerAttempt = input.attemptCount > 0
+        ? roundUsd(input.totalCostUsd / input.attemptCount)
+        : 0;
+    return {
+        costPerAcceptedChange: input.accepted ? input.totalCostUsd : undefined,
+        costPerAttempt,
+        acceptanceRate: input.accepted ? 1 : 0,
+        wastedCoordinationUsd: input.accepted
+            ? roundUsd(input.preworkCostUsd)
+            : roundUsd(input.totalCostUsd)
+    };
+}
 export function inferExit(input) {
     if (input.lastResult.status === "completed" && input.lastResult.verification.passed) {
         return {
@@ -622,3 +639,66 @@ function computeDiffRiskScore(input) {
 function roundScore(value) {
     return Math.round(value * 100) / 100;
 }
+// ---------------------------------------------------------------------------
+// Diagnostic hint generators
+//
+// These extract actionable context from failure messages so the next attempt
+// gets a concrete diagnosis, not just "verification failed."
+// ---------------------------------------------------------------------------
+const KNOWN_TOOLS = {
+    bun: "npm install -g bun",
+    pnpm: "npm install -g pnpm",
+    yarn: "npm install -g yarn",
+    eslint: "npm install eslint",
+    vitest: "npm install vitest",
+    jest: "npm install jest",
+    tsc: "npm install typescript",
+    prettier: "npm install prettier",
+    biome: "npm install @biomejs/biome"
+};
+function diagnoseEnvironmentIssue(message) {
+    // Try to extract the missing command name
+    const cmdMatch = message.match(/(?:command not found|enoent)[:\s]*['"]?(\w[\w.-]*)/i)
+        ?? message.match(/['"](\w[\w.-]*)['"].*(?:not found|enoent)/i);
+    const missingCmd = cmdMatch?.[1];
+    if (missingCmd && KNOWN_TOOLS[missingCmd.toLowerCase()]) {
+        return `The verifier needs "${missingCmd}" which is not installed. Fix: ${KNOWN_TOOLS[missingCmd.toLowerCase()]}`;
+    }
+    if (missingCmd) {
+        return `The verifier could not find "${missingCmd}". Ensure it is installed in the workspace before retrying.`;
+    }
+    return "A required tool or command was not found in the environment. Check that all dependencies referenced by the verify command are installed.";
+}
+function diagnoseGroundingIssue(message) {
+    // Extract the missing module/symbol name
+    const moduleMatch = message.match(/cannot find module ['"]([^'"]+)['"]/i)
+        ?? message.match(/module not found[:\s]*['"]?([^\s'"]+)/i);
+    const nameMatch = message.match(/cannot find name ['"]?(\w+)/i);
+    if (moduleMatch?.[1]) {
+        const mod = moduleMatch[1];
+        const isRelative = mod.startsWith(".") || mod.startsWith("/");
+        if (isRelative) {
+            return `Import "${mod}" points to a file that does not exist. Check the path and filename.`;
+        }
+        return `Module "${mod}" is not installed. Run npm install or check package.json dependencies.`;
+    }
+    if (nameMatch?.[1]) {
+        return `Symbol "${nameMatch[1]}" is not defined. Check that the import exists and the name is spelled correctly.`;
+    }
+    return "The code references modules or symbols that do not exist in the repository. Verify imports and file paths.";
+}
+function diagnoseVerificationIssue(message) {
+    // Count assertion failures for severity signal
+    const assertionCount = (message.match(/assertionerror/gi) ?? []).length;
+    if (assertionCount > 3) {
+        return `${String(assertionCount)} assertion failures detected — the change may have introduced a regression. Focus on the specific test expectations that broke.`;
+    }
+    // Check for common patterns
+    if (/timeout/i.test(message) && !/budget/i.test(message)) {
+        return "Tests timed out. The change may have introduced an infinite loop or unresolved async operation.";
+    }
+    if (/exit code (?!0)\d+/i.test(message) || /exited with code/i.test(message)) {
+        return "The verifier command exited non-zero. Read the output above to identify which specific check failed and why.";
+    }
+    return "Verification did not pass. Review the verifier output for the specific failing assertion or check.";
+}

package/dist/vendor/core/rollback.js

@@ -134,17 +134,24 @@ function readRepoState(repoRoot) {
     };
 }
 function readGitLines(repoRoot, args) {
-    const result = spawnSync("git", args, {
-        cwd: repoRoot,
-        encoding: "utf8"
-    });
-    if (result.status !== 0 || typeof result.stdout !== "string") {
-        return [];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const result = spawnSync("git", args, {
+            cwd: repoRoot,
+            encoding: "utf8"
+        });
+        if (result.status === 0 && typeof result.stdout === "string") {
+            return uniqueSorted(result.stdout
+                .split(/\r?\n/u)
+                .map((line) => normalizeRepoPath(line))
+                .filter(Boolean));
+        }
+        // Retry once after a short delay — handles git lock-file contention
+        // that occurs when another process holds .git/index.lock.
+        if (attempt === 0 && result.status !== 0) {
+            spawnSync("sleep", ["0.5"], { encoding: "utf8" });
+        }
     }
-    return uniqueSorted(result.stdout
-        .split(/\r?\n/u)
-        .map((line) => normalizeRepoPath(line))
-        .filter(Boolean));
+    return [];
 }
 function readGitScalar(repoRoot, args) {
     const result = spawnSync("git", args, {
@@ -190,9 +197,22 @@ function restoreTrackedFileFromHead(repoRoot, filePath) {
         cwd: repoRoot,
         encoding: "utf8"
     });
-    if (result.status !== 0) {
-        throw new Error(result.stderr?.trim() || `git restore failed for ${filePath}`);
+    if (result.status === 0) {
+        return;
+    }
+    // Retry once after a short delay (git lock-file contention)
+    spawnSync("sleep", ["0.5"], { encoding: "utf8" });
+    const retry = spawnSync("git", ["restore", "--staged", "--worktree", "--source=HEAD", "--", filePath], { cwd: repoRoot, encoding: "utf8" });
+    if (retry.status === 0) {
+        return;
+    }
+    // Fallback: try git checkout which works on older git versions
+    const fallback = spawnSync("git", ["checkout", "HEAD", "--", filePath], { cwd: repoRoot, encoding: "utf8" });
+    if (fallback.status === 0) {
+        return;
     }
+    throw new Error(result.stderr?.trim() ||
+        `git restore failed for ${filePath} (retry and checkout fallback also failed)`);
 }
 async function removeRepoPath(repoRoot, filePath) {
     await rm(resolveRepoPath(repoRoot, filePath), { recursive: true, force: true });

package/dist/vendor/core/routing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Route classification and compression for governed agent runs.
+ *
+ * Decides whether a task needs manager/planner orchestration or can go
+ * directly to a worker, based on task complexity signals. Prevents
+ * wasted coordination cost (Pre Work Burn) on simple tasks.
+ */
+import type { RoutingMode, RoutingPolicy } from "../contracts/index.js";
+export interface RouteDecision {
+    selectedMode: RoutingMode;
+    confidence: number;
+    expectedCostUsd: number;
+    expectedPreworkBurnPct: number;
+    reason: string[];
+    blockedSteps: string[];
+    compressed: boolean;
+    compressionSummary?: string;
+}
+export interface RouteClassificationInput {
+    objective: string;
+    verificationPlan: string[];
+    repoRoot?: string;
+    allowedPaths?: string[];
+    deniedPaths?: string[];
+    budgetUsd: number;
+    policy?: Partial<RoutingPolicy>;
+    /** Number of files the task references or is scoped to. */
+    scopedFileCount?: number;
+    /** Historical success rate for similar tasks with direct execution (0-1). */
+    historicalDirectSuccessRate?: number;
+}
+export declare function classifyRoute(input: RouteClassificationInput): RouteDecision;
+/**
+ * Checks whether a run's Pre Work Burn exceeds the routing policy limits.
+ * Returns a block reason if exceeded, undefined if within bounds.
+ */
+export declare function evaluatePreworkBurnPolicy(preworkCostUsd: number, totalCostUsd: number, policy?: Partial<RoutingPolicy>): {
+    exceeded: boolean;
+    reason?: string;
+};

package/dist/vendor/core/routing.js

@@ -0,0 +1,185 @@
+/**
+ * Route classification and compression for governed agent runs.
+ *
+ * Decides whether a task needs manager/planner orchestration or can go
+ * directly to a worker, based on task complexity signals. Prevents
+ * wasted coordination cost (Pre Work Burn) on simple tasks.
+ */
+import { DEFAULT_ROUTING_POLICY } from "../contracts/index.js";
+const SECURITY_KEYWORDS = [
+    "auth", "authentication", "authorization", "credential", "secret",
+    "token", "password", "oauth", "jwt", "session", "csrf", "xss",
+    "injection", "encryption", "certificate", "tls", "ssl", "permission"
+];
+const ARCHITECTURE_KEYWORDS = [
+    "refactor", "architecture", "redesign", "restructure", "migration",
+    "database schema", "api design", "service boundary", "microservice",
+    "event sourcing", "cqrs", "distributed"
+];
+const MIGRATION_KEYWORDS = [
+    "migration", "migrate", "upgrade", "downgrade", "schema change",
+    "data migration", "database migration", "breaking change"
+];
+const MULTI_FILE_KEYWORDS = [
+    "across", "all files", "every file", "codebase-wide", "global",
+    "rename everywhere", "update all", "system-wide"
+];
+function extractComplexitySignals(input) {
+    const lower = input.objective.toLowerCase();
+    return {
+        objectiveLength: input.objective.length,
+        fileCount: input.scopedFileCount ?? estimateFileCount(input),
+        hasSecurityKeywords: SECURITY_KEYWORDS.some((kw) => lower.includes(kw)),
+        hasArchitectureKeywords: ARCHITECTURE_KEYWORDS.some((kw) => lower.includes(kw)),
+        hasMigrationKeywords: MIGRATION_KEYWORDS.some((kw) => lower.includes(kw)),
+        hasMultiFileKeywords: MULTI_FILE_KEYWORDS.some((kw) => lower.includes(kw)),
+        verifierCount: input.verificationPlan.length,
+        budgetUsd: input.budgetUsd,
+        scopeRestricted: (input.allowedPaths?.length ?? 0) > 0 || (input.deniedPaths?.length ?? 0) > 0
+    };
+}
+function estimateFileCount(input) {
+    const pathCount = (input.allowedPaths?.length ?? 0) + (input.deniedPaths?.length ?? 0);
+    if (pathCount > 0)
+        return pathCount;
+    // Heuristic: short objectives with specific file refs → 1-2 files
+    const fileRefs = input.objective.match(/[\w/.-]+\.\w{1,5}/g);
+    return fileRefs?.length ?? 1;
+}
+// ---------------------------------------------------------------------------
+// Confidence scoring
+// ---------------------------------------------------------------------------
+function calculateDirectConfidence(signals, input) {
+    let confidence = 0.7; // Base: most tasks can go direct
+    // Boost for simple tasks
+    if (signals.objectiveLength < 200)
+        confidence += 0.1;
+    if (signals.fileCount <= 2)
+        confidence += 0.1;
+    if (signals.scopeRestricted)
+        confidence += 0.05;
+    if (signals.verifierCount === 1)
+        confidence += 0.05;
+    // Penalize for complex tasks
+    if (signals.hasSecurityKeywords)
+        confidence -= 0.25;
+    if (signals.hasArchitectureKeywords)
+        confidence -= 0.2;
+    if (signals.hasMigrationKeywords)
+        confidence -= 0.3;
+    if (signals.hasMultiFileKeywords)
+        confidence -= 0.15;
+    if (signals.objectiveLength > 500)
+        confidence -= 0.1;
+    if (signals.fileCount > 5)
+        confidence -= 0.15;
+    if (signals.budgetUsd > 10)
+        confidence -= 0.1;
+    // Historical evidence
+    if (input.historicalDirectSuccessRate !== undefined) {
+        confidence = confidence * 0.6 + input.historicalDirectSuccessRate * 0.4;
+    }
+    return Math.max(0, Math.min(1, confidence));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function classifyRoute(input) {
+    const policy = { ...DEFAULT_ROUTING_POLICY, ...input.policy };
+    const signals = extractComplexitySignals(input);
+    const directConfidence = calculateDirectConfidence(signals, input);
+    const reason = [];
+    const blockedSteps = [];
+    // Policy override: forced mode
+    if (policy.mode === "direct") {
+        return {
+            selectedMode: "direct",
+            confidence: 1,
+            expectedCostUsd: estimateDirectCost(input.budgetUsd),
+            expectedPreworkBurnPct: 5,
+            reason: ["Policy forces direct execution mode."],
+            blockedSteps: ["manager", "planner", "router", "consensus"],
+            compressed: true,
+            compressionSummary: "Policy: direct mode — skipping all orchestration."
+        };
+    }
+    if (policy.mode === "consensus") {
+        return {
+            selectedMode: "consensus",
+            confidence: 0.5,
+            expectedCostUsd: input.budgetUsd * 0.8,
+            expectedPreworkBurnPct: 35,
+            reason: ["Policy forces consensus mode."],
+            blockedSteps: [],
+            compressed: false
+        };
+    }
+    // Adaptive routing
+    if (directConfidence >= policy.skipOrchestrationIfConfidenceAbove) {
+        reason.push(`Direct confidence ${(directConfidence * 100).toFixed(0)}% exceeds threshold ${(policy.skipOrchestrationIfConfidenceAbove * 100).toFixed(0)}%.`);
+        if (signals.objectiveLength < 200)
+            reason.push("Short, focused objective.");
+        if (signals.fileCount <= 2)
+            reason.push(`Scoped to ${String(signals.fileCount)} file(s).`);
+        if (signals.scopeRestricted)
+            reason.push("Path scope is restricted.");
+        blockedSteps.push("manager", "consensus");
+        return {
+            selectedMode: "direct",
+            confidence: directConfidence,
+            expectedCostUsd: estimateDirectCost(input.budgetUsd),
+            expectedPreworkBurnPct: 8,
+            reason,
+            blockedSteps,
+            compressed: true,
+            compressionSummary: `Compressed from manager→planner→worker to direct worker. Estimated savings: ${String(Math.round(input.budgetUsd * 0.3 * 100) / 100)} USD.`
+        };
+    }
+    // Complex task — needs orchestration
+    if (signals.hasSecurityKeywords)
+        reason.push("Security-sensitive task detected.");
+    if (signals.hasMigrationKeywords)
+        reason.push("Migration task detected.");
+    if (signals.hasArchitectureKeywords)
+        reason.push("Architectural scope detected.");
+    if (signals.fileCount > 5)
+        reason.push(`Touches ${String(signals.fileCount)}+ files.`);
+    const needsConsensus = signals.hasSecurityKeywords && signals.hasMigrationKeywords;
+    return {
+        selectedMode: needsConsensus ? "consensus" : "manager",
+        confidence: directConfidence,
+        expectedCostUsd: input.budgetUsd * (needsConsensus ? 0.8 : 0.6),
+        expectedPreworkBurnPct: needsConsensus ? 40 : 25,
+        reason,
+        blockedSteps: needsConsensus ? [] : ["consensus"],
+        compressed: false
+    };
+}
+function estimateDirectCost(budgetUsd) {
+    // Direct execution typically uses 30-50% of budget
+    return Math.round(budgetUsd * 0.35 * 100) / 100;
+}
+/**
+ * Checks whether a run's Pre Work Burn exceeds the routing policy limits.
+ * Returns a block reason if exceeded, undefined if within bounds.
+ */
+export function evaluatePreworkBurnPolicy(preworkCostUsd, totalCostUsd, policy = {}) {
+    const resolved = { ...DEFAULT_ROUTING_POLICY, ...policy };
+    if (!resolved.enabled) {
+        return { exceeded: false };
+    }
+    if (preworkCostUsd > resolved.maxPreworkCostUsd) {
+        return {
+            exceeded: true,
+            reason: `Pre-work cost $${preworkCostUsd.toFixed(2)} exceeds routing policy cap of $${resolved.maxPreworkCostUsd.toFixed(2)}.`
+        };
+    }
+    const burnPct = totalCostUsd > 0 ? (preworkCostUsd / totalCostUsd) * 100 : 0;
+    if (burnPct > resolved.maxPreworkBudgetPct) {
+        return {
+            exceeded: true,
+            reason: `Pre Work Burn at ${burnPct.toFixed(0)}% exceeds routing policy cap of ${String(resolved.maxPreworkBudgetPct)}%.`
+        };
+    }
+    return { exceeded: false };
+}

package/dist/vendor/core/trajectory.d.ts

@@ -0,0 +1,18 @@
+import { type CircuitBreakDecision, type TrajectoryAssessment } from "../contracts/index.js";
+export declare function assessTrajectory(input: {
+    objective: string;
+    verificationPlan?: string[];
+    attempts: TrajectoryAttemptLike[];
+}): TrajectoryAssessment;
+export declare function decideCircuitBreak(input: {
+    objective: string;
+    verificationPlan?: string[];
+    attempts: TrajectoryAttemptLike[];
+    remainingIterations?: number;
+}): CircuitBreakDecision;
+interface TrajectoryAttemptLike {
+    index: number;
+    summary?: string;
+    failureClass?: string;
+}
+export {};