martin-loop 0.1.2 → 0.1.4

package/dist/vendor/core/compiler.js

@@ -0,0 +1,47 @@
+import { redactSecretsFromText } from "./leash.js";
+/**
+ * Compiles a deterministic PromptPacket from a MartinAdapterRequest.
+ * This is the context compiler — takes structured request state and produces
+ * a reconstructable packet (no chat history required).
+ */
+export function compilePromptPacket(request) {
+    const priorFailurePatterns = request.previousAttempts
+        .filter((a) => a.failureClass && a.intervention)
+        .map((a) => `${a.failureClass}:${a.intervention}`);
+    const guidanceParts = [
+        "Only modify files directly required to satisfy the contract.",
+        "Do not touch files outside the allowed paths."
+    ];
+    if (request.context.allowedPaths && request.context.allowedPaths.length > 0) {
+        guidanceParts.push(`Allowed paths: ${request.context.allowedPaths.join(", ")}.`);
+    }
+    if (request.context.deniedPaths && request.context.deniedPaths.length > 0) {
+        guidanceParts.push(`Denied paths (never touch): ${request.context.deniedPaths.join(", ")}.`);
+    }
+    if (priorFailurePatterns.length > 0) {
+        guidanceParts.push(`Prior failure patterns: ${priorFailurePatterns.join(", ")}. Adjust strategy accordingly.`);
+    }
+    return {
+        loopId: request.loopId,
+        attemptNumber: request.previousAttempts.length + 1,
+        contract: {
+            objective: redactSecretsFromText(request.context.objective),
+            verificationPlan: request.context.verificationPlan,
+            ...(request.context.allowedPaths ? { allowedPaths: request.context.allowedPaths } : {}),
+            ...(request.context.deniedPaths ? { deniedPaths: request.context.deniedPaths } : {}),
+            ...(request.context.acceptanceCriteria
+                ? {
+                    acceptanceCriteria: request.context.acceptanceCriteria.map((criterion) => redactSecretsFromText(criterion))
+                }
+                : {})
+        },
+        priorFailurePatterns,
+        guidance: guidanceParts.join(" "),
+        budgetEnvelope: {
+            remainingBudgetUsd: request.context.remainingBudgetUsd,
+            remainingIterations: request.context.remainingIterations,
+            remainingTokens: request.context.remainingTokens
+        }
+    };
+}
+//# sourceMappingURL=compiler.js.map

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

@@ -0,0 +1,37 @@
+export interface RepoGroundingFile {
+    path: string;
+    symbols: string[];
+    keywords: string[];
+}
+export interface RepoGroundingIndex {
+    schemaVersion: "martin.grounding.v1";
+    repoRoot: string;
+    createdAt: string;
+    fileCount: number;
+    files: RepoGroundingFile[];
+}
+export interface RepoGroundingHit {
+    path: string;
+    score: number;
+    matchedTerms: string[];
+    symbols: string[];
+}
+export declare function loadOrBuildRepoGroundingIndex(repoRoot: string): Promise<RepoGroundingIndex>;
+export declare function buildRepoGroundingIndex(repoRoot: string): Promise<RepoGroundingIndex>;
+export declare function queryRepoGroundingIndex(index: RepoGroundingIndex, query: string, limit?: number): RepoGroundingHit[];
+export type GroundingViolationKind = "file_not_found" | "symbol_not_found" | "import_not_found" | "patch_outside_allowed_paths";
+export interface GroundingViolation {
+    kind: GroundingViolationKind;
+    reference: string;
+    sourceHint?: string;
+}
+export interface GroundingScanResult {
+    violations: GroundingViolation[];
+    scannedReferences: number;
+    resolvedFiles: string[];
+    /** True when the diff adds only comments, whitespace, or empty lines — no substantive code. */
+    contentOnly: boolean;
+}
+export declare function scanPatchForGroundingViolations(diff: string, index: RepoGroundingIndex, options?: {
+    allowedPaths?: string[];
+}): GroundingScanResult;

package/dist/vendor/core/grounding.js

