@martinloop/mcp 0.5.0 → 0.5.1

package/dist/resources.js

@@ -37,6 +37,16 @@ export const MARTIN_STATIC_RESOURCE_URIS = {
     modeStatus: "martin://agent/mode-status",
     memorySummary: "martin://agent/memory-summary"
 };
+function formatRecordedCost(usd, provenance) {
+    if (provenance === "unavailable")
+        return "unavailable";
+    if (provenance === "actual")
+        return `$${usd.toFixed(2)} provider-settled actual`;
+    if (provenance === "calculated") {
+        return `$${usd.toFixed(2)} calculated from observed usage`;
+    }
+    return `$${usd.toFixed(2)} estimated`;
+}
 export const MARTIN_RESOURCE_TEMPLATES = [
     {
         name: "martin_run_record",
@@ -376,7 +386,7 @@ async function loadLatestRunForCompactResource(runsRoot) {
                 empty: true,
                 warnings: [
                     "No Martin run records were found yet.",
-                    "Run `npx martin-loop demo`, then run `npx martin-loop run ... --proof --verify <command>` for a no-spend local proof pass."
+                    "Run `npx martin-loop demo`, then use `--proof --verify <command>` for explicitly non-governed verification-only evidence."
                 ]
             };
         }
@@ -404,6 +414,7 @@ async function buildLatestSummaryResource(runsRoot) {
         budget: loop.budget,
         cost: {
             actualUsd: loop.cost.actualUsd,
+            provenance: loop.cost.provenance ?? "unavailable",
             avoidedUsdEstimate: loop.cost.avoidedUsd ?? 0,
             tokensIn: loop.cost.tokensIn,
             tokensOut: loop.cost.tokensOut,
@@ -439,6 +450,7 @@ async function buildLatestBudgetStatusResource(runsRoot) {
         budget: loop.budget,
         cost: {
             actualUsd: loop.cost.actualUsd,
+            provenance: loop.cost.provenance ?? "unavailable",
             avoidedUsdEstimate: loop.cost.avoidedUsd ?? 0,
             tokensIn: loop.cost.tokensIn,
             tokensOut: loop.cost.tokensOut,
@@ -575,7 +587,7 @@ async function buildLatestProofCardResource(runsRoot) {
         `Run: \`${loop.loopId}\``,
         `Status: ${loop.status} / ${loop.lifecycleState}`,
         `Attempts: ${loop.attempts.length}`,
-        `Spend: $${loop.cost.actualUsd.toFixed(2)} actual, $${(loop.cost.avoidedUsd ?? 0).toFixed(2)} avoided estimate`,
+        `Spend: ${formatRecordedCost(loop.cost.actualUsd, loop.cost.provenance ?? "unavailable")}, $${(loop.cost.avoidedUsd ?? 0).toFixed(2)} avoided estimate`,
         `Tokens: ${loop.cost.tokensIn} in / ${loop.cost.tokensOut} out`,
         `Verifier: ${verifierStatus}`,
         "",
@@ -599,7 +611,7 @@ function compactEmptyState(kind, runsRoot, warnings) {
         status: "empty",
         runsRoot,
         summary: "No Martin run records are available yet.",
-        nextStep: "Run `npx martin-loop doctor`, create the demo workspace with `npx martin-loop demo`, then run `npx martin-loop run ... --proof --verify <command>`.",
+        nextStep: "Run `npx martin-loop doctor`, create the demo workspace, then use `--proof --verify <command>` only for non-governed verification evidence.",
         warnings
     };
 }

package/dist/server.js

@@ -55,6 +55,15 @@ const stringArraySchema = {
     type: "array",
     items: { type: "string" }
 };
+function describeCostProvenance(provenance) {
+    if (provenance === "actual")
+        return "provider-settled actual";
+    if (provenance === "calculated")
+        return "calculated from observed usage";
+    if (provenance === "estimated")
+        return "estimated";
+    return "unavailable";
+}
 const loopPreviewSchema = {
     type: "object",
     additionalProperties: true,
@@ -68,6 +77,10 @@ const loopPreviewSchema = {
         updatedAt: { type: "string" },
         attempts: { type: "integer" },
         costUsd: { type: "number" },
+        costProvenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        },
         avoidedUsd: { type: "number" },
         pressure: { type: "string" },
         shouldStop: { type: "boolean" },
@@ -87,6 +100,7 @@ const loopPreviewSchema = {
         "lifecycleState",
         "attempts",
         "costUsd",
+        "costProvenance",
         "avoidedUsd",
         "pressure",
         "shouldStop",
@@ -113,9 +127,13 @@ const costSchema = {
         actualUsd: { type: "number" },
         avoidedUsd: { type: "number" },
         tokensIn: { type: "integer" },
-        tokensOut: { type: "integer" }
+        tokensOut: { type: "integer" },
+        provenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        }
     },
-    required: ["actualUsd", "avoidedUsd", "tokensIn", "tokensOut"]
+    required: ["actualUsd", "avoidedUsd", "tokensIn", "tokensOut", "provenance"]
 };
 const verificationSchema = {
     type: "object",
@@ -248,6 +266,10 @@ const runOutputSchema = {
         reason: { type: "string" },
         attempts: { type: "integer" },
         costUsd: { type: "number" },
+        costProvenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        },
         verificationPassed: { type: "boolean" },
         loopId: { type: "string" },
         pressure: { type: "string" },
@@ -279,6 +301,7 @@ const runOutputSchema = {
         "reason",
         "attempts",
         "costUsd",
+        "costProvenance",
         "verificationPassed",
         "loopId",
         "pressure",
@@ -346,6 +369,10 @@ const statusOutputSchema = {
         lifecycleState: { type: "string" },
         attempts: { type: "integer" },
         costUsd: { type: "number" },
+        costProvenance: {
+            type: "string",
+            enum: ["actual", "calculated", "estimated", "unavailable"]
+        },
         avoidedUsd: { type: "number" },
         pressure: { type: "string" },
         shouldStop: { type: "boolean" },
@@ -369,6 +396,7 @@ const statusOutputSchema = {
         "lifecycleState",
         "attempts",
         "costUsd",
+        "costProvenance",
         "avoidedUsd",
         "pressure",
         "shouldStop",
@@ -1503,17 +1531,22 @@ export function createMartinMcpServer(serverInfo) {
                     });
                 }
                 const output = await runLoopTool(input);
-                return createToolSuccessResult(output, `Run ${output.loopId} is ${output.status}/${output.lifecycleState} after ${output.attempts} attempt(s); spend ${output.costUsd.toFixed(2)} USD.`);
+                return createToolSuccessResult(output, [
+                    `Run ${output.loopId} is ${output.status}/${output.lifecycleState}`,
+                    `after ${output.attempts} attempt(s); recorded cost ${output.costUsd.toFixed(2)} USD (${describeCostProvenance(output.costProvenance)}).`,
+                    `Execution mode: ${output.executionMode}; governance claim eligible:`,
+                    `${output.governanceClaimEligible ? "yes" : "no"}.`
+                ].join(" "));
             }
             if (name === "martin_inspect") {
                 const input = validateToolInput("martin_inspect", args);
                 const output = await inspectLoopTool(input);
-                return createToolSuccessResult(output, `Inspected ${output.loopCount} run(s) from ${output.source}; total actual spend ${output.portfolio.totalActualUsd.toFixed(2)} USD.`);
+                return createToolSuccessResult(output, `Inspected ${output.loopCount} run(s) from ${output.source}; total recorded cost ${output.portfolio.totalActualUsd.toFixed(2)} USD.`);
             }
             if (name === "martin_status") {
                 const input = validateToolInput("martin_status", args);
                 const output = await getStatusTool(input);
-                return createToolSuccessResult(output, `Loop ${output.loopId} is ${output.status}/${output.lifecycleState}; pressure is ${output.pressure} with ${output.remainingBudgetUsd.toFixed(2)} USD remaining.`);
+                return createToolSuccessResult(output, `Loop ${output.loopId} is ${output.status}/${output.lifecycleState}; recorded cost is ${output.costUsd.toFixed(2)} USD (${describeCostProvenance(output.costProvenance)}), and pressure is ${output.pressure} with ${output.remainingBudgetUsd.toFixed(2)} USD remaining.`);
             }
             if (name === "martin_doctor") {
                 const input = validateToolInput("martin_doctor", args);
@@ -1671,8 +1704,7 @@ export function createMartinMcpServer(serverInfo) {
                     compressed: route.compressed,
                     ...(route.compressionSummary ? { compressionSummary: route.compressionSummary } : {}),
                     recommendedBudgetUsd,
-                    recommendedModelTier: route.recommendedModelTier,
-                    estimatedSavingVsSonnetUsd: route.estimatedSavingVsSonnetUsd
+                    modelAuthority: "agent_or_provider_default"
                 };
                 await recordMcpWorkflowStep({
                     runsRoot,
@@ -1687,7 +1719,7 @@ export function createMartinMcpServer(serverInfo) {
                         runsRoot
                     }
                 }).catch(() => { });
-                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route (${route.recommendedModelTier}), ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
+                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route, ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Model authority remains with the agent/provider. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
             }
             return createToolErrorResult(toToolFailure(new Error(`Unknown tool: ${name}`)));
         }

package/dist/tools/doctor.js

@@ -115,10 +115,11 @@ export async function martinDoctorTool(input) {
                 ...(gemini.resolvedPath ? { resolvedPath: gemini.resolvedPath } : {})
             },
             openai: {
-                available: Boolean(process.env.MARTIN_OPENAI_API_KEY),
-                detail: process.env.MARTIN_OPENAI_API_KEY
-                    ? `OpenAI-compatible endpoint configured (model: ${process.env.MARTIN_OPENAI_MODEL ?? "gpt-4.1-mini"})`
-                    : "Set MARTIN_OPENAI_API_KEY and optionally MARTIN_OPENAI_BASE_URL + MARTIN_OPENAI_MODEL to enable."
+                available: Boolean(process.env.MARTIN_OPENAI_MODEL &&
+                    (process.env.MARTIN_OPENAI_API_KEY || process.env.MARTIN_OPENAI_BASE_URL)),
+                detail: process.env.MARTIN_OPENAI_MODEL
+                    ? `OpenAI-compatible model configured: ${process.env.MARTIN_OPENAI_MODEL}.`
+                    : "MODEL_CONFIGURATION_REQUIRED: set MARTIN_OPENAI_MODEL and the endpoint/auth required by your provider."
             }
         },
         ...(input.engine ? { requestedEngine: input.engine } : {}),

package/dist/tools/get-status.d.ts

@@ -1,3 +1,4 @@
+import type { CostProvenance } from "../vendor/contracts/index.js";
 import { type LoopPreview } from "./tool-support.js";
 export interface GetStatusInput {
     /** JSON-serialized LoopRecord. */
@@ -18,6 +19,7 @@ export interface GetStatusOutput {
     lifecycleState: string;
     attempts: number;
     costUsd: number;
+    costProvenance: CostProvenance;
     avoidedUsd: number;
     pressure: string;
     shouldStop: boolean;

package/dist/tools/get-status.js

@@ -31,6 +31,7 @@ export async function getStatusTool(input) {
         lifecycleState: loop.lifecycleState,
         attempts: loop.attempts.length,
         costUsd: loop.cost.actualUsd,
+        costProvenance: loop.cost.provenance ?? "unavailable",
         avoidedUsd: loop.cost.avoidedUsd ?? 0,
         pressure: costState.pressure,
         shouldStop: costState.shouldStop,

package/dist/tools/preflight.js

@@ -36,7 +36,7 @@ export async function martinPreflightTool(input) {
         maxTokens: input.maxTokens
     });
     if (!executionMode.liveMode) {
-        warnings.push("Proof mode is active; preflight only proves configuration shape, not live CLI readiness.");
+        warnings.push("Verification-only mode is active; it cannot emit governed VERIFIED or prove live CLI readiness.");
     }
     else if (!engineAvailability.available) {
         warnings.push(`Requested engine '${engine}' is not available on PATH.`);

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

@@ -1,5 +1,6 @@
+import { type SpawnLike } from "../vendor/adapters/index.js";
 import { type RunStore } from "../vendor/core/index.js";
-import type { LoopBudget, ReceiptScope } from "../vendor/contracts/index.js";
+import type { CostProvenance, ExecutionMode, LoopBudget, ReceiptScope } from "../vendor/contracts/index.js";
 import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, type MartinEngine } from "./tool-support.js";
 export interface RunLoopInput {
     objective: string;
@@ -22,7 +23,10 @@ export interface RunLoopOutput {
     reason: string;
     attempts: number;
     costUsd: number;
+    costProvenance: CostProvenance;
     verificationPassed: boolean;
+    executionMode: ExecutionMode;
+    governanceClaimEligible: boolean;
     loopId: string;
     pressure: string;
     shouldStop: boolean;
@@ -43,5 +47,6 @@ export interface RunLoopOutput {
         artifacts: ReturnType<typeof buildArtifactSummary>;
     };
 }
+export declare function __setProofModeVerifierSpawnImplForTests(spawnImpl?: SpawnLike): void;
 export declare function __setRunStoreOverrideForTests(store?: RunStore): void;
 export declare function runLoopTool(input: RunLoopInput): Promise<RunLoopOutput>;

package/dist/tools/run-loop.js

@@ -1,10 +1,14 @@
-import { createClaudeCliAdapter, createCodexCliAdapter, createGeminiCliAdapter, createStubDirectProviderAdapter, probeCodexLaunch, resolveCliCommandAvailability } from "../vendor/adapters/index.js";
+import { createClaudeCliAdapter, createCodexCliAdapter, createGeminiCliAdapter, createVerifierOnlyAdapter, probeCodexLaunch, resolveCliCommandAvailability } 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";
 import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, buildRunRecordPaths, getEngineAvailability, resolveExecutionMode } from "./tool-support.js";
 import { normalizeLoopBudget } from "./workflow-governance.js";
+let proofModeVerifierSpawnImpl;
 let runStoreOverrideForTests;
+export function __setProofModeVerifierSpawnImplForTests(spawnImpl) {
+    proofModeVerifierSpawnImpl = spawnImpl;
+}
 export function __setRunStoreOverrideForTests(store) {
     runStoreOverrideForTests = store;
 }
@@ -15,6 +19,9 @@ export async function runLoopTool(input) {
     const allowedPaths = normalizeSafePathPatterns(input.allowedPaths, "allowedPaths");
     const deniedPaths = normalizeSafePathPatterns(input.deniedPaths, "deniedPaths");
     const executionMode = resolveExecutionMode();
+    const evidenceExecutionMode = executionMode.liveMode
+        ? "governed"
+        : "verification_only";
     const workspaceRoot = resolveSafeRepoRoot();
     const runsRoot = resolveRunsRoot(process.env);
     const receiptScope = {
@@ -30,7 +37,7 @@ export async function runLoopTool(input) {
             if (!engineAvailability.available) {
                 throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
                     category: "environment",
-                    suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
+                    suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
                     retryable: false
                 });
             }
@@ -52,17 +59,18 @@ export async function runLoopTool(input) {
             if (!engineAvailability.available) {
                 throw new MartinToolError("engine_unavailable", `Engine '${engine}' is not available on PATH.`, {
                     category: "environment",
-                    suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
+                    suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
                     retryable: false
                 });
             }
         }
     }
     const adapter = !executionMode.liveMode
-        ? createStubDirectProviderAdapter({
-            label: "Proof mode stub adapter (MARTIN_LIVE=false)",
-            providerId: "stub",
-            model: "stub"
+        ? createVerifierOnlyAdapter({
+            workingDirectory,
+            label: "Verification-only adapter (MARTIN_LIVE=false)",
+            ...(input.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: input.verifyTimeoutMs } : {}),
+            ...(proofModeVerifierSpawnImpl ? { spawnImpl: proofModeVerifierSpawnImpl } : {})
         })
         : engine === "codex"
             ? createCodexCliAdapter({
@@ -110,6 +118,10 @@ export async function runLoopTool(input) {
             ...(deniedPaths ? { deniedPaths } : {})
         },
         budget,
+        metadata: {
+            executionMode: evidenceExecutionMode,
+            governanceClaimEligible: evidenceExecutionMode === "governed" ? "true" : "false"
+        },
         adapter
     });
     const lastAttempt = result.loop.attempts.at(-1);
@@ -133,7 +145,10 @@ export async function runLoopTool(input) {
         reason: result.decision.reason,
         attempts: result.loop.attempts.length,
         costUsd: result.loop.cost.actualUsd,
+        costProvenance: result.loop.cost.provenance ?? "unavailable",
         verificationPassed,
+        executionMode: evidenceExecutionMode,
+        governanceClaimEligible: evidenceExecutionMode === "governed",
         loopId: result.loop.loopId,
         pressure: costState.pressure,
         shouldStop: costState.shouldStop,

package/dist/tools/tool-errors.js

@@ -92,7 +92,7 @@ export function toToolFailure(error) {
             code: "engine_unavailable",
             category: "environment",
             message,
-            suggestion: "Install the requested CLI or set MARTIN_LIVE=false for a no-spend proof run.",
+            suggestion: "Install the requested CLI. MARTIN_LIVE=false is verification-only and cannot emit governed VERIFIED.",
             retryable: false
         };
     }

package/dist/tools/tool-response.js

@@ -4,13 +4,20 @@ function createJsonBlock(output) {
         text: JSON.stringify(output, null, 2)
     };
 }
+function resolveHumanArtifact(output, summary) {
+    const rendered = "rendered" in output ? output.rendered : undefined;
+    return typeof rendered === "string" && rendered.trim().length > 0 ? rendered : summary;
+}
 export function createToolSuccessResult(output, summary) {
     return {
-        content: [createJsonBlock(output), { type: "text", text: summary }],
+        content: [
+            { type: "text", text: resolveHumanArtifact(output, summary) },
+            createJsonBlock(output)
+        ],
         structuredContent: output,
         _meta: {
             "martinloop/summary": summary,
-            "martinloop/contentVersion": "2026-05-15"
+            "martinloop/contentVersion": "2026-08-18"
         }
     };
 }

package/dist/tools/tool-support.d.ts

@@ -1,4 +1,4 @@
-import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope, TerminationEnvelopeV1 } from "../vendor/contracts/index.js";
+import type { CostProvenance, LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope, TerminationEnvelopeV1 } from "../vendor/contracts/index.js";
 import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "../vendor/core/index.js";
 export declare const MARTIN_ENGINE_VALUES: readonly ["claude", "codex", "gemini", "openai"];
 export type MartinEngine = (typeof MARTIN_ENGINE_VALUES)[number];
@@ -27,6 +27,7 @@ export interface LoopPreview {
     updatedAt?: string;
     attempts: number;
     costUsd: number;
+    costProvenance: CostProvenance;
     avoidedUsd: number;
     pressure: string;
     shouldStop: boolean;
@@ -128,7 +129,7 @@ export declare function inspectRunsRoot(runsRoot?: string): Promise<RunStoreInsp
 export declare function buildRunRecordPaths(runsRoot: string, loopId: string): CanonicalRunPaths;
 export declare function buildAttemptArtifactDirectory(runsRoot: string, loopId: string, attemptIndex: number): string;
 export declare function buildAttemptArtifactsReference(runsRoot: string, loopId: string, attemptIndex: number): Promise<AttemptArtifactFiles>;
-export declare function buildCostSnapshot(cost: Pick<LoopCost, "actualUsd" | "tokensIn" | "tokensOut"> & {
+export declare function buildCostSnapshot(cost: Pick<LoopCost, "actualUsd" | "tokensIn" | "tokensOut" | "provenance"> & {
     avoidedUsd?: number;
 }): LoopCost;
 export declare function buildBudgetSnapshot(budget: LoopBudget): LoopBudget;

package/dist/tools/tool-support.js

@@ -15,7 +15,7 @@ export function resolveExecutionMode() {
         mode: liveMode ? "live" : "proof",
         detail: liveMode
             ? "Live CLI execution is enabled."
-            : "Proof mode is active because MARTIN_LIVE=false."
+            : "Verification-only mode is active because MARTIN_LIVE=false; governed VERIFIED is unavailable."
     };
 }
 export function detectCliAvailability(command) {
@@ -175,7 +175,7 @@ function suggestInstallCommand(command) {
 export function getEngineAvailability(engine) {
     return detectCliAvailability(engine);
 }
-export function createSkippedCliAvailability(command, detail = "Proof mode skipped live CLI availability detection.") {
+export function createSkippedCliAvailability(command, detail = "Verification-only mode skipped live CLI availability detection; governed VERIFIED is unavailable.") {
     return {
         command,
         available: false,
@@ -208,6 +208,7 @@ export function buildLoopPreview(loop) {
         ...(loop.updatedAt ? { updatedAt: loop.updatedAt } : {}),
         attempts: loop.attempts.length,
         costUsd: loop.cost.actualUsd,
+        costProvenance: loop.cost.provenance ?? "unavailable",
         avoidedUsd: loop.cost.avoidedUsd ?? 0,
         pressure: costState.pressure,
         shouldStop: costState.shouldStop,
@@ -411,7 +412,8 @@ export function buildCostSnapshot(cost) {
         actualUsd: cost.actualUsd,
         avoidedUsd: cost.avoidedUsd ?? 0,
         tokensIn: cost.tokensIn,
-        tokensOut: cost.tokensOut
+        tokensOut: cost.tokensOut,
+        provenance: cost.provenance ?? "unavailable"
     };
 }
 export function buildBudgetSnapshot(budget) {

package/dist/vendor/adapters/claude-cli.d.ts

@@ -96,7 +96,7 @@ export interface GeminiCliAdapterOptions {
     timeoutMs?: number;
     verifyTimeoutMs?: number;
     label?: string;
-    /** Override the model passed via --model flag. Defaults to the Gemini `flash` alias. */
+    /** Explicit model override passed via --model. Omitted to preserve Gemini Auto. */
     model?: string;
     /** Approval mode for headless Gemini runs. Defaults to yolo for autonomous execution. */
     approvalMode?: "default" | "auto_edit" | "yolo" | "plan";
@@ -135,7 +135,7 @@ export declare function createClaudeCliAdapter(options?: ClaudeCliAdapterOptions
  */
 export declare function createCodexCliAdapter(options?: CodexCliAdapterOptions): MartinAdapter;
 /**
- * Spawns `gemini --model <model> --prompt "" --approval-mode <mode> --output-format json [...]`.
+ * Spawns `gemini [--model <explicit-model>] --prompt "" --approval-mode <mode> --output-format json [...]`.
  *
  * The prompt is delivered via stdin while forcing headless mode with `--prompt ""`,
  * which keeps large MartinLoop prompts off the command line on Windows.