@martinloop/mcp 0.3.5 → 0.3.6

package/dist/vendor/adapters/openai-compatible.js

@@ -72,12 +72,12 @@ function estimateCost(model, inputChars, outputChars) {
 // ---------------------------------------------------------------------------
 // Prompt builder
 // ---------------------------------------------------------------------------
-const DEFAULT_SYSTEM_PROMPT = `You are an expert software engineer executing a governed coding task.
-Follow these rules exactly:
-- Read the task description carefully and implement only what is asked.
-- Do not add features, refactors, or improvements beyond the stated task.
-- If the task asks you to write or modify code, output the complete file content with changes applied.
-- Be precise, minimal, and test-backed in all changes.
+const DEFAULT_SYSTEM_PROMPT = `You are an expert software engineer executing a governed coding task.
+Follow these rules exactly:
+- Read the task description carefully and implement only what is asked.
+- Do not add features, refactors, or improvements beyond the stated task.
+- If the task asks you to write or modify code, output the complete file content with changes applied.
+- Be precise, minimal, and test-backed in all changes.
 - State what you changed and why at the end of your response.`;
 export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
 export const DEFAULT_OPENAI_MODEL = "gpt-4.1-mini";
@@ -166,70 +166,103 @@ export function createOpenAiCompatibleAdapter(options) {
                     failure: { message: "budget_preflight_exceeded", classHint: "budget_pressure" }
                 };
             }
-            // Call the OpenAI-compatible endpoint
+            // Call the OpenAI-compatible endpoint with exponential-backoff retry on
+            // transient failures (429 rate-limit, 503/5xx server errors, network errors).
+            // Auth errors (401/403) and bad-request errors (400) are not retried — they
+            // indicate a permanent configuration problem.
+            const MAX_RETRIES = 3;
+            const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
             const endpoint = `${baseUrl}/v1/chat/completions`;
             let responseText = "";
             let tokensIn = estimated.tokensIn;
             let tokensOut = 0;
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), timeoutMs);
-            try {
-                const headers = { "Content-Type": "application/json" };
-                if (apiKey)
-                    headers["Authorization"] = `Bearer ${apiKey}`;
-                // OpenRouter requires a site URL header for attribution
-                if (baseUrl.includes("openrouter")) {
-                    headers["HTTP-Referer"] = "https://martinloop.com";
-                    headers["X-Title"] = "MartinLoop";
-                }
-                const res = await fetchFn(endpoint, {
-                    method: "POST",
-                    headers,
-                    body: JSON.stringify({
-                        model,
-                        messages: [
-                            { role: "system", content: systemPrompt },
-                            { role: "user", content: prompt }
-                        ],
-                        temperature: 0.2,
-                        max_tokens: 8192
-                    }),
-                    signal: controller.signal
-                });
-                const body = (await res.json());
-                if (!res.ok || body.error) {
-                    const errMsg = body.error?.message ?? `HTTP ${res.status}`;
-                    return {
-                        status: "failed",
-                        summary: `${model} API error: ${errMsg}`,
-                        usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
-                        verification: { passed: false, summary: "API call failed before verifier." },
-                        failure: { message: errMsg, classHint: "infrastructure_error" }
-                    };
+            const headers = { "Content-Type": "application/json" };
+            if (apiKey)
+                headers["Authorization"] = `Bearer ${apiKey}`;
+            if (baseUrl.includes("openrouter")) {
+                headers["HTTP-Referer"] = "https://martinloop.com";
+                headers["X-Title"] = "MartinLoop";
+            }
+            const requestBody = JSON.stringify({
+                model,
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    { role: "user", content: prompt }
+                ],
+                temperature: 0.2,
+                max_tokens: 8192
+            });
+            let lastError = "";
+            let succeeded = false;
+            for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), timeoutMs);
+                try {
+                    const res = await fetchFn(endpoint, {
+                        method: "POST",
+                        headers,
+                        body: requestBody,
+                        signal: controller.signal
+                    });
+                    const body = (await res.json());
+                    if (!res.ok || body.error) {
+                        const errMsg = body.error?.message ?? `HTTP ${res.status}`;
+                        if (RETRYABLE_STATUS.has(res.status) && attempt < MAX_RETRIES - 1) {
+                            lastError = errMsg;
+                            // Exponential backoff: 1s, 2s, 4s
+                            await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
+                            continue;
+                        }
+                        return {
+                            status: "failed",
+                            summary: `${model} API error: ${errMsg}`,
+                            usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
+                            verification: { passed: false, summary: "API call failed before verifier." },
+                            failure: { message: errMsg, classHint: "infrastructure_error" }
+                        };
+                    }
+                    responseText = body.choices?.[0]?.message?.content ?? "";
+                    if (body.usage) {
+                        tokensIn = body.usage.prompt_tokens ?? tokensIn;
+                        tokensOut = body.usage.completion_tokens ?? 0;
+                    }
+                    else {
+                        tokensOut = Math.ceil(responseText.length / CHARS_PER_TOKEN);
+                    }
+                    succeeded = true;
+                    break;
                 }
-                responseText = body.choices?.[0]?.message?.content ?? "";
-                if (body.usage) {
-                    tokensIn = body.usage.prompt_tokens ?? tokensIn;
-                    tokensOut = body.usage.completion_tokens ?? 0;
+                catch (error) {
+                    const isAbort = error instanceof Error && error.name === "AbortError";
+                    if (isAbort || attempt === MAX_RETRIES - 1) {
+                        const message = isAbort
+                            ? `${model} request timed out after ${timeoutMs}ms`
+                            : String(error);
+                        return {
+                            status: "failed",
+                            summary: message,
+                            usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
+                            verification: { passed: false, summary: isAbort ? "Request timed out." : "Network error." },
+                            failure: { message, classHint: "infrastructure_error" }
+                        };
+                    }
+                    // Transient network error — retry with backoff
+                    lastError = String(error);
+                    await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
                 }
-                else {
-                    tokensOut = Math.ceil(responseText.length / CHARS_PER_TOKEN);
+                finally {
+                    clearTimeout(timer);
                 }
             }
-            catch (error) {
-                const isAbort = error instanceof Error && error.name === "AbortError";
-                const message = isAbort ? `${model} request timed out after ${timeoutMs}ms` : String(error);
+            if (!succeeded) {
                 return {
                     status: "failed",
-                    summary: message,
+                    summary: `${model} API error after ${MAX_RETRIES} attempts: ${lastError}`,
                     usage: normalizeUsage({ actualUsd: 0, tokensIn: 0, tokensOut: 0, provenance: "unavailable" }),
-                    verification: { passed: false, summary: isAbort ? "Request timed out." : "Network error." },
-                    failure: { message, classHint: "infrastructure_error" }
+                    verification: { passed: false, summary: "API call failed after retries." },
+                    failure: { message: lastError, classHint: "infrastructure_error" }
                 };
             }
-            finally {
-                clearTimeout(timer);
-            }
             if (!responseText.trim()) {
                 return {
                     status: "failed",

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

@@ -1,6 +1,6 @@
 export type LoopStatus = "queued" | "running" | "verifying" | "completed" | "failed" | "exited";
 export type LoopLifecycleState = "created" | "running" | "verifying" | "completed" | "budget_exit" | "diminishing_returns" | "stuck_exit" | "human_escalation";
-export declare const FAILURE_CLASSES: readonly ["logic_error", "hallucination", "syntax_error", "type_error", "test_regression", "scope_creep", "no_progress", "repo_grounding_failure", "verification_failure", "environment_mismatch", "budget_pressure", "safety_leash_blocked"];
+export declare const FAILURE_CLASSES: readonly ["logic_error", "hallucination", "syntax_error", "type_error", "test_regression", "scope_creep", "no_progress", "repo_grounding_failure", "verification_failure", "environment_mismatch", "budget_pressure", "safety_leash_blocked", "sandbox_write_blocked"];
 export type FailureClass = (typeof FAILURE_CLASSES)[number];
 export type InterventionType = "compress_context" | "change_model" | "tighten_task" | "switch_adapter" | "run_verifier" | "escalate_human" | "stop_loop";
 export type LoopEventType = "run.started" | "attempt.started" | "attempt.completed" | "failure.classified" | "intervention.selected" | "verification.completed" | "budget.updated" | "run.completed";

package/dist/vendor/contracts/index.js

@@ -11,6 +11,7 @@ export const FAILURE_CLASSES = [
     "environment_mismatch",
     "budget_pressure",
     "safety_leash_blocked",
+    "sandbox_write_blocked",
 ];
 export { MARTIN_ERROR_CATEGORIES } from "./operator.js";
 export const DEFAULT_BUDGET = {

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

@@ -14,8 +14,12 @@ export { createLocalIdentityAuthority, hasIdentityScope, issueIdentityToken, ver
 export type { LocalIdentityAuthority } from "./identity.js";
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
-export { classifyRoute, evaluatePreworkBurnPolicy } from "./routing.js";
-export type { RouteDecision, RouteClassificationInput } from "./routing.js";
+export { classifyRoute, evaluatePreworkBurnPolicy, resolveModelForTier, selectBestEngine } from "./routing.js";
+export type { RouteDecision, RouteClassificationInput, AvailableEngine } from "./routing.js";
+export { validateTestIntegrity, snapshotTestFiles, identifyNewTests, findTestFiles, isTestFile, extractImports, hasTrivialAssertionsOnly, importsPreExistingCode } from "./test-integrity.js";
+export type { TestIntegrityReport, TestIntegrityFinding } from "./test-integrity.js";
+export { analyzeRepoStyle, buildPromptDirectives } from "./repo-analyzer.js";
+export type { RepoStyleProfile } from "./repo-analyzer.js";
 export { runContextIntegrityPrecheck } from "./context-integrity.js";
 export type { ContextIntegrityPrecheck, ContextIntegrityVerdict } from "./context-integrity.js";
 export { compilePromptPacket } from "./compiler.js";
@@ -24,6 +28,10 @@ export { createFileRunStore, makeLedgerEvent, readAllLoopRecords, readLatestLoop
 export type { AttemptArtifacts, LedgerEvent, LedgerEventKind, LoopAttemptRecord, LoopRunRecord, ReceiptIntegrityChainEntry, RunContract, RunStore, StoredReceiptIntegrityMaterial } from "./persistence/index.js";
 export { compileAndPersistContext } from "./persistence/index.js";
 export type { CompileResult } from "./persistence/index.js";
+export { appendMemory, readMemoryEntries, getPreference, buildMemorySummary, recordPreference, recordConsent } from "./persistence/memory-store.js";
+export type { MemoryEntry, MemoryKind, MemorySummary } from "./persistence/memory-store.js";
+export { appendTraceEntry, readTraceEntries, aggregateTraces, getHistoricalDirectSuccessRate } from "./persistence/trace-store.js";
+export type { TraceEntry, TraceAggregation } from "./persistence/trace-store.js";
 export interface MartinAdapterRequest {
     loopId: string;
     attemptId: string;

package/dist/vendor/core/index.js

@@ -13,7 +13,11 @@ export { createLocalIdentityAuthority, hasIdentityScope, issueIdentityToken, ver
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
 // ─── Routing economics ─────────────────────────────────────────────────────
-export { classifyRoute, evaluatePreworkBurnPolicy } from "./routing.js";
+export { classifyRoute, evaluatePreworkBurnPolicy, resolveModelForTier, selectBestEngine } from "./routing.js";
+// ─── Test Integrity Validation ──────────────────────────────────────────────
+export { validateTestIntegrity, snapshotTestFiles, identifyNewTests, findTestFiles, isTestFile, extractImports, hasTrivialAssertionsOnly, importsPreExistingCode } from "./test-integrity.js";
+// ─── Repo Style Analyzer ────────────────────────────────────────────────────
+export { analyzeRepoStyle, buildPromptDirectives } from "./repo-analyzer.js";
 // ─── Context Integrity Pre-gate ──────────────────────────────────────────────
 export { runContextIntegrityPrecheck } from "./context-integrity.js";
 // ─── Prompt packet compiler ──────────────────────────────────────────────────
@@ -21,6 +25,10 @@ export { compilePromptPacket } from "./compiler.js";
 // ─── Persistence (RunStore, LedgerEvent, FileRunStore) ──────────────────────
 export { createFileRunStore, makeLedgerEvent, readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot, resolveReceiptIntegrityPath, verifyReceiptIntegrityFromFiles, writeReceiptIntegrityMaterial } from "./persistence/index.js";
 export { compileAndPersistContext } from "./persistence/index.js";
+// ─── MartinLoop Memory Store ────────────────────────────────────────────────
+export { appendMemory, readMemoryEntries, getPreference, buildMemorySummary, recordPreference, recordConsent } from "./persistence/memory-store.js";
+// ─── Trace Intelligence Store ───────────────────────────────────────────────
+export { appendTraceEntry, readTraceEntries, aggregateTraces, getHistoricalDirectSuccessRate } from "./persistence/trace-store.js";
 /**
  * Admission gate — must pass before any attempt is executed.
  * Evaluates budget headroom, oscillation, and repetitive failure patterns.
@@ -1009,7 +1017,7 @@ export async function runMartin(input) {
             }
         }
         if (patchDecision && patchDecision.decision !== "KEEP" && !failure) {
-            failure = classifyPatchDecisionFailure(patchDecision);
+            failure = classifyPatchDecisionFailure(patchDecision, result);
             loop = applyPatchFailureToLoop(loop, {
                 attemptId,
                 summary: patchDecision.summary,
@@ -1403,7 +1411,19 @@ function toPatchDecisionArtifact(decision) {
         reasonCodes: decision.reasonCodes
     };
 }
-function classifyPatchDecisionFailure(decision) {
+const SANDBOX_WRITE_BLOCKED_PATTERNS = [
+    /createprocessasuserw failed:\s*\d+/iu,
+    /windows sandbox: runner error/iu,
+    /writing is blocked by read-only sandbox/iu,
+    /read-only filesystem sandbox/iu,
+    /approval is disabled/iu
+];
+function detectSandboxWriteBlocked(result) {
+    const sources = [result.summary, result.failure?.message]
+        .filter((value) => typeof value === "string" && value.trim().length > 0);
+    return sources.some((source) => SANDBOX_WRITE_BLOCKED_PATTERNS.some((pattern) => pattern.test(source)));
+}
+function classifyPatchDecisionFailure(decision, result) {
     if (decision.reasonCodes.includes("grounding_failure")) {
         return {
             failureClass: "repo_grounding_failure",
@@ -1445,6 +1465,14 @@ function classifyPatchDecisionFailure(decision) {
             recommendedIntervention: "escalate_human"
         };
     }
+    if (result && detectSandboxWriteBlocked(result)) {
+        return {
+            failureClass: "sandbox_write_blocked",
+            rationale: "The adapter reported a completed patch but the workspace-write sandbox blocked the underlying file write, so no trustworthy code change landed on disk.",
+            retryable: true,
+            recommendedIntervention: "switch_adapter"
+        };
+    }
     return {
         failureClass: "no_progress",
         rationale: "Patch truth discarded the attempt because it did not produce a trustworthy code change.",

package/dist/vendor/core/persistence/memory-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MartinLoop Memory Store
+ *
+ * Append-only, never-overwriting persistent memory. Records user consent
+ * signals, preferences, behavioral patterns, and learning outcomes so
+ * MartinLoop gets smarter with every session.
+ *
+ * Design principles:
+ * - Append-only JSONL — entries are never deleted or overwritten
+ * - Structured by kind — each memory entry has a type and a key
+ * - Source-aware — distinguishes explicit user input from inferred patterns
+ * - Confidence-scored — inferred memories degrade gracefully
+ *
+ * Storage: <runsRoot>/_martin/memory.jsonl
+ */
+export type MemoryKind = "consent" | "preference" | "pattern" | "feedback" | "budget" | "model";
+export interface MemoryEntry {
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    /** What kind of memory this is */
+    kind: MemoryKind;
+    /** Dot-notated key, e.g. "model.direct.claude", "budget.auth.usd", "gate.bypassed" */
+    key: string;
+    /** The memory payload */
+    value: unknown;
+    /** Did the user say it explicitly, or did Martin observe it? */
+    source: "explicit" | "inferred";
+    /** Confidence score 0-1 — inferred memories should be < 0.8 */
+    confidence: number;
+}
+export interface MemorySummary {
+    totalEntries: number;
+    byKind: Partial<Record<MemoryKind, MemoryEntry[]>>;
+    recentPreferences: MemoryEntry[];
+    recentConsents: MemoryEntry[];
+    recentFeedback: MemoryEntry[];
+}
+/**
+ * Append a memory entry. Never overwrites — always appends.
+ */
+export declare function appendMemory(runsRoot: string, entry: MemoryEntry): Promise<void>;
+/**
+ * Read all memory entries in order (oldest first).
+ */
+export declare function readMemoryEntries(runsRoot: string): Promise<MemoryEntry[]>;
+/**
+ * Get the most recent memory entry for a specific key.
+ * Returns undefined if no entry exists for that key.
+ */
+export declare function getPreference(runsRoot: string, key: string): Promise<MemoryEntry | undefined>;
+/**
+ * Build a summary of memory entries for MCP resource and MartinLoop context injection.
+ * Returns the top 20 most recent entries per kind.
+ */
+export declare function buildMemorySummary(entries: MemoryEntry[]): MemorySummary;
+/**
+ * Record a preference from user input.
+ */
+export declare function recordPreference(runsRoot: string, key: string, value: unknown, source?: "explicit" | "inferred"): Promise<void>;
+/**
+ * Record a consent signal (user approved or denied a governance action).
+ */
+export declare function recordConsent(runsRoot: string, action: string, approved: boolean, context?: Record<string, unknown>): Promise<void>;

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

@@ -0,0 +1,115 @@
+/**
+ * MartinLoop Memory Store
+ *
+ * Append-only, never-overwriting persistent memory. Records user consent
+ * signals, preferences, behavioral patterns, and learning outcomes so
+ * MartinLoop gets smarter with every session.
+ *
+ * Design principles:
+ * - Append-only JSONL — entries are never deleted or overwritten
+ * - Structured by kind — each memory entry has a type and a key
+ * - Source-aware — distinguishes explicit user input from inferred patterns
+ * - Confidence-scored — inferred memories degrade gracefully
+ *
+ * Storage: <runsRoot>/_martin/memory.jsonl
+ */
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const MEMORY_DIRECTORY = "_martin";
+const MEMORY_FILENAME = "memory.jsonl";
+function resolveMemoryPath(runsRoot) {
+    return join(resolve(runsRoot), MEMORY_DIRECTORY, MEMORY_FILENAME);
+}
+/**
+ * Append a memory entry. Never overwrites — always appends.
+ */
+export async function appendMemory(runsRoot, entry) {
+    const memPath = resolveMemoryPath(runsRoot);
+    await mkdir(join(resolve(runsRoot), MEMORY_DIRECTORY), { recursive: true });
+    await appendFile(memPath, JSON.stringify(entry) + "\n", "utf8");
+}
+/**
+ * Read all memory entries in order (oldest first).
+ */
+export async function readMemoryEntries(runsRoot) {
+    const memPath = resolveMemoryPath(runsRoot);
+    try {
+        const raw = await readFile(memPath, "utf8");
+        return raw
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get the most recent memory entry for a specific key.
+ * Returns undefined if no entry exists for that key.
+ */
+export async function getPreference(runsRoot, key) {
+    const entries = await readMemoryEntries(runsRoot);
+    // Return the most recent entry for this key (last in file)
+    const matches = entries.filter((e) => e.key === key);
+    return matches[matches.length - 1];
+}
+/**
+ * Build a summary of memory entries for MCP resource and MartinLoop context injection.
+ * Returns the top 20 most recent entries per kind.
+ */
+export function buildMemorySummary(entries) {
+    const byKind = {};
+    for (const entry of entries) {
+        if (!byKind[entry.kind]) {
+            byKind[entry.kind] = [];
+        }
+        byKind[entry.kind].push(entry);
+    }
+    // Keep only the 20 most recent per kind
+    for (const kind of Object.keys(byKind)) {
+        byKind[kind] = byKind[kind].slice(-20);
+    }
+    const recent = entries.slice(-50);
+    return {
+        totalEntries: entries.length,
+        byKind,
+        recentPreferences: recent.filter((e) => e.kind === "preference"),
+        recentConsents: recent.filter((e) => e.kind === "consent"),
+        recentFeedback: recent.filter((e) => e.kind === "feedback")
+    };
+}
+/**
+ * Record a preference from user input.
+ */
+export async function recordPreference(runsRoot, key, value, source = "explicit") {
+    await appendMemory(runsRoot, {
+        timestamp: new Date().toISOString(),
+        kind: "preference",
+        key,
+        value,
+        source,
+        confidence: source === "explicit" ? 1.0 : 0.6
+    });
+}
+/**
+ * Record a consent signal (user approved or denied a governance action).
+ */
+export async function recordConsent(runsRoot, action, approved, context) {
+    await appendMemory(runsRoot, {
+        timestamp: new Date().toISOString(),
+        kind: "consent",
+        key: `consent.${action}`,
+        value: { approved, context },
+        source: "explicit",
+        confidence: 1.0
+    });
+}

package/dist/vendor/core/persistence/trace-store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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)
+ */
+export interface TraceEntry {
+    /** ISO-8601 timestamp */
+    timestamp: string;
+    /** Unique loop identifier */
+    loopId: string;
+    /** The objective that was governed */
+    objective: string;
+    /** Which engine executed the run */
+    engine: string;
+    /** Route selected by classifyRoute */
+    selectedRoute: "direct" | "manager" | "consensus";
+    /** Route classifier confidence (0-1) */
+    routeConfidence: number;
+    /** Budget allocated (USD) */
+    budgetUsd: number;
+    /** Actual spend (USD) */
+    actualCostUsd: number;
+    /** Pre-work burn percentage */
+    preWorkBurnPct: number;
+    /** Number of attempts */
+    attempts: number;
+    /** Final loop status */
+    status: string;
+    /** Final lifecycle state */
+    lifecycleState: string;
+    /** Failure class of last attempt (if failed) */
+    failureClass?: string;
+    /** Whether verification passed */
+    verificationPassed: boolean;
+    /** Number of files changed */
+    filesChanged: number;
+    /** Working directory (hashed for privacy) */
+    workspaceHash: string;
+}
+export interface TraceAggregation {
+    totalRuns: number;
+    directRuns: number;
+    managerRuns: number;
+    consensusRuns: number;
+    directSuccessRate: number;
+    managerSuccessRate: number;
+    averageCostUsd: number;
+    averagePreWorkBurnPct: number;
+    totalSpendUsd: number;
+    totalSavedUsd: number;
+    topFailureClasses: Array<{
+        failureClass: string;
+        count: number;
+    }>;
+    averageAttemptsPerRun: number;
+    lastUpdated: string;
+}
+/**
+ * Append a trace entry to the local trace store. Never overwrites.
+ */
+export declare function appendTraceEntry(runsRoot: string, entry: TraceEntry): Promise<void>;
+/**
+ * Read all trace entries from the local trace store.
+ */
+export declare function readTraceEntries(runsRoot: string): Promise<TraceEntry[]>;
+/**
+ * Aggregate trace entries into summary statistics.
+ * Used by classifyRoute() to get historicalDirectSuccessRate.
+ */
+export declare function aggregateTraces(entries: TraceEntry[]): TraceAggregation;
+/**
+ * Get the historical direct success rate for use in route classification.
+ * Returns undefined if insufficient data (< 5 runs).
+ */
+export declare function getHistoricalDirectSuccessRate(runsRoot: string): Promise<number | undefined>;