@martinloop/mcp 0.3.5 → 0.3.7

package/dist/server-validation.d.ts

@@ -1,4 +1,4 @@
-type ToolName = "martin_run" | "martin_inspect" | "martin_status" | "martin_doctor" | "martin_plan" | "martin_preflight" | "martin_logs" | "martin_cancel" | "martin_pause" | "martin_continue" | "martin_list_runs" | "martin_triage_runs" | "martin_get_run" | "martin_get_attempt" | "martin_get_verification_results" | "martin_run_dossier" | "martin_dossier" | "martin_eval" | "martin_pr_summary" | "martin_create_pr" | "martin_review_pr";
+type ToolName = "martin_run" | "martin_inspect" | "martin_status" | "martin_doctor" | "martin_estimate" | "martin_plan" | "martin_preflight" | "martin_logs" | "martin_cancel" | "martin_pause" | "martin_continue" | "martin_list_runs" | "martin_triage_runs" | "martin_get_run" | "martin_get_attempt" | "martin_get_verification_results" | "martin_run_dossier" | "martin_dossier" | "martin_eval" | "martin_pr_summary" | "martin_create_pr" | "martin_review_pr";
 export { sanitizeToolErrorMessage } from "./tools/tool-errors.js";
 export declare function validateToolInput(name: ToolName, args: unknown): unknown;
 export declare function resolveSafeRepoRoot(repoRoot?: string, workspaceRoot?: string): string;

package/dist/server-validation.js

@@ -14,6 +14,8 @@ export function validateToolInput(name, args) {
             return validateStatusInput(args);
         case "martin_doctor":
             return validateDoctorInput(args);
+        case "martin_estimate":
+            return validateEstimateInput(args);
         case "martin_plan":
             return validatePlanInput(args);
         case "martin_preflight":
@@ -252,6 +254,16 @@ function validateDoctorInput(args) {
         ...optionalEnumAsObject(record.engine, "engine", MARTIN_ENGINE_VALUES)
     };
 }
+function validateEstimateInput(args) {
+    const record = requireObject(args);
+    assertAllowedKeys(record, ["objective", "engine", "budgetUsd", "fileScope"]);
+    return {
+        objective: requireString(record.objective, "objective"),
+        ...optionalEnumAsObject(record.engine, "engine", MARTIN_ENGINE_VALUES),
+        ...optionalPositiveNumber(record.budgetUsd, "budgetUsd"),
+        ...optionalStringArrayAsObject(record.fileScope, "fileScope")
+    };
+}
 function validatePreflightInput(args) {
     return validateRunInput(args);
 }

package/dist/server.js

@@ -721,7 +721,7 @@ export function createMartinMcpServer(serverInfo) {
         tools: [
             {
                 name: "martin_run",
-                description: "Execute a governed Martin Loop run on a coding task and return the run summary, spend, artifact rollup, and verification state. This hard-blocks until martin_doctor, martin_plan, and martin_preflight receipts exist for the same task.",
+                description: "Execute a governed Martin Loop run on a coding task and return the run summary, spend, artifact rollup, and verification state. This hard-blocks until martin_doctor, martin_estimate, martin_plan, and martin_preflight receipts exist for the same task.",
                 annotations: {
                     destructiveHint: true,
                     idempotentHint: false,
@@ -1518,7 +1518,7 @@ export function createMartinMcpServer(serverInfo) {
                     workingDirectory: output.environment.workingDirectory,
                     engine: input.engine,
                     receiptScope: output.receiptScope
-                }).catch(() => { });
+                });
                 return createToolSuccessResult(output, output.summary);
             }
             if (name === "martin_plan") {
@@ -1535,7 +1535,7 @@ export function createMartinMcpServer(serverInfo) {
                         repoRoot: output.workingDirectory,
                         runsRoot: resolveRunsRoot(process.env)
                     }
-                }).catch(() => { });
+                });
                 return createToolSuccessResult(output, `Plan ready for ${output.objective} with ${output.risk.level} risk and ${output.approvalRecommendation.replace(/_/gu, " ")} approval.`);
             }
             if (name === "martin_preflight") {
@@ -1553,7 +1553,7 @@ export function createMartinMcpServer(serverInfo) {
                         allowedPaths: output.normalized.allowedPaths,
                         deniedPaths: output.normalized.deniedPaths,
                         budget: output.normalized.budget
-                    }).catch(() => { });
+                    });
                 }
                 return createToolSuccessResult(output, output.summary);
             }
