@vitest-agent/mcp 2.3.4 → 2.4.0

package/index.d.ts

@@ -520,6 +520,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
       } | undefined;
       readonly passWithNoTests?: boolean | undefined;
       readonly timeout?: number | undefined;
+      readonly projectRoot?: string | undefined;
       readonly _sessionContext?: {
         readonly chatId: string;
         readonly conversationId: string;
@@ -529,6 +530,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
     output: {
       readonly kind: "ok";
       readonly project?: string | undefined;
+      readonly projectRoot: string;
       readonly scope: {
         readonly project: string | null;
         readonly files: readonly string[];
@@ -691,6 +693,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
       readonly message: string;
     } | {
       readonly kind: "no-match";
+      readonly projectRoot: string;
       readonly filter: {
         readonly project: string | null;
         readonly files: readonly string[];
@@ -1450,7 +1453,7 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
       readonly id: number;
       readonly outcome: "abandoned" | "confirmed" | "refuted";
       readonly validatedTurnId?: number | undefined;
-      readonly validatedAt: string;
+      readonly validatedAt?: string | undefined;
     } | {
       readonly action: "list";
       readonly sessionId?: number | undefined;

package/index.js

@@ -12,7 +12,7 @@ import { parseSessionEnvExports, recoverSessionContextFromSessionEnv } from "./s
 *
 * @public
 */
-const CURRENT_MCP_VERSION = "2.3.4";
+const CURRENT_MCP_VERSION = "2.4.0";
 
 //#endregion
 export { CURRENT_MCP_VERSION, McpLive, appRouter, buildMcpServer, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, parseSessionEnvExports, recoverSessionContextFromSessionEnv, startMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "2.3.4",
+	"version": "2.4.0",
 	"private": false,
 	"description": "Model Context Protocol server for vitest-agent. Exposes 53 tools for agent access to test data, TDD lifecycle, and session management.",
 	"keywords": [
@@ -42,7 +42,7 @@
 		"@effect/sql-sqlite-node": "4.0.0-rc.109",
 		"@modelcontextprotocol/sdk": "^1.30.0",
 		"@trpc/server": "^11.18.0",
-		"@vitest-agent/sdk": "2.4.4",
+		"@vitest-agent/sdk": "2.4.5",
 		"effect": "4.0.0-rc.109",
 		"zod": "^4.4.3"
 	},

package/server.js

@@ -405,10 +405,11 @@ function buildMcpServer(ctx) {
 		};
 	});
 	server.registerTool("run_tests", {
-		description: "Use to run Vitest tests, with optional file, project, and tag filters. structuredContent carries the typed AgentReport plus per-test classifications (discriminate on `kind`: ok, timeout, error, no-match). Unknown parameters are rejected — accepted keys are files, project, tags, passWithNoTests, timeout. The legacy format=json arg is dropped — structuredContent supersedes it.",
+		description: "Use to run Vitest tests, with optional file, project, and tag filters. structuredContent carries the typed AgentReport plus per-test classifications (discriminate on `kind`: ok, timeout, error, no-match). Unknown parameters are rejected — accepted keys are files, project, tags, passWithNoTests, timeout, projectRoot. The server's Vitest root is normally frozen at boot (ctx.cwd) — projectRoot overrides it for this call, but only after validation: it must be an existing directory belonging to the same git repository as ctx.cwd (checked via `git rev-parse --git-common-dir`, which is identical across a repo and all its worktrees, including a sibling worktree checked out from the same repo). A path in a different repository, or a non-existent path, is rejected with `{ kind: \"error\" }` naming both paths — never a silent fallback to ctx.cwd. The resolved root actually used is always echoed back on success. The legacy format=json arg is dropped — structuredContent supersedes it.",
 		inputSchema: strict({
 			files: z.optional(z.array(z.string())).describe("Test file paths to run"),
 			project: z.optional(z.string()).describe("Project name to filter"),
+			projectRoot: z.optional(z.string()).describe("Explicit Vitest root to use instead of the server's boot-time ctx.cwd. Prefer an absolute path; a relative path is resolved against ctx.cwd, not the server process's cwd. Validated: must be an existing directory in the same git repository as ctx.cwd (same git-common-dir, e.g. a sibling worktree). Rejected with { kind: 'error' } naming both paths otherwise."),
 			tags: z.optional(strict({
 				all: z.optional(z.array(z.string())).describe("Require every listed tag"),
 				any: z.optional(z.array(z.string())).describe("Require at least one listed tag"),
@@ -430,6 +431,7 @@ function buildMcpServer(ctx) {
 			tags: args.tags,
 			passWithNoTests: args.passWithNoTests,
 			timeout: args.timeout,
+			...args.projectRoot !== void 0 && { projectRoot: args.projectRoot },
 			...args._sessionContext !== void 0 && { _sessionContext: args._sessionContext }
 		});
 		return structuredResult(Schema.decodeSync(RunTestsAsMarkdown)(data), data);
@@ -765,7 +767,7 @@ function buildMcpServer(ctx) {
 		return structuredResult(Schema.decodeSync(TddArtifactListAsMarkdown)(data), data);
 	});
 	server.registerTool("hypothesis", {
-		description: "Use to manage debugging hypotheses, with a CRUD action discriminator: action='record' (content, tddTaskId?, optional citation ids) writes a hypothesis — the binding session is resolved server-side from the recovered host context (active TDD subagent, else main session); pass tddTaskId (returned by tdd_task action='start') to bind deterministically to that task's session, and do not pass sessionId when recording; action='validate' (id, outcome, validatedAt) records a validation outcome; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
+		description: "Use to manage debugging hypotheses, with a CRUD action discriminator: action='record' (content, tddTaskId?, optional citation ids) writes a hypothesis — the binding session is resolved server-side from the recovered host context (active TDD subagent, else main session); pass tddTaskId (returned by tdd_task action='start') to bind deterministically to that task's session, and do not pass sessionId when recording; action='validate' (id, outcome, validatedAt?) records a validation outcome — validatedAt is optional and defaults server-side to now when omitted, or is honored verbatim when supplied; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
 		inputSchema: strict({
 			action: z.enum([
 				"record",
@@ -804,7 +806,7 @@ function buildMcpServer(ctx) {
 			action: "validate",
 			id: args.id,
 			outcome: args.outcome,
-			validatedAt: args.validatedAt,
+			...args.validatedAt !== void 0 && { validatedAt: args.validatedAt },
 			...args.validatedTurnId !== void 0 && { validatedTurnId: args.validatedTurnId }
 		}));
 		const result = await caller.hypothesis({

package/tools/help.js

@@ -97,7 +97,7 @@ const HELP_TEXT = `# vitest-agent MCP Tools
 
 \`hypothesis\` actions:
 - \`{ action: "record", sessionId, content, createdTurnId?, citedTestErrorId?, citedStackFrameId? }\`
-- \`{ action: "validate", id, outcome, validatedAt, validatedTurnId? }\`
+- \`{ action: "validate", id, outcome, validatedAt?, validatedTurnId? }\` — \`validatedAt\` defaults server-side to now when omitted; an explicit value is honored verbatim
 - \`{ action: "list", sessionId?, outcome?, limit? }\`
 
 ## TDD lifecycle

package/tools/hypothesis.js

@@ -73,7 +73,7 @@ const ValidateVariant = Schema.Struct({
 		"abandoned"
 	]),
 	validatedTurnId: Schema.optional(Schema.Number),
-	validatedAt: Schema.String
+	validatedAt: Schema.optional(Schema.String)
 });
 const ListVariant = Schema.Struct({
 	action: Schema.Literal("list"),
@@ -136,7 +136,7 @@ const hypothesis = idempotentProcedure.input(Schema.toStandardSchemaV1(Hypothesi
 			yield* (yield* DataStore).validateHypothesis({
 				id: variant.id,
 				outcome: variant.outcome,
-				validatedAt: variant.validatedAt,
+				validatedAt: variant.validatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
 				...variant.validatedTurnId !== void 0 && { validatedTurnId: variant.validatedTurnId }
 			});
 			return { action: "validate" };

package/tools/run-tests.js

@@ -2,10 +2,13 @@ import { publicProcedure } from "../context.js";
 import { AgentReport, DataReader, DataStore, buildAgentReport, buildConsoleLeaks, coerceErrorField, collectConsoleLeakEntries } from "@vitest-agent/sdk";
 import { Effect, Schema, SchemaGetter } from "effect";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { execFile } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { Writable } from "node:stream";
+import { promisify } from "node:util";
 
 //#region src/tools/run-tests.ts
 const TagFilter = Schema.Struct({
@@ -27,6 +30,7 @@ const RunTestsScope = Schema.Struct({
 const RunTestsOk = Schema.Struct({
 	kind: Schema.Literal("ok").annotate({ description: "Discriminant — `true` test run completed (with or without failures)." }),
 	project: Schema.optional(Schema.String),
+	projectRoot: Schema.String.annotate({ description: "The absolute Vitest root actually used for this run (issue #252). Echoed whether or not the caller supplied a `projectRoot` param -- when absent, this is the server's boot-time ctx.cwd; when supplied and validated, this is the resolved, validated path. Lets an agent confirm discovery resolved where it expected, or that an explicit projectRoot was actually honored." }),
 	scope: RunTestsScope,
 	report: AgentReport.annotate({ description: "Full AgentReport including pass/fail counts and per-module errors." }),
 	classifications: Schema.Record(Schema.String, Schema.String).annotate({ description: "Per-test classification labels: stable, new-failure, persistent, flaky, recovered." }),
@@ -42,6 +46,7 @@ const RunTestsError = Schema.Struct({
 }).annotate({ identifier: "RunTestsError" });
 const RunTestsNoMatch = Schema.Struct({
 	kind: Schema.Literal("no-match").annotate({ description: "Discriminant — the resolved filter set matched zero test cases. Tests did not run; this is independent of passWithNoTests policy." }),
+	projectRoot: Schema.String.annotate({ description: "The absolute Vitest root actually resolved for this call (issue #252) — echoed the same as on RunTestsOk, even though no test ran." }),
 	filter: Schema.Struct({
 		project: Schema.NullOr(Schema.String),
 		files: Schema.Array(Schema.String),
@@ -164,6 +169,73 @@ function sanitizeTestArgs(args) {
 	}
 	return result;
 }
+const execFileAsync = promisify(execFile);
+/**
+* Resolve the git common directory for `dir` (`git rev-parse
+* --git-common-dir`) — identical across a repository and every worktree
+* attached to it, which is what makes it the right "same repository"
+* comparison (a plain `--show-toplevel` differs per worktree). Returns
+* `null` when `dir` is not inside a git repository or the command fails
+* for any other reason; callers treat `null` as "cannot confirm same
+* repository", never as a silent pass.
+*
+* @internal exported for tests
+*/
+async function resolveGitCommonDir(dir) {
+	try {
+		const { stdout } = await execFileAsync("git", ["rev-parse", "--git-common-dir"], { cwd: dir });
+		const trimmed = stdout.trim();
+		if (trimmed.length === 0) return null;
+		const candidate = resolve(dir, trimmed);
+		return await realpath(candidate);
+	} catch {
+		return null;
+	}
+}
+/**
+* Validate an optional caller-supplied `projectRoot` against `ctxCwd`
+* (the MCP server's boot-time root). `undefined` always resolves to
+* `ctxCwd` unchanged (issue #252's option 1: explicit opt-in only —
+* never inferred, never defaulted to anything but the historical
+* behavior when the caller says nothing).
+*
+* A supplied `projectRoot` is VALIDATED, not trusted: it must resolve to
+* an existing directory that shares a git common directory with
+* `ctxCwd` (same repository, including across worktrees). Any failure
+* returns `{ ok: false, message }` naming both paths — never a silent
+* fallback to `ctxCwd`, never a raw throw.
+*
+* @internal exported for tests
+*/
+async function validateProjectRoot(projectRoot, ctxCwd) {
+	if (projectRoot === void 0) return {
+		ok: true,
+		root: ctxCwd
+	};
+	const resolvedRoot = resolve(ctxCwd, projectRoot);
+	let isDirectory;
+	try {
+		isDirectory = (await stat(resolvedRoot)).isDirectory();
+	} catch {
+		return {
+			ok: false,
+			message: `projectRoot "${resolvedRoot}" does not exist (ctx.cwd is "${ctxCwd}").`
+		};
+	}
+	if (!isDirectory) return {
+		ok: false,
+		message: `projectRoot "${resolvedRoot}" is not a directory (ctx.cwd is "${ctxCwd}").`
+	};
+	const [rootCommonDir, cwdCommonDir] = await Promise.all([resolveGitCommonDir(resolvedRoot), resolveGitCommonDir(ctxCwd)]);
+	if (rootCommonDir === null || cwdCommonDir === null || rootCommonDir !== cwdCommonDir) return {
+		ok: false,
+		message: `projectRoot "${resolvedRoot}" does not belong to the same git repository as ctx.cwd "${ctxCwd}".`
+	};
+	return {
+		ok: true,
+		root: resolvedRoot
+	};
+}
 let _runTestsChain = Promise.resolve();
 function serializeRunTests(fn) {
 	const next = _runTestsChain.then(fn, fn);
@@ -195,9 +267,10 @@ function coerceErrors(errors) {
 function formatRunTestsMarkdown(data) {
 	if (data.kind === "timeout") return `Test run timed out after ${data.timeoutSeconds} seconds.`;
 	if (data.kind === "error") return `Test run failed: ${data.message}`;
-	if (data.kind === "no-match") return formatNoMatchMarkdown(data.filter);
+	const rootLine = `\nProject root: \`${data.projectRoot}\``;
+	if (data.kind === "no-match") return `${formatNoMatchMarkdown(data.filter)}${rootLine}`;
 	const classMap = new Map(Object.entries(data.classifications));
-	return formatReportMarkdown(data.report, classMap);
+	return `${formatReportMarkdown(data.report, classMap)}${rootLine}`;
 }
 /**
 * Render the `no-match` filter context plus a remediation pointer aimed at
@@ -310,6 +383,7 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 	tags: Schema.optional(TagFilter),
 	passWithNoTests: Schema.optional(Schema.Boolean),
 	timeout: Schema.optional(Schema.Number),
+	projectRoot: Schema.optional(Schema.String),
 	_sessionContext: Schema.optional(Schema.Struct({
 		chatId: Schema.String,
 		conversationId: Schema.String,
@@ -326,6 +400,12 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 	}
 	const resolvedExpression = composeTagExpression(tagsInput ?? null);
 	const hasFilter = files.length > 0 || project !== void 0 || resolvedExpression !== null;
+	const projectRootValidation = await validateProjectRoot(input.projectRoot, ctx.cwd);
+	if (!projectRootValidation.ok) return {
+		kind: "error",
+		message: projectRootValidation.message
+	};
+	const resolvedRoot = projectRootValidation.root;
 	const timeoutMs = (input.timeout ?? 120) * 1e3;
 	const recovered = input._sessionContext ?? null ?? ctx.sessionContext.get();
 	if (recovered !== null) {
@@ -342,7 +422,7 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 	try {
 		covOverride = makeCoverageDirOverride();
 		vitest = await createVitest("test", {
-			root: ctx.cwd,
+			root: resolvedRoot,
 			run: true,
 			coverage: covOverride.coverage,
 			...project ? { project } : {},
@@ -363,6 +443,7 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 		const unhandledErrors = coerceErrors(result.unhandledErrors);
 		if (hasFilter && result.testModules.length === 0 && unhandledErrors.length === 0) return {
 			kind: "no-match",
+			projectRoot: resolvedRoot,
 			filter: {
 				project: project ?? null,
 				files,
@@ -400,6 +481,7 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 		return {
 			kind: "ok",
 			...project !== void 0 && { project },
+			projectRoot: resolvedRoot,
 			scope: {
 				project: project ?? null,
 				files,
@@ -440,4 +522,4 @@ const runTests = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
 }));
 
 //#endregion
-export { RunTestsAsMarkdown, RunTestsResult, coerceErrors, composeTagExpression, formatNoMatchMarkdown, formatReportMarkdown, formatRunTestsMarkdown, makeCoverageDirOverride, readDiscoveryLastScannedAt, runTests, sanitizeTestArgs, withStdioCaptured };
+export { RunTestsAsMarkdown, RunTestsResult, coerceErrors, composeTagExpression, formatNoMatchMarkdown, formatReportMarkdown, formatRunTestsMarkdown, makeCoverageDirOverride, readDiscoveryLastScannedAt, resolveGitCommonDir, runTests, sanitizeTestArgs, validateProjectRoot, withStdioCaptured };