@@ -0,0 +1,270 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { extname, join, relative } from "node:path";
+const TEXT_EXTENSIONS = new Set([
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".json", ".md", ".yaml", ".yml", ".py", ".go",
+    ".rs", ".java", ".sh"
+]);
+const IGNORED_DIRS = new Set([
+    ".git", "node_modules", ".next", "dist", "build",
+    ".turbo", "coverage", ".npm-cache", ".pnpm-store"
+]);
+const MAX_FILE_BYTES = 64_000;
+const MAX_FILES = 500;
+export async function loadOrBuildRepoGroundingIndex(repoRoot) {
+    const cachePath = getGroundingCachePath(repoRoot);
+    try {
+        const cached = JSON.parse(await readFile(cachePath, "utf8"));
+        if (cached?.schemaVersion === "martin.grounding.v1") {
+            return cached;
+        }
+    }
+    catch { }
+    const index = await buildRepoGroundingIndex(repoRoot);
+    try {
+        await mkdir(join(homedir(), ".martin", "grounding"), { recursive: true });
+        await writeFile(cachePath, JSON.stringify(index, null, 2), "utf8");
+    }
+    catch {
+        // Cache persistence is best-effort; runtime grounding must still work even
+        // when the local filesystem blocks writes to ~/.martin/grounding.
+    }
+    return index;
+}
+export async function buildRepoGroundingIndex(repoRoot) {
+    const files = [];
+    const discovered = await walk(repoRoot, repoRoot, files, { count: 0 });
+    return {
+        schemaVersion: "martin.grounding.v1",
+        repoRoot,
+        createdAt: new Date().toISOString(),
+        fileCount: discovered.count,
+        files
+    };
+}
+export function queryRepoGroundingIndex(index, query, limit = 6) {
+    const terms = tokenize(query);
+    if (terms.length === 0)
+        return [];
+    return index.files
+        .map((file) => {
+        let score = 0;
+        const matched = new Set();
+        for (const term of terms) {
+            if (file.path.toLowerCase().includes(term)) {
+                score += 5;
+                matched.add(term);
+            }
+            if (file.keywords.some((keyword) => keyword === term)) {
+                score += 3;
+                matched.add(term);
+            }
+            if (file.symbols.some((symbol) => symbol.toLowerCase().includes(term))) {
+                score += 4;
+                matched.add(term);
+            }
+        }
+        if (score === 0)
+            return undefined;
+        return {
+            path: file.path,
+            score,
+            matchedTerms: [...matched],
+            symbols: file.symbols.slice(0, 5)
+        };
+    })
+        .filter((item) => Boolean(item))
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+        .slice(0, limit);
+}
+function getGroundingCachePath(repoRoot) {
+    return join(homedir(), ".martin", "grounding", `${Buffer.from(repoRoot).toString("base64url")}.json`);
+}
+async function walk(repoRoot, currentDir, files, state) {
+    if (state.count >= MAX_FILES)
+        return state;
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (state.count >= MAX_FILES)
+            break;
+        const absPath = join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name)) {
+                await walk(repoRoot, absPath, files, state);
+            }
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (!TEXT_EXTENSIONS.has(extname(entry.name).toLowerCase()))
+            continue;
+        try {
+            const content = await readFile(absPath, "utf8");
+            if (content.length > MAX_FILE_BYTES)
+                continue;
+            const relPath = relative(repoRoot, absPath).replace(/\\/g, "/");
+            files.push({
+                path: relPath,
+                symbols: extractSymbols(content),
+                keywords: extractKeywords(relPath, content)
+            });
+            state.count += 1;
+        }
+        catch { }
+    }
+    return state;
+}
+function extractSymbols(content) {
+    const out = new Set();
+    const patterns = [
+        /export\s+(?:async\s+)?function\s+([A-Za-z0-9_]+)/g,
+        /export\s+class\s+([A-Za-z0-9_]+)/g,
+        /export\s+const\s+([A-Za-z0-9_]+)/g,
+        /function\s+([A-Za-z0-9_]+)/g,
+        /class\s+([A-Za-z0-9_]+)/g,
+        /def\s+([A-Za-z0-9_]+)/g
+    ];
+    for (const pattern of patterns) {
+        for (const match of content.matchAll(pattern)) {
+            if (match[1])
+                out.add(match[1]);
+        }
+    }
+    return [...out].slice(0, 12);
+}
+function extractKeywords(relPath, content) {
+    const out = new Set();
+    for (const part of relPath.split(/[\/.\-_]+/u)) {
+        if (part.length >= 3)
+            out.add(part.toLowerCase());
+    }
+    for (const term of tokenize(content.split("\n").slice(0, 10).join(" "))) {
+        out.add(term);
+    }
+    return [...out].slice(0, 20);
+}
+function tokenize(input) {
+    const stopWords = new Set([
+        "the", "and", "for", "with", "from", "that",
+        "this", "into", "only", "keep", "fix", "make", "loop"
+    ]);
+    return [...new Set(input.toLowerCase().match(/[a-z0-9_]{3,}/g) ?? [])].filter((term) => !stopWords.has(term));
+}
+export function scanPatchForGroundingViolations(diff, index, options = {}) {
+    const violations = [];
+    const resolvedFiles = [];
+    const indexedPaths = new Set(index.files.map((file) => file.path));
+    const indexedSymbols = new Set(index.files.flatMap((file) => file.symbols.map((symbol) => symbol.toLowerCase())));
+    const referencedFiles = new Set();
+    const diffFilePattern = /^(?:---|\+\+\+)\s+[ab]\/(.+)$/gm;
+    for (const match of diff.matchAll(diffFilePattern)) {
+        const filePath = match[1]?.trim();
+        if (filePath && filePath !== "/dev/null") {
+            referencedFiles.add(filePath);
+        }
+    }
+    for (const filePath of referencedFiles) {
+        if (indexedPaths.has(filePath)) {
+            resolvedFiles.push(filePath);
+        }
+        else {
+            violations.push({
+                kind: "file_not_found",
+                reference: filePath,
+                sourceHint: `diff header references ${filePath}`
+            });
+        }
+        if (options.allowedPaths?.length) {
+            const isAllowed = options.allowedPaths.some((pattern) => matchesGlobPattern(filePath, pattern));
+            if (!isAllowed) {
+                violations.push({
+                    kind: "patch_outside_allowed_paths",
+                    reference: filePath,
+                    sourceHint: `${filePath} is outside allowed paths: ${options.allowedPaths.join(", ")}`
+                });
+            }
+        }
+    }
+    const addedLinePattern = /^\+(?!\+\+)(.+)$/gm;
+    const importPattern = /(?:import|require)\s*(?:.*\s+from\s+)?['"]([^'"]+)['"]/g;
+    const identifierPattern = /\b([A-Za-z_][A-Za-z0-9_]{2,})\b/g;
+    const symbolKeywords = new Set([
+        "const",
+        "let",
+        "var",
+        "function",
+        "class",
+        "return",
+        "export",
+        "import",
+        "from",
+        "await",
+        "async",
+        "new",
+        "true",
+        "false",
+        "null",
+        "undefined"
+    ]);
+    for (const lineMatch of diff.matchAll(addedLinePattern)) {
+        const line = lineMatch[1] ?? "";
+        for (const importMatch of line.matchAll(importPattern)) {
+            const reference = importMatch[1] ?? "";
+            if (!reference.startsWith(".") && !reference.startsWith("/")) {
+                continue;
+            }
+            const normalized = reference
+                .replace(/^\.\//, "")
+                .replace(/\.(js|ts|tsx|jsx)$/, "");
+            const hasMatch = index.files.some((file) => {
+                const withoutExt = file.path.replace(/\.(js|ts|tsx|jsx)$/, "");
+                return withoutExt.endsWith(normalized) || withoutExt.includes(normalized);
+            });
+            if (!hasMatch) {
+                violations.push({
+                    kind: "import_not_found",
+                    reference,
+                    sourceHint: `import in added line: ${line.trim().slice(0, 80)}`
+                });
+            }
+        }
+        for (const symbolMatch of line.matchAll(identifierPattern)) {
+            const symbol = symbolMatch[1];
+            if (!symbol)
+                continue;
+            if (symbolKeywords.has(symbol))
+                continue;
+            if (symbol.toUpperCase() === symbol)
+                continue;
+            if (indexedSymbols.has(symbol.toLowerCase()))
+                continue;
+            if (/^[a-z]+$/.test(symbol) && symbol.length <= 4)
+                continue;
+            violations.push({
+                kind: "symbol_not_found",
+                reference: symbol,
+                sourceHint: `symbol in added line: ${line.trim().slice(0, 80)}`
+            });
+        }
+    }
+    // Detect content-only diff (only comments, whitespace, empty lines added)
+    const substantiveLinePattern = /^\+(?!\+\+)\s*(?!\/\/|\/\*|\*|#).*\S/gm;
+    const hasSubstantiveLines = substantiveLinePattern.test(diff);
+    const contentOnly = !hasSubstantiveLines && diff.includes("+");
+    return {
+        violations,
+        scannedReferences: referencedFiles.size,
+        resolvedFiles,
+        contentOnly
+    };
+}
+function matchesGlobPattern(filePath, pattern) {
+    const regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "__DOUBLESTAR__")
+        .replace(/\*/g, "[^/]*")
+        .replace(/__DOUBLESTAR__/g, ".*");
+    return new RegExp(`^${regexStr}$`).test(filePath);
+}
+//# sourceMappingURL=grounding.js.map

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

@@ -0,0 +1,145 @@
+import { type ApprovalPolicy, type CostProvenance, type ExecutionProfile, type FailureClass, type InterventionType, type LoopArtifact, type LoopAttempt, type LoopBudget, type LoopRecord, type LoopTask } from "../contracts/index.js";
+import { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, type ExitDecision } from "./policy.js";
+import { evaluateChangeApprovalLeash, evaluateFilesystemLeash, evaluateSecretLeash, redactSecretsFromText, resolveExecutionProfile, evaluateVerificationLeash } from "./leash.js";
+import { buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations } from "./grounding.js";
+import { captureRollbackBoundary, restoreRollbackBoundary } from "./rollback.js";
+import { type RunStore } from "./persistence/index.js";
+export type { ApprovalPolicy, BudgetPreflightEstimate, BudgetSettlement, CostProvenance, EvidenceVector, ExecutionProfile, FailureClass, InterventionType, PatchDecision, PatchDecisionArtifact, PatchDecisionReasonCode, PatchScore, RollbackBoundaryArtifact, RollbackBoundaryStrategy, RollbackFileSnapshot, RollbackOutcomeArtifact, RollbackOutcomeStatus, PolicyPhase } from "../contracts/index.js";
+export { classifyFailure, computeEvidenceVector, evaluatePatchDecision, evaluateCostGovernor, evaluateBudgetPreflight, inferExit, nextPolicyPhase, policyPhaseToLifecycleState, scorePatchDecision, selectRecoveryRecipe, evaluateVerificationLeash, evaluateFilesystemLeash, evaluateChangeApprovalLeash, evaluateSecretLeash, resolveExecutionProfile, redactSecretsFromText, buildRepoGroundingIndex, loadOrBuildRepoGroundingIndex, queryRepoGroundingIndex, scanPatchForGroundingViolations, captureRollbackBoundary, restoreRollbackBoundary };
+export type { BudgetPreflightDecision, BudgetPreflightInput, CostGovernorState, EvidenceVectorInput, EvaluatedPatchDecision, ExitDecision, FailureAssessment, PatchDecisionInput, RecoveryDecision, RecoveryRecipe } from "./policy.js";
+export type { ResolvedExecutionProfile, SafetyLeashDecision, SafetyViolation } from "./leash.js";
+export type { GroundingScanResult, GroundingViolation, GroundingViolationKind, RepoGroundingHit, RepoGroundingIndex } from "./grounding.js";
+export { compilePromptPacket } from "./compiler.js";
+export type { PromptPacket, CompilerAdapterRequest } from "./compiler.js";
+export { createFileRunStore, makeLedgerEvent, resolveRunsRoot } from "./persistence/index.js";
+export type { AttemptArtifacts, LedgerEvent, LedgerEventKind, RunContract, RunStore } from "./persistence/index.js";
+export { compileAndPersistContext } from "./persistence/index.js";
+export type { CompileResult } from "./persistence/index.js";
+export interface MartinAdapterRequest {
+    loopId: string;
+    attemptId: string;
+    context: {
+        taskTitle: string;
+        objective: string;
+        verificationPlan: string[];
+        verificationStack?: LoopTask["verificationStack"];
+        /** Absolute path to the repository root. */
+        repoRoot?: string;
+        /** Glob patterns for files the agent may modify. Empty = no restriction. */
+        allowedPaths?: string[];
+        /** Glob patterns for files the agent must never modify. */
+        deniedPaths?: string[];
+        /** Human-readable acceptance criteria injected into the prompt. */
+        acceptanceCriteria?: string[];
+        executionProfile?: ExecutionProfile;
+        allowedNetworkDomains?: string[];
+        approvalPolicy?: ApprovalPolicy;
+        focus: string;
+        remainingBudgetUsd: number;
+        remainingIterations: number;
+        remainingTokens: number;
+    };
+    previousAttempts: LoopAttempt[];
+}
+export interface MartinAdapterResult {
+    status: "completed" | "failed";
+    summary: string;
+    usage: {
+        actualUsd: number;
+        estimatedUsd?: number;
+        tokensIn: number;
+        tokensOut: number;
+        provenance?: CostProvenance;
+    };
+    verification: {
+        passed: boolean;
+        summary: string;
+    };
+    execution?: {
+        changedFiles?: string[];
+        diffStats?: {
+            filesChanged: number;
+            addedLines: number;
+            deletedLines: number;
+        };
+        structuredErrors?: Array<{
+            file: string;
+            line?: number;
+            col?: number;
+            code?: string;
+            message: string;
+        }>;
+    };
+    artifacts?: LoopArtifact[];
+    failure?: {
+        message: string;
+        classHint?: FailureClass;
+    };
+}
+export interface MartinAdapter {
+    adapterId: string;
+    kind: "direct-provider" | "agent-cli";
+    label: string;
+    metadata: {
+        providerId: string;
+        model: string;
+        transport?: "cli" | "http" | "routed_http";
+        capabilities?: {
+            preflight?: boolean;
+            usageSettlement?: boolean;
+            diffArtifacts?: boolean;
+            structuredErrors?: boolean;
+            cachingSignals?: boolean;
+        };
+        [key: string]: unknown;
+    };
+    execute(request: MartinAdapterRequest): Promise<MartinAdapterResult>;
+    withModel?(model: string): MartinAdapter;
+}
+export interface DistilledContext {
+    focus: string;
+    recentAttempts: LoopAttempt[];
+    constraints: {
+        remainingBudgetUsd: number;
+        remainingIterations: number;
+        remainingTokens: number;
+    };
+}
+export interface AttemptPolicyDecision {
+    allowed: boolean;
+    reason: string;
+    recommendedIntervention?: InterventionType;
+}
+/**
+ * Admission gate — must pass before any attempt is executed.
+ * Evaluates budget headroom, oscillation, and repetitive failure patterns.
+ * PolicyPhase remains explicit: attempts are only admitted in ADMIT phase.
+ */
+export declare function evaluateAttemptPolicy(input: {
+    request: MartinAdapterRequest;
+    projectedUsd: number;
+}): AttemptPolicyDecision;
+export interface RunMartinInput {
+    workspaceId: string;
+    projectId: string;
+    teamId?: string;
+    task: LoopTask;
+    budget: LoopBudget;
+    metadata?: Record<string, string>;
+    adapter: MartinAdapter;
+    now?: () => string;
+    idFactory?: (prefix: string) => string;
+    maxRecentAttempts?: number;
+    fallbackModels?: string[];
+    fallbackAdapters?: MartinAdapter[];
+    /** Optional persistence store. When provided, runMartin writes artifacts on each lifecycle event. */
+    store?: RunStore;
+}
+export interface RunMartinResult {
+    loop: LoopRecord;
+    decision: ExitDecision;
+}
+export declare function distillContext(loop: Pick<LoopRecord, "task" | "budget" | "cost" | "attempts">, options?: {
+    maxRecentAttempts?: number;
+}): DistilledContext;
+export declare function runMartin(input: RunMartinInput): Promise<RunMartinResult>;