@martinloop/mcp 0.3.5 → 0.3.6

package/dist/vendor/core/persistence/trace-store.js

@@ -0,0 +1,125 @@
+/**
+ * Append-Only Trace Store
+ *
+ * Aggregates run data over time to build institutional memory. Every governed
+ * run's routing decision, cost, failure class, and outcome is appended to a
+ * local JSONL trace file. Data is NEVER overwritten — only appended.
+ *
+ * The trace store feeds:
+ * - classifyRoute() with historicalDirectSuccessRate from real past runs
+ * - Cost prediction models with actual spend data
+ * - Failure pattern detection across runs
+ * - Team analytics and optimization recommendations
+ *
+ * Storage: `<runsRoot>/_martin/trace-log.jsonl` (one JSON object per line)
+ */
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const TRACE_DIRECTORY = "_martin";
+const TRACE_FILENAME = "trace-log.jsonl";
+function resolveTracePath(runsRoot) {
+    return join(resolve(runsRoot), TRACE_DIRECTORY, TRACE_FILENAME);
+}
+/**
+ * Append a trace entry to the local trace store. Never overwrites.
+ */
+export async function appendTraceEntry(runsRoot, entry) {
+    const tracePath = resolveTracePath(runsRoot);
+    await mkdir(join(resolve(runsRoot), TRACE_DIRECTORY), { recursive: true });
+    const line = JSON.stringify(entry) + "\n";
+    await appendFile(tracePath, line, "utf8");
+}
+/**
+ * Read all trace entries from the local trace store.
+ */
+export async function readTraceEntries(runsRoot) {
+    const tracePath = resolveTracePath(runsRoot);
+    try {
+        const raw = await readFile(tracePath, "utf8");
+        return raw
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Aggregate trace entries into summary statistics.
+ * Used by classifyRoute() to get historicalDirectSuccessRate.
+ */
+export function aggregateTraces(entries) {
+    if (entries.length === 0) {
+        return {
+            totalRuns: 0,
+            directRuns: 0,
+            managerRuns: 0,
+            consensusRuns: 0,
+            directSuccessRate: 0,
+            managerSuccessRate: 0,
+            averageCostUsd: 0,
+            averagePreWorkBurnPct: 0,
+            totalSpendUsd: 0,
+            totalSavedUsd: 0,
+            topFailureClasses: [],
+            averageAttemptsPerRun: 0,
+            lastUpdated: new Date().toISOString()
+        };
+    }
+    const direct = entries.filter((e) => e.selectedRoute === "direct");
+    const manager = entries.filter((e) => e.selectedRoute === "manager");
+    const consensus = entries.filter((e) => e.selectedRoute === "consensus");
+    const directSuccesses = direct.filter((e) => e.status === "completed" && e.verificationPassed);
+    const managerSuccesses = manager.filter((e) => e.status === "completed" && e.verificationPassed);
+    const totalCost = entries.reduce((sum, e) => sum + e.actualCostUsd, 0);
+    const totalBudget = entries.reduce((sum, e) => sum + e.budgetUsd, 0);
+    const totalAttempts = entries.reduce((sum, e) => sum + e.attempts, 0);
+    const totalBurnPct = entries.reduce((sum, e) => sum + e.preWorkBurnPct, 0);
+    // Count failure classes
+    const failureCounts = new Map();
+    for (const entry of entries) {
+        if (entry.failureClass) {
+            failureCounts.set(entry.failureClass, (failureCounts.get(entry.failureClass) ?? 0) + 1);
+        }
+    }
+    const topFailureClasses = [...failureCounts.entries()]
+        .map(([failureClass, count]) => ({ failureClass, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 10);
+    return {
+        totalRuns: entries.length,
+        directRuns: direct.length,
+        managerRuns: manager.length,
+        consensusRuns: consensus.length,
+        directSuccessRate: direct.length > 0 ? directSuccesses.length / direct.length : 0,
+        managerSuccessRate: manager.length > 0 ? managerSuccesses.length / manager.length : 0,
+        averageCostUsd: Math.round((totalCost / entries.length) * 100) / 100,
+        averagePreWorkBurnPct: Math.round(totalBurnPct / entries.length),
+        totalSpendUsd: Math.round(totalCost * 100) / 100,
+        totalSavedUsd: Math.round((totalBudget - totalCost) * 100) / 100,
+        topFailureClasses,
+        averageAttemptsPerRun: Math.round((totalAttempts / entries.length) * 10) / 10,
+        lastUpdated: entries[entries.length - 1]?.timestamp ?? new Date().toISOString()
+    };
+}
+/**
+ * Get the historical direct success rate for use in route classification.
+ * Returns undefined if insufficient data (< 5 runs).
+ */
+export async function getHistoricalDirectSuccessRate(runsRoot) {
+    const entries = await readTraceEntries(runsRoot);
+    const directRuns = entries.filter((e) => e.selectedRoute === "direct");
+    if (directRuns.length < 5)
+        return undefined;
+    const successes = directRuns.filter((e) => e.status === "completed" && e.verificationPassed);
+    return successes.length / directRuns.length;
+}

package/dist/vendor/core/repo-analyzer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Repo Style Analyzer
+ *
+ * Scans a repository to detect coding conventions, patterns, and style
+ * so that governed agent runs produce code matching the existing codebase.
+ *
+ * Detects:
+ * - Naming conventions (camelCase, snake_case, PascalCase, kebab-case)
+ * - Test framework (Vitest, Jest, Mocha, node:test)
+ * - Package manager (pnpm, npm, yarn, bun)
+ * - Module system (ESM, CJS, mixed)
+ * - File organization pattern (feature folders, type folders, flat)
+ * - TypeScript strictness level
+ * - Comment density
+ * - Formatting (tabs vs spaces, semicolons, quotes)
+ */
+export interface RepoStyleProfile {
+    /** Detected package manager */
+    packageManager: "pnpm" | "npm" | "yarn" | "bun" | "unknown";
+    /** Detected module system */
+    moduleSystem: "esm" | "cjs" | "mixed" | "unknown";
+    /** Detected test framework */
+    testFramework: "vitest" | "jest" | "mocha" | "node-test" | "unknown";
+    /** Primary language */
+    language: "typescript" | "javascript" | "mixed";
+    /** TypeScript strict mode enabled */
+    typescriptStrict: boolean;
+    /** Dominant naming convention for files */
+    fileNaming: "kebab-case" | "camelCase" | "PascalCase" | "snake_case" | "mixed";
+    /** Dominant naming convention for variables/functions */
+    codeNaming: "camelCase" | "snake_case" | "mixed";
+    /** Uses semicolons */
+    semicolons: boolean;
+    /** Single vs double quotes */
+    quotes: "single" | "double" | "mixed";
+    /** Indentation style */
+    indentation: "tabs" | "2-spaces" | "4-spaces" | "mixed";
+    /** Average lines per file (source files) */
+    avgLinesPerFile: number;
+    /** File organization pattern */
+    organization: "feature-folders" | "type-folders" | "flat" | "mixed";
+    /** Raw signals for prompt injection */
+    promptDirectives: string[];
+}
+/**
+ * Analyze a repository and return a style profile.
+ */
+export declare function analyzeRepoStyle(rootDir: string): RepoStyleProfile;
+/**
+ * Build prompt directives from the style profile.
+ * These get injected into the agent's prompt to match repo conventions.
+ */
+export declare function buildPromptDirectives(profile: RepoStyleProfile): string[];

package/dist/vendor/core/repo-analyzer.js

@@ -0,0 +1,263 @@
+/**
+ * Repo Style Analyzer
+ *
+ * Scans a repository to detect coding conventions, patterns, and style
+ * so that governed agent runs produce code matching the existing codebase.
+ *
+ * Detects:
+ * - Naming conventions (camelCase, snake_case, PascalCase, kebab-case)
+ * - Test framework (Vitest, Jest, Mocha, node:test)
+ * - Package manager (pnpm, npm, yarn, bun)
+ * - Module system (ESM, CJS, mixed)
+ * - File organization pattern (feature folders, type folders, flat)
+ * - TypeScript strictness level
+ * - Comment density
+ * - Formatting (tabs vs spaces, semicolons, quotes)
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, extname } from "node:path";
+/**
+ * Analyze a repository and return a style profile.
+ */
+export function analyzeRepoStyle(rootDir) {
+    const profile = {
+        packageManager: detectPackageManager(rootDir),
+        moduleSystem: detectModuleSystem(rootDir),
+        testFramework: detectTestFramework(rootDir),
+        language: detectLanguage(rootDir),
+        typescriptStrict: detectTypeScriptStrict(rootDir),
+        fileNaming: "kebab-case",
+        codeNaming: "camelCase",
+        semicolons: true,
+        quotes: "double",
+        indentation: "2-spaces",
+        avgLinesPerFile: 0,
+        organization: "mixed",
+        promptDirectives: []
+    };
+    // Sample source files for style detection
+    const sourceFiles = collectSourceFiles(rootDir, 50);
+    if (sourceFiles.length > 0) {
+        const styleSignals = analyzeSourceFiles(sourceFiles);
+        profile.fileNaming = styleSignals.fileNaming;
+        profile.codeNaming = styleSignals.codeNaming;
+        profile.semicolons = styleSignals.semicolons;
+        profile.quotes = styleSignals.quotes;
+        profile.indentation = styleSignals.indentation;
+        profile.avgLinesPerFile = styleSignals.avgLinesPerFile;
+    }
+    profile.organization = detectOrganization(rootDir);
+    profile.promptDirectives = buildPromptDirectives(profile);
+    return profile;
+}
+function detectPackageManager(rootDir) {
+    if (existsSync(join(rootDir, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(join(rootDir, "bun.lockb")) || existsSync(join(rootDir, "bun.lock")))
+        return "bun";
+    if (existsSync(join(rootDir, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(rootDir, "package-lock.json")))
+        return "npm";
+    return "unknown";
+}
+function detectModuleSystem(rootDir) {
+    const pkgPath = join(rootDir, "package.json");
+    if (!existsSync(pkgPath))
+        return "unknown";
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.type === "module")
+            return "esm";
+        if (pkg.type === "commonjs")
+            return "cjs";
+    }
+    catch { /* ignore */ }
+    return "unknown";
+}
+function detectTestFramework(rootDir) {
+    const pkgPath = join(rootDir, "package.json");
+    if (!existsSync(pkgPath))
+        return "unknown";
+    try {
+        const raw = readFileSync(pkgPath, "utf8");
+        if (raw.includes("vitest"))
+            return "vitest";
+        if (raw.includes("jest"))
+            return "jest";
+        if (raw.includes("mocha"))
+            return "mocha";
+        if (raw.includes("node:test"))
+            return "node-test";
+    }
+    catch { /* ignore */ }
+    if (existsSync(join(rootDir, "vitest.config.ts")) || existsSync(join(rootDir, "vitest.config.js")))
+        return "vitest";
+    if (existsSync(join(rootDir, "jest.config.ts")) || existsSync(join(rootDir, "jest.config.js")))
+        return "jest";
+    return "unknown";
+}
+function detectLanguage(rootDir) {
+    if (existsSync(join(rootDir, "tsconfig.json")) ||
+        existsSync(join(rootDir, "tsconfig.base.json")) ||
+        existsSync(join(rootDir, "tsconfig.build.json"))) {
+        return "typescript";
+    }
+    return "javascript";
+}
+function detectTypeScriptStrict(rootDir) {
+    const candidates = ["tsconfig.json", "tsconfig.base.json", "tsconfig.build.json"];
+    for (const candidate of candidates) {
+        const tsConfigPath = join(rootDir, candidate);
+        if (!existsSync(tsConfigPath))
+            continue;
+        try {
+            const raw = readFileSync(tsConfigPath, "utf8");
+            if (raw.includes('"strict": true') || raw.includes('"strict":true'))
+                return true;
+        }
+        catch { /* skip */ }
+    }
+    return false;
+}
+function collectSourceFiles(rootDir, limit) {
+    const results = [];
+    const extensions = new Set([".ts", ".tsx", ".js", ".jsx"]);
+    function walk(dir, depth) {
+        if (depth > 5 || results.length >= limit)
+            return;
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (results.length >= limit)
+                    return;
+                if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
+                    continue;
+                const fullPath = join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(fullPath, depth + 1);
+                }
+                else if (entry.isFile() && extensions.has(extname(entry.name))) {
+                    results.push(fullPath);
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    walk(rootDir, 0);
+    return results;
+}
+function analyzeSourceFiles(files) {
+    let semiCount = 0;
+    let noSemiCount = 0;
+    let singleQuoteCount = 0;
+    let doubleQuoteCount = 0;
+    let tabCount = 0;
+    let twoSpaceCount = 0;
+    let fourSpaceCount = 0;
+    let totalLines = 0;
+    for (const filePath of files) {
+        try {
+            const content = readFileSync(filePath, "utf8");
+            const lines = content.split("\n");
+            totalLines += lines.length;
+            for (const line of lines.slice(0, 100)) {
+                if (line.trimEnd().endsWith(";"))
+                    semiCount++;
+                else if (line.trim().length > 0)
+                    noSemiCount++;
+                if (/'\w/.test(line))
+                    singleQuoteCount++;
+                if (/"\w/.test(line))
+                    doubleQuoteCount++;
+                if (line.startsWith("\t"))
+                    tabCount++;
+                else if (line.startsWith("  ") && !line.startsWith("    "))
+                    twoSpaceCount++;
+                else if (line.startsWith("    "))
+                    fourSpaceCount++;
+            }
+        }
+        catch { /* skip */ }
+    }
+    const semicolons = semiCount > noSemiCount;
+    const quotes = singleQuoteCount > doubleQuoteCount * 2 ? "single" :
+        doubleQuoteCount > singleQuoteCount * 2 ? "double" : "mixed";
+    const indentation = tabCount > twoSpaceCount + fourSpaceCount ? "tabs" :
+        twoSpaceCount > fourSpaceCount * 2 ? "2-spaces" :
+            fourSpaceCount > twoSpaceCount * 2 ? "4-spaces" : "mixed";
+    return {
+        fileNaming: "kebab-case", // Default, hard to detect reliably without more files
+        codeNaming: "camelCase", // TypeScript default
+        semicolons,
+        quotes,
+        indentation,
+        avgLinesPerFile: files.length > 0 ? Math.round(totalLines / files.length) : 0
+    };
+}
+function detectOrganization(rootDir) {
+    const srcDir = join(rootDir, "src");
+    if (!existsSync(srcDir))
+        return "flat";
+    try {
+        const entries = readdirSync(srcDir, { withFileTypes: true });
+        const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+        const hasFeatureDirs = dirs.some((d) => !["utils", "lib", "types", "helpers", "common", "shared", "__tests__", "tests"].includes(d));
+        const hasTypeDirs = dirs.some((d) => ["components", "hooks", "services", "models", "controllers", "routes", "middleware"].includes(d));
+        if (hasFeatureDirs && !hasTypeDirs)
+            return "feature-folders";
+        if (hasTypeDirs && !hasFeatureDirs)
+            return "type-folders";
+        if (hasFeatureDirs && hasTypeDirs)
+            return "mixed";
+    }
+    catch { /* skip */ }
+    return "flat";
+}
+/**
+ * Build prompt directives from the style profile.
+ * These get injected into the agent's prompt to match repo conventions.
+ */
+export function buildPromptDirectives(profile) {
+    const directives = [];
+    if (profile.language === "typescript") {
+        directives.push("Write TypeScript, not JavaScript.");
+        if (profile.typescriptStrict) {
+            directives.push("TypeScript strict mode is enabled. Use explicit types, avoid any.");
+        }
+    }
+    if (profile.moduleSystem === "esm") {
+        directives.push("Use ES module imports (import/export), not require().");
+    }
+    else if (profile.moduleSystem === "cjs") {
+        directives.push("Use CommonJS (require/module.exports), not ES module imports.");
+    }
+    if (profile.testFramework !== "unknown") {
+        directives.push(`Use ${profile.testFramework} for tests. Do not introduce a different test framework.`);
+    }
+    if (profile.semicolons) {
+        directives.push("Use semicolons at the end of statements.");
+    }
+    else {
+        directives.push("Do not use semicolons at the end of statements.");
+    }
+    if (profile.quotes === "single") {
+        directives.push("Use single quotes for strings.");
+    }
+    else if (profile.quotes === "double") {
+        directives.push("Use double quotes for strings.");
+    }
+    if (profile.indentation === "tabs") {
+        directives.push("Use tabs for indentation.");
+    }
+    else if (profile.indentation === "2-spaces") {
+        directives.push("Use 2-space indentation.");
+    }
+    else if (profile.indentation === "4-spaces") {
+        directives.push("Use 4-space indentation.");
+    }
+    if (profile.packageManager !== "unknown") {
+        directives.push(`This project uses ${profile.packageManager}. Do not use other package managers.`);
+    }
+    return directives;
+}

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

@@ -15,6 +15,14 @@ export interface RouteDecision {
     blockedSteps: string[];
     compressed: boolean;
     compressionSummary?: string;
+    /**
+     * Recommended model tier based on task complexity and route.
+     * Follows cost-aware routing: direct → haiku/sonnet, manager → sonnet,
+     * consensus → opus. Never use a more expensive model than the task needs.
+     */
+    recommendedModelTier: "haiku" | "sonnet" | "opus";
+    /** Estimated cost saving vs always using sonnet */
+    estimatedSavingVsSonnetUsd: number;
 }
 export interface RouteClassificationInput {
     objective: string;
@@ -29,6 +37,40 @@ export interface RouteClassificationInput {
     /** Historical success rate for similar tasks with direct execution (0-1). */
     historicalDirectSuccessRate?: number;
 }
+/**
+ * Resolve a tier to a concrete model ID for a specific engine.
+ * Allows downstream adapters to switch models automatically.
+ */
+export declare function resolveModelForTier(tier: RouteDecision["recommendedModelTier"], engine: "claude" | "codex" | "gemini" | "openai" | string): string;
+/**
+ * Available engine registry — describes what's installed and its capability.
+ * Populated by doctor/preflight from PATH and env var detection.
+ */
+export interface AvailableEngine {
+    id: string;
+    available: boolean;
+    /** Cost tier: cheap < mid < expensive */
+    costTier: "cheap" | "mid" | "expensive";
+    /** Capability tier: determines which task types this engine can handle */
+    capabilityTier: "haiku" | "sonnet" | "opus";
+}
+/**
+ * Select the best available engine for a given tier requirement.
+ *
+ * When multiple engines are available, picks the cheapest that meets
+ * the capability requirement. Falls back gracefully:
+ * - If required tier unavailable, upgrades to next tier of same engine
+ * - If only one engine family available, uses its best equivalent
+ *
+ * @param requiredTier - Minimum capability tier needed
+ * @param availableEngines - What's installed and authenticated
+ * @returns Best engine ID and concrete model to use
+ */
+export declare function selectBestEngine(requiredTier: RouteDecision["recommendedModelTier"], availableEngines: AvailableEngine[]): {
+    engineId: string;
+    model: string;
+    reasoning: string;
+};
 export declare function classifyRoute(input: RouteClassificationInput): RouteDecision;
 /**
  * Checks whether a run's Pre Work Burn exceeds the routing policy limits.