@martinloop/mcp 0.8.8 → 0.8.9

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const MARTIN_MCP_PACKAGE_VERSION = "0.8.8";
+export declare const MARTIN_MCP_PACKAGE_VERSION = "0.8.9";

package/dist/package-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by build — do not edit by hand.
 // Source of truth: packages/mcp/package.json#version
-export const MARTIN_MCP_PACKAGE_VERSION = "0.8.8";
+export const MARTIN_MCP_PACKAGE_VERSION = "0.8.9";

package/dist/server-validation.js

@@ -145,6 +145,7 @@ function validateRunInput(args) {
         "workingDirectory",
         "engine",
         "model",
+        "fallbackEngines",
         "context",
         "policyPack",
         "maxUsd",
@@ -169,6 +170,7 @@ function validateRunInput(args) {
             : {}),
         ...(engine ? { engine } : {}),
         ...optionalString(record.model, "model"),
+        ...optionalEnumArrayAsObject(record.fallbackEngines, "fallbackEngines", MARTIN_ENGINE_VALUES),
         ...optionalString(record.context, "context"),
         ...optionalEnumAsObject(record.policyPack, "policyPack", [
             "solo-founder",
@@ -643,3 +645,19 @@ function optionalEnumAsObject(value, name, allowed) {
     const enumValue = optionalEnum(value, name, allowed);
     return enumValue ? { [name]: enumValue } : {};
 }
+function optionalEnumArrayAsObject(value, name, allowed) {
+    if (value === undefined)
+        return {};
+    if (!Array.isArray(value))
+        throw invalidArgumentsError(`Invalid ${name}.`);
+    const values = value.map((item) => {
+        if (typeof item !== "string" || !allowed.includes(item)) {
+            throw invalidArgumentsError(`Invalid ${name}.`);
+        }
+        return item;
+    });
+    if (new Set(values).size !== values.length) {
+        throw invalidArgumentsError(`Invalid ${name}: duplicate engines are not allowed.`);
+    }
+    return { [name]: values };
+}

package/dist/server.js

@@ -935,7 +935,16 @@ export function createMartinMcpServer(serverInfo) {
                         },
                         model: {
                             type: "string",
-                            description: "Optional model override passed to the CLI."
+                            description: "Optional model override passed to the primary provider."
+                        },
+                        fallbackEngines: {
+                            type: "array",
+                            uniqueItems: true,
+                            items: {
+                                type: "string",
+                                enum: [...MARTIN_ENGINE_VALUES]
+                            },
+                            description: "Explicit ordered provider fallbacks authorized for this run. No provider is added implicitly."
                         },
                         maxUsd: {
                             type: "number",

package/dist/tools/run-loop.d.ts

@@ -7,6 +7,8 @@ export interface RunLoopInput {
     workingDirectory?: string;
     engine?: MartinEngine;
     model?: string;
+    /** Explicit ordered provider fallbacks authorized by the caller. */
+    fallbackEngines?: MartinEngine[];
     maxUsd?: number;
     maxIterations?: number;
     maxTokens?: number;

package/dist/tools/run-loop.js

@@ -1,4 +1,4 @@
-import { createClaudeCliAdapter, createCodexCliAdapter, createGeminiCliAdapter, probeCodexLaunch, resolveCliCommandAvailability, createVerifierOnlyAdapter } from "../vendor/adapters/index.js";
+import { createClaudeCliAdapter, createCodexCliAdapter, createGeminiCliAdapter, createOpenAiCompatibleAdapter, resolveOpenAiCompatibleRuntimeConfig, probeCodexLaunch, resolveCliCommandAvailability, createVerifierOnlyAdapter } from "../vendor/adapters/index.js";
 import { createFileRunStore, evaluateCostGovernor, resolveRunsRoot, runMartin } from "../vendor/core/index.js";
 import { normalizeSafePathPatterns, resolveSafeRepoRoot } from "../server-validation.js";
 import { MartinToolError } from "./tool-errors.js";
@@ -12,10 +12,131 @@ export function __setProofModeVerifierSpawnImplForTests(spawnImpl) {
 export function __setRunStoreOverrideForTests(store) {
     runStoreOverrideForTests = store;
 }
+function assertAuthorizedFallbackEngines(primary, fallbacks) {
+    const seen = new Set();
+    for (const fallback of fallbacks) {
+        if (fallback === primary) {
+            throw new MartinToolError("invalid_arguments", "Fallback chain cannot repeat the primary engine.", {
+                category: "invalid_input",
+                retryable: false
+            });
+        }
+        if (seen.has(fallback)) {
+            throw new MartinToolError("invalid_arguments", `Duplicate fallback engine '${fallback}'.`, {
+                category: "invalid_input",
+                retryable: false
+            });
+        }
+        seen.add(fallback);
+    }
+}
+function ensureLiveEngineReady(engine, workingDirectory, providerExecutionTimeoutMs) {
+    if (engine === "openai") {
+        const config = resolveOpenAiCompatibleRuntimeConfig();
+        const localEndpoint = /^(?:https?:\/\/)?(?:localhost|127\.0\.0\.1|\[::1\])(?::|\/|$)/iu.test(config.baseUrl);
+        if (!config.model) {
+            throw new MartinToolError("engine_unavailable", "Authorized OpenAI-compatible fallback has no configured model.", {
+                category: "environment",
+                suggestion: "Set MARTIN_OPENAI_MODEL before authorizing the OpenAI fallback.",
+                retryable: false
+            });
+        }
+        if (!config.apiKeyConfigured && !localEndpoint) {
+            throw new MartinToolError("engine_unavailable", "Authorized OpenAI-compatible fallback is not authenticated.", {
+                category: "environment",
+                suggestion: "Set MARTIN_OPENAI_API_KEY, or use an explicitly local OpenAI-compatible endpoint.",
+                retryable: false
+            });
+        }
+        return undefined;
+    }
+    if (engine === "codex") {
+        const availability = resolveCliCommandAvailability("codex");
+        if (!availability.available) {
+            throw new MartinToolError("engine_unavailable", "Engine 'codex' is not available on PATH.", {
+                category: "environment",
+                suggestion: "Install/authenticate Codex before authorizing it for governed execution.",
+                retryable: false
+            });
+        }
+        const probe = probeCodexLaunch({
+            workingDirectory,
+            availability,
+            ...(providerExecutionTimeoutMs !== undefined ? { providerExecutionTimeoutMs } : {})
+        });
+        if (!probe.ok) {
+            throw new MartinToolError("engine_unavailable", probe.summary, {
+                category: "environment",
+                suggestion: "Run martin_doctor or martin_preflight with engine='codex' before retrying.",
+                retryable: false
+            });
+        }
+        return probe;
+    }
+    const availability = getEngineAvailability(engine);
+    if (!availability.available) {
+        throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
+            category: "environment",
+            suggestion: "Install/authenticate every provider explicitly listed in the fallback chain.",
+            retryable: false
+        });
+    }
+    return undefined;
+}
+function createLiveEngineAdapter(input) {
+    if (input.engine === "codex") {
+        return createCodexCliAdapter({
+            workingDirectory: input.workingDirectory,
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+            ...(input.providerExecutionTimeoutMs !== undefined
+                ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
+                : {}),
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.codexProbe
+                ? {
+                    command: input.codexProbe.command,
+                    capabilityProfile: input.codexProbe.capabilityProfile,
+                    autonomyResolution: input.codexProbe.autonomyResolution
+                }
+                : {})
+        });
+    }
+    if (input.engine === "gemini") {
+        return createGeminiCliAdapter({
+            workingDirectory: input.workingDirectory,
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+            ...(input.providerExecutionTimeoutMs !== undefined
+                ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
+                : {}),
+            ...(input.model ? { model: input.model } : {})
+        });
+    }
+    if (input.engine === "openai") {
+        const config = resolveOpenAiCompatibleRuntimeConfig();
+        const resolvedModel = input.model ?? config.model;
+        return createOpenAiCompatibleAdapter({
+            baseUrl: config.baseUrl,
+            apiKey: config.apiKey,
+            ...(resolvedModel ? { model: resolvedModel } : {}),
+            workingDirectory: input.workingDirectory,
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {})
+        });
+    }
+    return createClaudeCliAdapter({
+        workingDirectory: input.workingDirectory,
+        ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+        ...(input.providerExecutionTimeoutMs !== undefined
+            ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
+            : {}),
+        ...(input.model ? { model: input.model } : {})
+    });
+}
 export async function runLoopTool(input) {
     const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
     const engine = input.engine ?? "claude";
     const model = input.model;
+    const fallbackEngines = input.fallbackEngines ?? [];
+    assertAuthorizedFallbackEngines(engine, fallbackEngines);
     const allowedPaths = normalizeSafePathPatterns(input.allowedPaths, "allowedPaths");
     const deniedPaths = normalizeSafePathPatterns(input.deniedPaths, "deniedPaths");
     const executionMode = resolveExecutionMode();
@@ -31,41 +152,11 @@ export async function runLoopTool(input) {
         runsRoot
     };
     let codexProbeOverride;
+    const fallbackProbeOverrides = new Map();
     if (executionMode.liveMode) {
-        if (engine === "codex") {
-            const engineAvailability = resolveCliCommandAvailability("codex");
-            if (!engineAvailability.available) {
-                throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
-                    category: "environment",
-                    suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
-                    retryable: false
-                });
-            }
-            const codexProbe = probeCodexLaunch({
-                workingDirectory,
-                availability: engineAvailability,
-                ...(input.providerExecutionTimeoutMs !== undefined
-                    ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
-                    : {})
-            });
-            if (!codexProbe.ok) {
-                throw new MartinToolError("engine_unavailable", codexProbe.summary, {
-                    category: "environment",
-                    suggestion: "Run martin_doctor or martin_preflight with engine='codex' before retrying live governed work.",
-                    retryable: false
-                });
-            }
-            codexProbeOverride = codexProbe;
-        }
-        else {
-            const engineAvailability = getEngineAvailability(engine);
-            if (!engineAvailability.available) {
-                throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
-                    category: "environment",
-                    suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
-                    retryable: false
-                });
-            }
+        codexProbeOverride = ensureLiveEngineReady(engine, workingDirectory, input.providerExecutionTimeoutMs);
+        for (const fallbackEngine of fallbackEngines) {
+            fallbackProbeOverrides.set(fallbackEngine, ensureLiveEngineReady(fallbackEngine, workingDirectory, input.providerExecutionTimeoutMs));
         }
     }
     const adapter = !executionMode.liveMode
