martin-loop 0.1.4 → 1.3.0

package/dist/vendor/core/router/trust-calibration.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Trust Calibration Engine — the self-improvement loop.
+ *
+ * Reads historical run records from ~/.martin/runs/ and computes a reliability
+ * profile for each model that has been used. The router uses these profiles to
+ * automatically downgrade to cheaper models when evidence shows they perform
+ * as well as more expensive ones, and to deprioritize models with poor track records.
+ *
+ * This closes the feedback loop that was missing: every completed run writes
+ * evidence to disk; this module reads it back into routing decisions.
+ */
+export interface ModelTrustProfile {
+    /** Model identifier as recorded in attempt records (e.g. "claude-sonnet-4-6") */
+    model: string;
+    /** Total runs where this model was used for at least one attempt */
+    runsObserved: number;
+    /** Fraction of observed runs that completed successfully (0–1) */
+    completionRate: number;
+    /** Average USD cost per iteration (attempt) */
+    avgCostPerIteration: number;
+    /** Average iterations used vs budget.maxIterations (lower = more efficient) */
+    avgIterationEfficiency: number;
+    /**
+     * Composite score 0–1: completionRate * (1 - avgIterationEfficiency).
+     * High score = completes well AND uses fewer iterations than the budget allows.
+     */
+    efficiencyScore: number;
+    /** ISO timestamp of the most recent run that informed this profile */
+    lastUpdated: string;
+}
+export interface TrustCalibrationResult {
+    /** Per-model reliability profiles, sorted by efficiencyScore descending */
+    profiles: ModelTrustProfile[];
+    /**
+     * The model with the best efficiencyScore that also meets minRuns threshold.
+     * Null if insufficient data exists yet.
+     */
+    recommendedModel: string | null;
+    /** Total number of runs analyzed to produce this result */
+    calibrationBasis: number;
+}
+/**
+ * Reads historical loop records and computes a trust profile for each model.
+ *
+ * @param runsDir - Override the default ~/.martin/runs path (useful for testing)
+ * @param minRuns - Minimum observations required before a profile is considered
+ *   reliable enough to influence routing. Default: 3.
+ * @param efficiencyThreshold - Minimum efficiencyScore for a model to be
+ *   eligible for auto-recommendation. Default: 0.75.
+ */
+export declare function calibrateTrust(runsDir?: string, minRuns?: number, efficiencyThreshold?: number): Promise<TrustCalibrationResult>;
+/**
+ * Returns true if a model should be deprioritized based on its trust profile.
+ * A model is deprioritized when it has enough observations to be confident
+ * it performs poorly (low completion rate).
+ */
+export declare function shouldDeprioritize(profile: ModelTrustProfile, minRuns?: number, minCompletionRate?: number): boolean;

package/dist/vendor/core/router/trust-calibration.js