@@ -1635,11 +1635,13 @@ export function createMartinMcpServer(serverInfo) {
                 return createToolSuccessResult(output, `PR review verdict for ${output.loopId}: ${output.verdict}.`);
             }
             if (name === "martin_estimate") {
-                const input = args;
+                const input = validateToolInput("martin_estimate", args);
                 const objective = input.objective;
                 const engine = input.engine ?? "claude";
                 const budgetUsd = input.budgetUsd ?? 5;
                 const fileScope = input.fileScope ?? [];
+                const workingDirectory = resolveSafeRepoRoot();
+                const runsRoot = resolveRunsRoot(process.env);
                 const route = classifyRoute({
                     objective,
                     verificationPlan: [],
@@ -1662,9 +1664,18 @@ export function createMartinMcpServer(serverInfo) {
                     blockedSteps: route.blockedSteps,
                     compressed: route.compressed,
                     ...(route.compressionSummary ? { compressionSummary: route.compressionSummary } : {}),
-                    recommendedBudgetUsd
+                    recommendedBudgetUsd,
+                    recommendedModelTier: route.recommendedModelTier,
+                    estimatedSavingVsSonnetUsd: route.estimatedSavingVsSonnetUsd
                 };
-                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route, ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
+                await recordMcpWorkflowStep({
+                    runsRoot,
+                    step: "estimate",
+                    workingDirectory,
+                    objective,
+                    engine
+                });
+                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 createToolErrorResult(toToolFailure(new Error(`Unknown tool: ${name}`)));
         }

package/dist/tools/doctor.js

@@ -113,6 +113,12 @@ export async function martinDoctorTool(input) {
                 available: gemini.available,
                 detail: gemini.detail,
                 ...(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."
             }
         },
         ...(input.engine ? { requestedEngine: input.engine } : {}),

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

@@ -1,5 +1,5 @@
 import { type SpawnLike } from "../vendor/adapters/index.js";
-import { type RunStore } from "../vendor/core/index.js";
+import { type RunStore, type RunMartinInput, type RunMartinResult } from "../vendor/core/index.js";
 import type { LoopBudget, ReceiptScope } from "../vendor/contracts/index.js";
 import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, type MartinEngine } from "./tool-support.js";
 export interface RunLoopInput {
@@ -46,4 +46,5 @@ export interface RunLoopOutput {
 }
 export declare function __setProofModeVerifierSpawnImplForTests(spawnImpl?: SpawnLike): void;
 export declare function __setRunStoreOverrideForTests(store?: RunStore): void;
+export declare function __setRunMartinImplForTests(impl?: (input: RunMartinInput) => Promise<RunMartinResult>): void;
 export declare function runLoopTool(input: RunLoopInput): Promise<RunLoopOutput>;

package/dist/tools/run-loop.js

@@ -6,12 +6,16 @@ import { buildArtifactSummary, buildVerificationSummary, buildLoopPreview, build
 import { normalizeLoopBudget } from "./workflow-governance.js";
 let proofModeVerifierSpawnImpl;
 let runStoreOverrideForTests;
+let runMartinImpl = runMartin;
 export function __setProofModeVerifierSpawnImplForTests(spawnImpl) {
     proofModeVerifierSpawnImpl = spawnImpl;
 }
 export function __setRunStoreOverrideForTests(store) {
     runStoreOverrideForTests = store;
 }
+export function __setRunMartinImplForTests(impl) {
+    runMartinImpl = impl ?? runMartin;
+}
 export async function runLoopTool(input) {
     const workingDirectory = resolveSafeRepoRoot(input.workingDirectory);
     const engine = input.engine ?? "claude";
@@ -98,7 +102,7 @@ export async function runLoopTool(input) {
         partialBudget.maxTokens = input.maxTokens;
     }
     const budget = normalizeLoopBudget(partialBudget);
-    const result = await runMartin({
+    const result = await runMartinImpl({
         workspaceId: input.workspaceId ?? "ws_mcp",
         projectId: input.projectId ?? "proj_mcp",
         store: runStoreOverrideForTests ?? createFileRunStore({ runsRoot }),

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

@@ -1,6 +1,6 @@
 import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope } 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"];
+export declare const MARTIN_ENGINE_VALUES: readonly ["claude", "codex", "gemini", "openai"];
 export type MartinEngine = (typeof MARTIN_ENGINE_VALUES)[number];
 export interface InspectableLoopAttempt extends LoopAttemptRecord {
     attemptId?: string;

package/dist/tools/tool-support.js

@@ -3,7 +3,7 @@ import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { evaluateCostGovernor, resolveRunsRoot } from "../vendor/core/index.js";
 import { readAllLoopRecordsSafely } from "./run-store.js";
-export const MARTIN_ENGINE_VALUES = ["claude", "codex", "gemini"];
+export const MARTIN_ENGINE_VALUES = ["claude", "codex", "gemini", "openai"];
 const CLI_CACHE_TTL_MS = 60_000;
 const RUN_STORE_CACHE_TTL_MS = 5_000;
 const cliAvailabilityCache = new Map();
@@ -429,6 +429,7 @@ export function buildSuggestedResourceUris(loopId) {
         "martin://runs/triage",
         "martin://runs/latest",
         "martin://runs/latest/summary",
+        "martin://runs/latest/receipt",
         "martin://runs/latest/proof-card",
         "martin://runs/latest/budget-status",
         "martin://runs/latest/verifier-evidence",

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

@@ -0,0 +1,146 @@
+/**
+ * Real agent-CLI adapters.
+ *
+ * Exports a generic factory (`createAgentCliAdapter`) and two pre-configured
+ * factories (`createClaudeCliAdapter`, `createCodexCliAdapter`) that spawn
+ * the respective AI coding CLI as a child subprocess.
+ *
+ * Usage in CLI:
+ *   createClaudeCliAdapter({ workingDirectory: process.cwd() })
+ *   createCodexCliAdapter({ workingDirectory: process.cwd() })
+ *
+ * MCP tools and integration tests use the same factories.
+ */
+import type { MartinAdapter, MartinAdapterRequest } from "../../../core/index.js";
+import { type SpawnLike } from "./cli-bridge.js";
+/**
+ * Given a prompt string, returns the full argv array to pass to spawn().
+ * Example for Claude:  () => ["--output-format", "json", "--print"]
+ * Example for Codex:   () => ["exec", "--sandbox", "workspace-write", "-"]
+ */
+export type CliArgsBuilder = (prompt: string, request: MartinAdapterRequest) => string[];
+export type CliStdinBuilder = (prompt: string) => string | undefined;
+export interface AgentCliAdapterOptions {
+    /** The executable to spawn (e.g. "claude", "codex"). */
+    command: string;
+    /** Converts a prompt string into the argv array passed to spawn(). */
+    argsBuilder: CliArgsBuilder;
+    /** Optional stdin payload for CLIs that accept prompt input via stdin or `-`. */
+    stdinBuilder?: CliStdinBuilder;
+    /** Adapter ID suffix. Defaults to command. */
+    adapterIdSuffix?: string;
+    /** Working directory for all subprocesses. Defaults to process.cwd(). */
+    workingDirectory?: string;
+    /** Timeout for the agent subprocess in ms. Defaults to 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Timeout per verification command in ms. Defaults to 120_000 (2 min). */
+    verifyTimeoutMs?: number;
+    /** Human-readable label shown in loop records. */
+    label?: string;
+    /** Model name surfaced in adapter metadata (also used for cost estimation). */
+    model?: string;
+    /**
+     * Whether the CLI outputs JSON when --output-format json is passed.
+     * Set to false for CLIs that don't support this flag (e.g. Codex).
+     * Defaults to true for Claude.
+     */
+    supportsJsonOutput?: boolean;
+    /**
+     * Set when `argsBuilder` requests `--output-format stream-json` (newline-
+     * delimited JSON events) rather than single-blob `json`. Enables (a)
+     * incremental result parsing that scans for the final `result` event, and
+     * (b) a live cumulative-cost circuit breaker that terminates the subprocess
+     * the moment projected spend crosses the remaining per-attempt budget,
+     * rather than only learning about an overspend after the process exits.
+     */
+    streamingUsageCap?: boolean;
+    /** Test-only override for subprocess spawning. */
+    spawnImpl?: SpawnLike;
+}
+export interface ClaudeCliAdapterOptions {
+    workingDirectory?: string;
+    timeoutMs?: number;
+    verifyTimeoutMs?: number;
+    label?: string;
+    /** Override the model passed via --model flag. */
+    model?: string;
+    /** Extra args appended after core args (before prompt). */
+    extraArgs?: string[];
+    spawnImpl?: SpawnLike;
+}
+export interface CodexCliAdapterOptions {
+    /** Override the executable or absolute command path used to launch Codex. */
+    command?: string;
+    workingDirectory?: string;
+    timeoutMs?: number;
+    verifyTimeoutMs?: number;
+    label?: string;
+    /** Override the model passed via --model flag. */
+    model?: string;
+    /**
+     * Deprecated no-op retained for compatibility.
+     *
+     * Codex CLI's supported non-interactive entrypoint is `codex exec`.
+     * MartinLoop now uses explicit sandboxing instead of the legacy
+     * `--full-auto` compatibility path, which can exit before verifier execution.
+     */
+    fullAuto?: boolean;
+    /** Codex sandbox mode for model-generated commands. Defaults to workspace-write. */
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access";
+    /** Extra args appended after core args (before prompt). */
+    extraArgs?: string[];
+    spawnImpl?: SpawnLike;
+}
+export interface GeminiCliAdapterOptions {
+    workingDirectory?: string;
+    timeoutMs?: number;
+    verifyTimeoutMs?: number;
+    label?: string;
+    /** Override the model passed via --model flag. Defaults to the Gemini `flash` alias. */
+    model?: string;
+    /** Approval mode for headless Gemini runs. Defaults to yolo for autonomous execution. */
+    approvalMode?: "default" | "auto_edit" | "yolo" | "plan";
+    /** Enable Gemini sandbox mode when the host is configured for it. Disabled by default. */
+    sandbox?: boolean;
+    /** Extra args appended after core args. */
+    extraArgs?: string[];
+    spawnImpl?: SpawnLike;
+}
+export declare function createAgentCliAdapter(options: AgentCliAdapterOptions): MartinAdapter;
+/**
+ * Spawns `claude --output-format stream-json --verbose --print "<prompt>" [extraArgs]`.
+ *
+ * `stream-json` emits one JSON event per line — including per-turn usage on
+ * each `assistant` message and a final `result` event carrying the same
+ * `result`/`usage`/`total_cost_usd` fields as single-blob `json` output — so
+ * MartinLoop can both (a) recover real token usage/cost as before, and
+ * (b) watch cumulative spend live and self-terminate the subprocess the
+ * moment it crosses the remaining per-attempt budget (see
+ * `streamingUsageCap` / `createStreamingUsageInspector`), instead of only
+ * discovering an overspend after the whole process has already exited.
+ *
+ * Requires the Claude Code CLI to be installed and authenticated:
+ *   https://docs.anthropic.com/claude-code
+ */
+export declare function createClaudeCliAdapter(options?: ClaudeCliAdapterOptions): MartinAdapter;
+/**
+ * Spawns `codex exec --cd <workspace> --sandbox <mode> [--model <model>] [extraArgs] -`.
+ *
+ * The prompt is delivered via stdin so Windows shell quoting cannot truncate or
+ * reinterpret long MartinLoop prompts that contain paths, deny rules, or budget
+ * context.
+ *
+ * Requires the Codex CLI to be installed and authenticated:
+ *   npm install -g @openai/codex
+ */
+export declare function createCodexCliAdapter(options?: CodexCliAdapterOptions): MartinAdapter;
+/**
+ * Spawns `gemini --model <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.
+ *
+ * Requires the Gemini CLI to be installed and authenticated:
+ *   npm install -g @google/gemini-cli
+ */
+export declare function createGeminiCliAdapter(options?: GeminiCliAdapterOptions): MartinAdapter;