@@ -75,39 +166,35 @@ export async function runLoopTool(input) {
             ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
             ...(proofModeVerifierSpawnImpl ? { spawnImpl: proofModeVerifierSpawnImpl } : {})
         })
-        : engine === "codex"
-            ? createCodexCliAdapter({
-                workingDirectory,
-                ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
-                ...(input.providerExecutionTimeoutMs !== undefined
-                    ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
-                    : {}),
-                ...(model ? { model } : {}),
-                ...(codexProbeOverride
-                    ? {
-                        command: codexProbeOverride.command,
-                        capabilityProfile: codexProbeOverride.capabilityProfile,
-                        autonomyResolution: codexProbeOverride.autonomyResolution
-                    }
-                    : {})
-            })
-            : engine === "gemini"
-                ? createGeminiCliAdapter({
-                    workingDirectory,
-                    ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
-                    ...(input.providerExecutionTimeoutMs !== undefined
-                        ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
-                        : {}),
-                    ...(model ? { model } : {})
-                })
-                : createClaudeCliAdapter({
-                    workingDirectory,
-                    ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
-                    ...(input.providerExecutionTimeoutMs !== undefined
-                        ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
-                        : {}),
-                    ...(model ? { model } : {})
-                });
+        : createLiveEngineAdapter({
+            engine,
+            workingDirectory,
+            ...(model ? { model } : {}),
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+            ...(input.providerExecutionTimeoutMs !== undefined
+                ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
+                : {}),
+            ...(codexProbeOverride ? { codexProbe: codexProbeOverride } : {})
+        });
+    if (!executionMode.liveMode && fallbackEngines.length > 0) {
+        throw new MartinToolError("invalid_arguments", "fallbackEngines are available only in live governed mode.", {
+            category: "invalid_input",
+            retryable: false
+        });
+    }
+    const fallbackAdapters = executionMode.liveMode
+        ? fallbackEngines.map((fallbackEngine) => createLiveEngineAdapter({
+            engine: fallbackEngine,
+            workingDirectory,
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+            ...(input.providerExecutionTimeoutMs !== undefined
+                ? { providerExecutionTimeoutMs: input.providerExecutionTimeoutMs }
+                : {}),
+            ...(fallbackProbeOverrides.get(fallbackEngine)
+                ? { codexProbe: fallbackProbeOverrides.get(fallbackEngine) }
+                : {})
+        }))
+        : [];
     const partialBudget = {};
     if (input.maxUsd !== undefined) {
         partialBudget.maxUsd = input.maxUsd;
@@ -141,9 +228,14 @@ export async function runLoopTool(input) {
         budget,
         metadata: {
             executionMode: evidenceExecutionMode,
-            governanceClaimEligible: evidenceExecutionMode === "governed" ? "true" : "false"
+            governanceClaimEligible: evidenceExecutionMode === "governed" ? "true" : "false",
+            ...(executionMode.liveMode ? { authorizedPrimaryEngine: engine } : {}),
+            ...(executionMode.liveMode && fallbackEngines.length > 0
+                ? { authorizedFallbackEngines: fallbackEngines.join(",") }
+                : {})
         },
-        adapter
+        adapter,
+        ...(fallbackAdapters.length > 0 ? { fallbackAdapters } : {})
     });
     const lastAttempt = result.loop.attempts.at(-1);
     // D5: verificationPassed must reflect authoritative verifier execution/binding,