@@ -0,0 +1,127 @@
+/**
+ * Trust Calibration Engine — the self-improvement loop.
+ *
+ * Reads historical run records from ~/.martin/runs/ and computes a reliability
+ * profile for each model that has been used. The router uses these profiles to
+ * automatically downgrade to cheaper models when evidence shows they perform
+ * as well as more expensive ones, and to deprioritize models with poor track records.
+ *
+ * This closes the feedback loop that was missing: every completed run writes
+ * evidence to disk; this module reads it back into routing decisions.
+ */
+import { readAllLoopRecords } from "../persistence/runs-reader.js";
+/**
+ * Reads historical loop records and computes a trust profile for each model.
+ *
+ * @param runsDir - Override the default ~/.martin/runs path (useful for testing)
+ * @param minRuns - Minimum observations required before a profile is considered
+ *   reliable enough to influence routing. Default: 3.
+ * @param efficiencyThreshold - Minimum efficiencyScore for a model to be
+ *   eligible for auto-recommendation. Default: 0.75.
+ */
+export async function calibrateTrust(runsDir, minRuns = 3, efficiencyThreshold = 0.75) {
+    const records = await readAllLoopRecords(runsDir);
+    if (records.length === 0) {
+        return { profiles: [], recommendedModel: null, calibrationBasis: 0 };
+    }
+    const accumulators = new Map();
+    for (const record of records) {
+        const modelsInRun = extractModelsFromRun(record);
+        const isCompleted = record.status === "completed";
+        const iterationEfficiency = record.budget.maxIterations > 0
+            ? record.attempts.length / record.budget.maxIterations
+            : 1;
+        for (const model of modelsInRun) {
+            const existing = accumulators.get(model) ?? {
+                model,
+                completedRuns: 0,
+                totalRuns: 0,
+                totalCostUsd: 0,
+                totalAttempts: 0,
+                totalIterationsUsedFraction: 0,
+                latestUpdatedAt: record.createdAt
+            };
+            existing.totalRuns += 1;
+            existing.totalAttempts += record.attempts.length;
+            existing.totalCostUsd += record.cost.actualUsd;
+            existing.totalIterationsUsedFraction += iterationEfficiency;
+            if (isCompleted)
+                existing.completedRuns += 1;
+            const recordTs = record.updatedAt ?? record.createdAt;
+            if (recordTs > existing.latestUpdatedAt) {
+                existing.latestUpdatedAt = recordTs;
+            }
+            accumulators.set(model, existing);
+        }
+    }
+    const profiles = [];
+    for (const acc of accumulators.values()) {
+        if (acc.totalRuns === 0)
+            continue;
+        const completionRate = acc.completedRuns / acc.totalRuns;
+        const avgIterationEfficiency = acc.totalIterationsUsedFraction / acc.totalRuns;
+        const avgCostPerIteration = acc.totalAttempts > 0 ? acc.totalCostUsd / acc.totalAttempts : 0;
+        // efficiencyScore: high means "completes reliably AND uses fewer iterations"
+        const efficiencyScore = completionRate * (1 - avgIterationEfficiency * 0.5);
+        profiles.push({
+            model: acc.model,
+            runsObserved: acc.totalRuns,
+            completionRate,
+            avgCostPerIteration,
+            avgIterationEfficiency,
+            efficiencyScore: Math.round(efficiencyScore * 1000) / 1000,
+            lastUpdated: acc.latestUpdatedAt
+        });
+    }
+    // Sort by efficiency descending
+    profiles.sort((a, b) => b.efficiencyScore - a.efficiencyScore);
+    // Recommend the cheapest model that meets threshold with enough data
+    const eligible = profiles.filter((p) => p.runsObserved >= minRuns && p.efficiencyScore >= efficiencyThreshold);
+    const recommendedModel = eligible.length > 0
+        ? eligible.reduce((best, p) => p.avgCostPerIteration < best.avgCostPerIteration ? p : best).model
+        : null;
+    return {
+        profiles,
+        recommendedModel,
+        calibrationBasis: records.length
+    };
+}
+/**
+ * Returns true if a model should be deprioritized based on its trust profile.
+ * A model is deprioritized when it has enough observations to be confident
+ * it performs poorly (low completion rate).
+ */
+export function shouldDeprioritize(profile, minRuns = 5, minCompletionRate = 0.4) {
+    return (profile.runsObserved >= minRuns &&
+        profile.completionRate < minCompletionRate);
+}
+/**
+ * Extracts the distinct set of models used in a run.
+ * Falls back to adapterId if model field is absent.
+ */
+function extractModelsFromRun(record) {
+    const models = new Set();
+    for (const attempt of record.attempts) {
+        const key = attempt.model ?? attempt.adapterId;
+        if (key)
+            models.add(normalizeModelName(key));
+    }
+    return [...models];
+}
+function normalizeModelName(raw) {
+    // Normalize known aliases to a consistent key
+    if (raw.includes("sonnet"))
+        return "claude-sonnet";
+    if (raw.includes("haiku"))
+        return "claude-haiku";
+    if (raw.includes("opus"))
+        return "claude-opus";
+    if (raw.includes("gpt-4o-mini"))
+        return "gpt-4o-mini";
+    if (raw.includes("gpt-4o"))
+        return "gpt-4o";
+    if (raw.includes("o3"))
+        return "o3";
+    return raw;
+}
+//# sourceMappingURL=trust-calibration.js.map