@@ -153,6 +245,12 @@ export async function runLoopTool(input) {
     const verificationPassed = lastAttempt !== undefined &&
         result.decision.lifecycleState === "completed" &&
         (lastAttempt.verifierScore ?? 0) >= 1;
+    const fallbackAdapterIndex = lastAttempt
+        ? fallbackAdapters.findIndex((candidate) => candidate.adapterId === lastAttempt.adapterId)
+        : -1;
+    const effectiveEngine = fallbackAdapterIndex >= 0
+        ? (fallbackEngines[fallbackAdapterIndex] ?? engine)
+        : engine;
     const costState = evaluateCostGovernor({
         budget: result.loop.budget,
         cost: {
@@ -183,7 +281,7 @@ export async function runLoopTool(input) {
         ...(costState.remainingTokens !== undefined
             ? { remainingTokens: costState.remainingTokens }
             : {}),
-        engine,
+        engine: effectiveEngine,
         workingDirectory,
         budget,
         inspection: {

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

@@ -1,4 +1,4 @@
-import { type ApprovalPolicy, type AgentExecutionIntent, type ContextHandoffReceipt, type CostProvenance, type ExecutionProfile, type ExternalOutcomeEvidenceReference, type FailureClass, type InterventionType, type LoopArtifact, type LoopAttempt, type LoopBudget, type ProviderUsageSettlement, type MutationMode, type LoopRecord, type LoopTask, type ReceiptScope } from "../contracts/index.js";
+import { type ApprovalPolicy, type AgentExecutionIntent, type ContextHandoffReceipt, type CostProvenance, type ExecutionProfile, type ExternalOutcomeEvidenceReference, type FailureClass, type InterventionType, type LoopArtifact, type LoopAttempt, type LoopBudget, type ProviderUsageSettlement, type MutationMode, type LoopRecord, type LoopTask, type ReceiptScope, type RollbackBoundaryArtifact } 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";
@@ -7,6 +7,7 @@ import { type RunStore } from "./persistence/index.js";
 import { type ExitPolicyOverrides } from "./exits.js";
 import { type ExitSignalSource } from "./exit-signal.js";
 import { type VerifierExecutionBinding } from "./verified-handoff.js";
+import { acquireRunExecutionLease, evaluateRunResumability, loadResumeCandidateBoundary, loadResumeVerifierFailure } from "./resume.js";
 export type { AgentExecutionIntent, ApprovalPolicy, BudgetPreflightEstimate, BudgetSettlement, CostProvenance, EvidenceVector, ExecutionProfile, FailureClass, InterventionType, PatchDecision, PatchDecisionArtifact, PatchDecisionReasonCode, PatchScore, MutationMode, RollbackBoundaryArtifact, RollbackBoundaryStrategy, RollbackFileSnapshot, RollbackOutcomeArtifact, RollbackOutcomeStatus, PolicyPhase, CallStage, AgentRole, FirstDelta, RoutingEconomics } from "../contracts/index.js";
 export { DEFAULT_AGENT_EXECUTION_INTENT, DEFAULT_PROVIDER_EXECUTION_TIMEOUT_MS, GOVERNED_AUTONOMOUS_BOUNDARY, normalizeProviderExecutionTimeoutMs } 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, listAttemptChangedFilesSinceBoundary, listIgnoredFileChangesSinceBoundary, restoreRollbackBoundary };
@@ -22,6 +23,7 @@ export type { LocalIdentityAuthority } from "./identity.js";
 export { compileExecutionPolicy } from "./policy-compiler.js";
 export { assessTrajectory, decideCircuitBreak } from "./trajectory.js";
 export { calculateAvoidedUsd, calculateLoopAvoidedUsd } from "./savings.js";
+export { acquireRunExecutionLease, evaluateRunResumability, loadResumeCandidateBoundary, loadResumeVerifierFailure };
 export type { AvoidedUsdInput } from "./savings.js";
 export { classifyRoute, evaluatePreworkBurnPolicy } from "./routing.js";
 export type { RouteDecision, RouteClassificationInput } from "./routing.js";
@@ -257,6 +259,15 @@ export interface RunMartinInput {
     idFactory?: (prefix: string) => string;
     maxRecentAttempts?: number;
     fallbackAdapters?: MartinAdapter[];
+    /**
+     * Continue an unfinished persisted run under the same loop ID and authority.
+     * runMartin acquires the durable execution lease before any store persistence.
+     */
+    resume?: {
+        loop: LoopRecord;
+        preCandidateBoundary?: RollbackBoundaryArtifact;
+        lastVerifierFailure?: MartinAdapterRequest["context"]["lastVerifierFailure"];
+    };
     receiptScope?: ReceiptScope;
     /** Optional persistence store. When provided, runMartin writes artifacts on each lifecycle event. */
     store?: RunStore;