package/dist/vendor/core/run-martin.d.ts

@@ -0,0 +1,2 @@
+import type { RunMartinOptions, RunMartinResult } from "./types.js";
+export declare function runMartin(options: RunMartinOptions): Promise<RunMartinResult>;

package/dist/vendor/core/run-martin.js

@@ -0,0 +1,287 @@
+import { appendLoopEvent, createLoopRecord } from "../contracts/index.js";
+import { distillContext } from "./context-distillation.js";
+import { evaluateCostGovernor } from "./cost-governor.js";
+import { inferExit } from "./exit-intelligence.js";
+import { classifyFailure } from "./failure-taxonomy.js";
+export async function runMartin(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const contracts = createContractOptions(options.idFactory);
+    let loop = createLoopRecord({
+        workspaceId: options.workspaceId,
+        projectId: options.projectId,
+        task: options.task,
+        ...(options.budget ? { budget: options.budget } : {}),
+        ...(options.teamId ? { teamId: options.teamId } : {})
+    }, {
+        ...contracts,
+        now: now()
+    });
+    let finalContext = distillContext(loop);
+    let decision = {
+        shouldExit: false,
+        lifecycleState: "running",
+        reason: "Run initialized."
+    };
+    loop = pushEvent(loop, {
+        type: "run.started",
+        lifecycleState: "running",
+        payload: {
+            adapterId: options.adapter.adapterId,
+            adapterKind: options.adapter.kind
+        }
+    }, contracts, now(), "running");
+    while (loop.attempts.length < loop.budget.maxIterations) {
+        const preAttemptCost = evaluateCostGovernor({
+            budget: loop.budget,
+            cost: loop.cost,
+            attemptsUsed: loop.attempts.length
+        });
+        if (preAttemptCost.shouldStop) {
+            decision = {
+                shouldExit: true,
+                lifecycleState: "budget_exit",
+                reason: "Budget governor reached a hard limit."
+            };
+            loop = finalizeLoop(loop, decision, contracts, now(), "exited");
+            finalContext = distillContext(loop);
+            return {
+                loop,
+                decision,
+                finalContext
+            };
+        }
+        finalContext = distillContext(loop);
+        const attemptIndex = loop.attempts.length + 1;
+        const attemptStartedAt = now();
+        const attemptId = makeId("att", options.idFactory);
+        loop = {
+            ...loop,
+            attempts: [
+                ...loop.attempts,
+                {
+                    attemptId,
+                    index: attemptIndex,
+                    adapterId: options.adapter.adapterId,
+                    model: options.adapter.metadata.model ?? options.adapter.label,
+                    startedAt: attemptStartedAt
+                }
+            ],
+            status: "running",
+            lifecycleState: "running",
+            updatedAt: attemptStartedAt
+        };
+        loop = pushEvent(loop, {
+            type: "attempt.started",
+            lifecycleState: "running",
+            payload: {
+                attemptId,
+                attemptIndex,
+                adapterId: options.adapter.adapterId
+            }
+        }, contracts, attemptStartedAt, "running");
+        const adapterRequest = {
+            loopId: loop.loopId,
+            workspaceId: loop.workspaceId,
+            projectId: loop.projectId,
+            attemptIndex,
+            task: loop.task,
+            context: finalContext,
+            budget: loop.budget,
+            costState: preAttemptCost
+        };
+        if (loop.teamId) {
+            adapterRequest.teamId = loop.teamId;
+        }
+        const result = await options.adapter.execute(adapterRequest);
+        const completedAt = now();
+        loop = applyResult(loop, attemptId, result, completedAt);
+        loop = pushEvent(loop, {
+            type: "attempt.completed",
+            lifecycleState: "running",
+            payload: {
+                attemptId,
+                status: result.status,
+                summary: result.summary
+            }
+        }, contracts, completedAt, "running");
+        const postAttemptCost = evaluateCostGovernor({
+            budget: loop.budget,
+            cost: loop.cost,
+            attemptsUsed: loop.attempts.length
+        });
+        if (postAttemptCost.pressure !== "healthy") {
+            loop = pushEvent(loop, {
+                type: "budget.updated",
+                lifecycleState: "running",
+                payload: {
+                    pressure: postAttemptCost.pressure,
+                    remainingBudgetUsd: postAttemptCost.remainingBudgetUsd,
+                    remainingIterations: postAttemptCost.remainingIterations,
+                    remainingTokens: postAttemptCost.remainingTokens
+                }
+            }, contracts, now(), "running");
+        }
+        if (result.status === "completed" && result.verification.passed) {
+            loop = pushEvent(loop, {
+                type: "verification.completed",
+                lifecycleState: "verifying",
+                payload: {
+                    attemptId,
+                    passed: true,
+                    summary: result.verification.summary
+                }
+            }, contracts, now(), "verifying");
+            decision = {
+                shouldExit: true,
+                lifecycleState: "completed",
+                reason: result.verification.summary
+            };
+            loop = finalizeLoop(loop, decision, contracts, now(), "completed");
+            finalContext = distillContext(loop);
+            return {
+                loop,
+                decision,
+                finalContext
+            };
+        }
+        const failure = classifyFailure({
+            attempts: loop.attempts.slice(0, -1),
+            result
+        });
+        loop = annotateAttempt(loop, attemptId, failure);
+        loop = pushEvent(loop, {
+            type: "failure.classified",
+            lifecycleState: "running",
+            payload: {
+                attemptId,
+                failureClass: failure.failureClass,
+                rationale: failure.rationale
+            }
+        }, contracts, now(), "running");
+        loop = pushEvent(loop, {
+            type: "intervention.selected",
+            lifecycleState: "running",
+            payload: {
+                attemptId,
+                intervention: failure.recommendedIntervention
+            }
+        }, contracts, now(), "running");
+        loop = pushEvent(loop, {
+            type: "verification.completed",
+            lifecycleState: "verifying",
+            payload: {
+                attemptId,
+                passed: result.verification.passed,
+                summary: result.verification.summary
+            }
+        }, contracts, now(), "verifying");
+        decision = inferExit({
+            loop,
+            lastResult: result,
+            lastFailure: failure,
+            costState: postAttemptCost
+        });
+        if (decision.shouldExit) {
+            loop = finalizeLoop(loop, decision, contracts, now(), lifecycleStatus(decision));
+            finalContext = distillContext(loop);
+            return {
+                loop,
+                decision,
+                finalContext
+            };
+        }
+    }
+    decision = {
+        shouldExit: true,
+        lifecycleState: "budget_exit",
+        reason: "The run exhausted its iteration budget."
+    };
+    loop = finalizeLoop(loop, decision, contracts, now(), "exited");
+    finalContext = distillContext(loop);
+    return {
+        loop,
+        decision,
+        finalContext
+    };
+}
+function applyResult(loop, attemptId, result, completedAt) {
+    return {
+        ...loop,
+        attempts: loop.attempts.map((attempt) => attempt.attemptId === attemptId ? buildCompletedAttempt(attempt, result, completedAt) : attempt),
+        artifacts: [...loop.artifacts, ...(result.artifacts ?? [])],
+        cost: {
+            actualUsd: round(loop.cost.actualUsd + result.usage.actualUsd),
+            avoidedUsd: round(loop.cost.avoidedUsd + (result.usage.avoidedUsd ?? 0)),
+            tokensIn: loop.cost.tokensIn + result.usage.tokensIn,
+            tokensOut: loop.cost.tokensOut + result.usage.tokensOut
+        },
+        updatedAt: completedAt
+    };
+}
+function buildCompletedAttempt(attempt, result, completedAt) {
+    const nextAttempt = {
+        ...attempt,
+        completedAt,
+        summary: result.summary
+    };
+    if (result.failure?.classHint) {
+        nextAttempt.failureClass = result.failure.classHint;
+    }
+    return nextAttempt;
+}
+function annotateAttempt(loop, attemptId, failure) {
+    return {
+        ...loop,
+        attempts: loop.attempts.map((attempt) => {
+            if (attempt.attemptId !== attemptId) {
+                return attempt;
+            }
+            return {
+                ...attempt,
+                failureClass: failure.failureClass,
+                intervention: failure.recommendedIntervention
+            };
+        })
+    };
+}
+function finalizeLoop(loop, decision, contracts, timestamp, status) {
+    return pushEvent({
+        ...loop,
+        lifecycleState: decision.lifecycleState,
+        status,
+        updatedAt: timestamp
+    }, {
+        type: "run.completed",
+        lifecycleState: decision.lifecycleState,
+        payload: {
+            reason: decision.reason
+        }
+    }, contracts, timestamp, status);
+}
+function pushEvent(loop, event, contracts, timestamp, status) {
+    const next = appendLoopEvent(loop, {
+        ...event,
+        timestamp
+    }, {
+        ...contracts,
+        now: timestamp
+    });
+    return status ? { ...next, status, lifecycleState: event.lifecycleState ?? next.lifecycleState } : next;
+}
+function lifecycleStatus(decision) {
+    return decision.lifecycleState === "completed" ? "completed" : "exited";
+}
+function createContractOptions(idFactory) {
+    return idFactory ? { idFactory } : {};
+}
+function makeId(prefix, idFactory) {
+    if (idFactory) {
+        return idFactory(prefix);
+    }
+    const entropy = Math.random().toString(36).slice(2, 10);
+    return `${prefix}_${entropy}`;
+}
+function round(value) {
+    return Number(value.toFixed(4));
+}
+//# sourceMappingURL=run-martin.js.map

package/dist/vendor/core/security/cve-scanner.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CVE Patch Scanner — Phase 37.
+ *
+ * Parses a unified diff for newly added package dependencies and queries the
+ * OSV.dev API (https://api.osv.dev) to check for known CVEs. Blocks the
+ * attempt if any discovered package has severity HIGH or CRITICAL.
+ *
+ * Supported manifest formats:
+ *   - package.json (npm/Node.js) — ecosystem: "npm"
+ *   - requirements.txt (Python) — ecosystem: "PyPI"
+ *   - Cargo.toml (Rust) — ecosystem: "crates.io"
+ *   - go.mod (Go) — ecosystem: "Go"
+ *
+ * Design rules:
+ * - Advisory when OSV.dev is unreachable (never hard-fail on network error)
+ * - Only checks ADDED lines (+ prefix) — not removed packages
+ * - Deduplicates package names before querying
+ * - MAX_PACKAGES_PER_SCAN = 20 to bound latency
+ */
+export type CveSeverity = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" | "UNKNOWN";
+export interface CveMatch {
+    packageName: string;
+    version?: string;
+    ecosystem: string;
+    vulnId: string;
+    summary: string;
+    severity: CveSeverity;
+    url: string;
+}
+export interface CveScanResult {
+    /** Newly added packages extracted from the diff. */
+    packageCandidates: PackageCandidate[];
+    /** CVEs found for any of the candidates. */
+    matches: CveMatch[];
+    /**
+     * True when any match has severity HIGH or CRITICAL.
+     * The caller should discard the attempt when this is true.
+     */
+    blocked: boolean;
+    /** Human-readable block reason. Undefined when not blocked. */
+    blockReason?: string;
+    /** True when OSV.dev was unreachable — scan ran in advisory-only mode. */
+    networkError?: boolean;
+}
+export interface PackageCandidate {
+    name: string;
+    version?: string;
+    ecosystem: string;
+}
+/**
+ * Extract newly added package dependencies from a unified diff string.
+ * Only examines added lines (starting with +) to avoid flagging removals.
+ */
+export declare function extractPackageCandidates(diff: string): PackageCandidate[];
+/**
+ * Scan a unified diff for new package dependencies and check them against
+ * the OSV.dev vulnerability database.
+ *
+ * Returns immediately (advisory mode) if OSV.dev is unreachable.
+ * Blocks the attempt if any package has severity HIGH or CRITICAL.
+ */
+export declare function scanDiffForCves(diff: string): Promise<CveScanResult>;