@vitest-agent/mcp 1.0.0

package/tools/tdd-task.js

@@ -0,0 +1,278 @@
+import { idempotentProcedure } from "../middleware/idempotency.js";
+import { DataReader, DataStore, GoalDetail } from "@vitest-agent/sdk";
+import { Effect, Match, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/tdd-task.ts
+/**
+* Consolidated `tdd_task` MCP tool — Schema-driven implementation.
+*
+* `start` and `end` mutate; `get` and `resume` read. Every action
+* now returns a structured payload — `get` carries the full nested
+* `TddTaskDetail` tree plus the `currentPhase` lookup, and `resume`
+* carries a compact summary discriminated by `phaseAvailable`. The
+* boundary in server.ts uses `formatTddTaskMarkdown` to render
+* `get` / `resume` text.
+*
+* @packageDocumentation
+*/
+const TddPhaseRow = Schema.Struct({
+	id: Schema.Number,
+	behaviorId: Schema.NullOr(Schema.Number),
+	phase: Schema.String,
+	startedAt: Schema.String,
+	endedAt: Schema.NullOr(Schema.String),
+	transitionReason: Schema.NullOr(Schema.String)
+}).annotations({ identifier: "TddTaskPhaseRow" });
+const TddArtifactDetailRow = Schema.Struct({
+	id: Schema.Number,
+	phaseId: Schema.Number,
+	artifactKind: Schema.String,
+	testCaseId: Schema.NullOr(Schema.Number),
+	testRunId: Schema.NullOr(Schema.Number),
+	recordedAt: Schema.String
+}).annotations({ identifier: "TddTaskArtifactRow" });
+const TddTaskDetailSchema = Schema.Struct({
+	tddTaskId: Schema.Number,
+	sessionId: Schema.Number,
+	goal: Schema.String,
+	startedAt: Schema.String,
+	endedAt: Schema.NullOr(Schema.String),
+	outcome: Schema.NullOr(Schema.String),
+	runId: Schema.NullOr(Schema.String),
+	goals: Schema.Array(GoalDetail),
+	phases: Schema.Array(TddPhaseRow),
+	artifacts: Schema.Array(TddArtifactDetailRow)
+}).annotations({ identifier: "TddTaskDetailSchema" });
+const CurrentPhaseLookup = Schema.Struct({
+	id: Schema.Number,
+	phase: Schema.String,
+	startedAt: Schema.String,
+	behaviorId: Schema.NullOr(Schema.Number)
+}).annotations({ identifier: "TddTaskCurrentPhaseLookup" });
+const TddTaskStartOk = Schema.Struct({
+	action: Schema.Literal("start"),
+	tddTaskId: Schema.Number,
+	goal: Schema.String,
+	runId: Schema.optional(Schema.String)
+}).annotations({ identifier: "TddTaskStartOk" });
+const TddTaskEndOk = Schema.Struct({
+	action: Schema.Literal("end"),
+	tddTaskId: Schema.Number,
+	outcome: Schema.Literal("succeeded", "blocked", "abandoned")
+}).annotations({ identifier: "TddTaskEndOk" });
+const TddTaskGetFound = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(true),
+	task: TddTaskDetailSchema,
+	currentPhase: Schema.NullOr(CurrentPhaseLookup)
+}).annotations({ identifier: "TddTaskGetFound" });
+const TddTaskGetMissing = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(false),
+	tddTaskId: Schema.Number
+}).annotations({ identifier: "TddTaskGetMissing" });
+const TddTaskResumeFound = Schema.Struct({
+	action: Schema.Literal("resume"),
+	found: Schema.Literal(true),
+	tddTaskId: Schema.Number,
+	goal: Schema.String,
+	status: Schema.String,
+	currentPhase: Schema.NullOr(CurrentPhaseLookup),
+	phasesRecorded: Schema.Number,
+	artifactsRecorded: Schema.Number
+}).annotations({ identifier: "TddTaskResumeFound" });
+const TddTaskResumeMissing = Schema.Struct({
+	action: Schema.Literal("resume"),
+	found: Schema.Literal(false),
+	tddTaskId: Schema.Number
+}).annotations({ identifier: "TddTaskResumeMissing" });
+const TddTaskResult = Schema.Union(TddTaskStartOk, TddTaskEndOk, TddTaskGetFound, TddTaskGetMissing, TddTaskResumeFound, TddTaskResumeMissing).annotations({
+	identifier: "TddTaskResult",
+	title: "tdd_task result",
+	description: "Discriminate on `action`. `get` and `resume` further discriminate on `found`. `get` carries the full nested task tree."
+});
+const formatTddTaskMarkdown = (data) => {
+	if (data.action === "start" || data.action === "end") return JSON.stringify(data, null, 2);
+	if (data.action === "get") {
+		if (!data.found) return `No TDD task with tddTaskId=${data.tddTaskId}.`;
+		const s = data.task;
+		const currentPhaseLine = data.currentPhase === null ? "- current phase: (none — no open phase)" : `- current phase: ${data.currentPhase.phase} [phaseId=${data.currentPhase.id}]${data.currentPhase.behaviorId !== null ? ` behaviorId=${data.currentPhase.behaviorId}` : ""}`;
+		const lines = [
+			`# TDD Task ${s.tddTaskId}`,
+			"",
+			`- goal: ${s.goal}`,
+			`- run_id: ${s.runId ?? "(none — run_id not recorded)"}`,
+			`- sessionId: ${s.sessionId}`,
+			`- started: ${s.startedAt}`,
+			`- ended: ${s.endedAt ?? "still open"}`,
+			`- outcome: ${s.outcome ?? "pending"}`,
+			currentPhaseLine
+		];
+		if (s.phases.length > 0) {
+			lines.push("", "## Phases", "");
+			for (const p of s.phases) {
+				const duration = p.endedAt ? ` -> ${p.endedAt}` : " (current)";
+				lines.push(`- **${p.phase}** [id=${p.id}] ${p.startedAt}${duration}`);
+				if (p.transitionReason !== null) lines.push(`  - reason: ${p.transitionReason}`);
+			}
+		}
+		if (s.artifacts.length > 0) {
+			lines.push("", "## Artifacts", "");
+			for (const a of s.artifacts) lines.push(`- **${a.artifactKind}** [id=${a.id}, phase=${a.phaseId}] at=${a.recordedAt}${a.testRunId !== null ? ` run=${a.testRunId}` : ""}`);
+		}
+		if (s.goals.length > 0) {
+			lines.push("", "## Goals and Behaviors", "");
+			for (const g of s.goals) {
+				lines.push(`### Goal ${g.ordinal + 1}: ${g.goal} [${g.status}]`);
+				if (g.behaviors.length > 0) {
+					lines.push("");
+					for (const b of g.behaviors) lines.push(`- **${b.behavior}** [${b.status}]`);
+				}
+				lines.push("");
+			}
+		}
+		return lines.join("\n");
+	}
+	if (!data.found) return `No TDD task with tddTaskId=${data.tddTaskId}.`;
+	const lines = [
+		`# TDD task #${data.tddTaskId}: ${data.goal}`,
+		"",
+		`**Status:** ${data.status}`
+	];
+	if (data.currentPhase !== null) lines.push(`**Current phase:** ${data.currentPhase.phase} (started ${data.currentPhase.startedAt})`);
+	else lines.push("**Current phase:** none (TDD cycle not yet entered)");
+	lines.push("", `**Phases recorded:** ${data.phasesRecorded}`);
+	if (data.artifactsRecorded > 0) lines.push(`**Artifacts:** ${data.artifactsRecorded}`);
+	lines.push("", `Use \`tdd_task({ action: "get", tddTaskId: ${data.tddTaskId} })\` for the full detail tree, or call \`tdd_phase_transition_request\` to advance.`);
+	return lines.join("\n");
+};
+const TddTaskAsMarkdown = Schema.transformOrFail(TddTaskResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTddTaskMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TddTaskAsMarkdown is one-way."))
+});
+const StartVariant = Schema.Struct({
+	action: Schema.Literal("start"),
+	goal: Schema.String,
+	sessionId: Schema.optional(Schema.Number),
+	chatId: Schema.optional(Schema.String),
+	parentTddTaskId: Schema.optional(Schema.Number),
+	startedAt: Schema.optional(Schema.String),
+	runId: Schema.optional(Schema.String)
+});
+const EndVariant = Schema.Struct({
+	action: Schema.Literal("end"),
+	tddTaskId: Schema.Number,
+	outcome: Schema.Literal("succeeded", "blocked", "abandoned"),
+	summaryNoteId: Schema.optional(Schema.Number)
+});
+const GetVariant = Schema.Struct({
+	action: Schema.Literal("get"),
+	tddTaskId: Schema.Number
+});
+const ResumeVariant = Schema.Struct({
+	action: Schema.Literal("resume"),
+	tddTaskId: Schema.Number
+});
+const TddTaskInput = Schema.Union(StartVariant, EndVariant, GetVariant, ResumeVariant);
+const tddTask = idempotentProcedure.input(Schema.standardSchemaV1(TddTaskInput)).mutation(async ({ ctx, input }) => {
+	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+		start: (variant) => Effect.gen(function* () {
+			const reader = yield* DataReader;
+			const store = yield* DataStore;
+			let sessionId;
+			if (variant.sessionId !== void 0) sessionId = variant.sessionId;
+			else if (variant.chatId !== void 0) {
+				const opt = yield* reader.getSessionByChatId(variant.chatId);
+				if (Option.isNone(opt)) return yield* Effect.fail(/* @__PURE__ */ new Error(`Unknown chatId: ${variant.chatId}. Run record session-start first.`));
+				sessionId = opt.value.id;
+			} else return yield* Effect.fail(/* @__PURE__ */ new Error("tdd_task action=start: provide sessionId or chatId"));
+			if (variant.runId !== void 0 && variant.runId.trim().length === 0) return yield* Effect.fail(/* @__PURE__ */ new Error("tdd_task action=start: runId must not be blank"));
+			return {
+				action: "start",
+				tddTaskId: yield* store.writeTddTask({
+					sessionId,
+					goal: variant.goal,
+					startedAt: variant.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+					...variant.runId !== void 0 && { runId: variant.runId },
+					...variant.parentTddTaskId !== void 0 && { parentTddTaskId: variant.parentTddTaskId }
+				}),
+				goal: variant.goal,
+				...variant.runId !== void 0 && { runId: variant.runId }
+			};
+		}),
+		end: (variant) => Effect.gen(function* () {
+			yield* (yield* DataStore).endTddTask({
+				id: variant.tddTaskId,
+				outcome: variant.outcome,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				...variant.summaryNoteId !== void 0 && { summaryNoteId: variant.summaryNoteId }
+			});
+			return {
+				action: "end",
+				tddTaskId: variant.tddTaskId,
+				outcome: variant.outcome
+			};
+		}),
+		get: (variant) => Effect.gen(function* () {
+			const reader = yield* DataReader;
+			const opt = yield* reader.getTddTaskById(variant.tddTaskId);
+			if (Option.isNone(opt)) return {
+				action: "get",
+				found: false,
+				tddTaskId: variant.tddTaskId
+			};
+			const currentOpt = yield* reader.getCurrentTddPhase(variant.tddTaskId);
+			const { id, ...rest } = opt.value;
+			return {
+				action: "get",
+				found: true,
+				task: {
+					tddTaskId: id,
+					...rest
+				},
+				currentPhase: Option.match(currentOpt, {
+					onNone: () => null,
+					onSome: (p) => ({
+						id: p.id,
+						phase: p.phase,
+						startedAt: p.startedAt,
+						behaviorId: p.behaviorId
+					})
+				})
+			};
+		}),
+		resume: (variant) => Effect.gen(function* () {
+			const reader = yield* DataReader;
+			const tddOpt = yield* reader.getTddTaskById(variant.tddTaskId);
+			if (Option.isNone(tddOpt)) return {
+				action: "resume",
+				found: false,
+				tddTaskId: variant.tddTaskId
+			};
+			const tdd = tddOpt.value;
+			const currentOpt = yield* reader.getCurrentTddPhase(variant.tddTaskId);
+			return {
+				action: "resume",
+				found: true,
+				tddTaskId: tdd.id,
+				goal: tdd.goal,
+				status: tdd.outcome ?? "in progress",
+				currentPhase: Option.match(currentOpt, {
+					onNone: () => null,
+					onSome: (p) => ({
+						id: p.id,
+						phase: p.phase,
+						startedAt: p.startedAt,
+						behaviorId: p.behaviorId
+					})
+				}),
+				phasesRecorded: tdd.phases.length,
+				artifactsRecorded: tdd.artifacts.length
+			};
+		})
+	})));
+});
+
+//#endregion
+export { TddTaskAsMarkdown, TddTaskResult, tddTask };

package/tools/test.js

@@ -0,0 +1,281 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, Match, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/test.ts
+/**
+* Consolidated `test` MCP tool — Schema-driven implementation.
+*
+* Replaces `test_list`, `test_get`, and `test_for_file` with one
+* tool keyed on `action`. Result variants discriminate on
+* `inventoryKind` so a single Effect Schema describes every shape
+* the tool can emit.
+*
+* @packageDocumentation
+*/
+const TestRowSchema = Schema.Struct({
+	id: Schema.Number,
+	fullName: Schema.String,
+	state: Schema.String,
+	duration: Schema.NullOr(Schema.Number),
+	module: Schema.String,
+	classification: Schema.NullOr(Schema.String)
+}).annotations({ identifier: "TestListRow" });
+const TestErrorRowMini = Schema.Struct({
+	name: Schema.NullOr(Schema.String),
+	message: Schema.String,
+	diff: Schema.NullOr(Schema.String),
+	stack: Schema.NullOr(Schema.String)
+}).annotations({ identifier: "TestGetErrorRow" });
+const TestRunRow = Schema.Struct({
+	state: Schema.Literal("passed", "failed"),
+	timestamp: Schema.String
+}).annotations({ identifier: "TestGetRunRow" });
+const TestListGroup = Schema.Struct({
+	project: Schema.String,
+	tests: Schema.Array(TestRowSchema)
+});
+const TestListResult = Schema.Struct({
+	action: Schema.Literal("list"),
+	count: Schema.Number,
+	groups: Schema.Array(TestListGroup)
+}).annotations({ identifier: "TestList" });
+const TestGetFound = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(true),
+	project: Schema.String,
+	test: TestRowSchema,
+	errors: Schema.Array(TestErrorRowMini),
+	runs: Schema.Array(TestRunRow)
+}).annotations({ identifier: "TestGetFound" });
+const TestGetMissing = Schema.Struct({
+	action: Schema.Literal("get"),
+	found: Schema.Literal(false),
+	project: Schema.String,
+	fullName: Schema.String
+}).annotations({ identifier: "TestGetMissing" });
+const TestForFileResult = Schema.Struct({
+	action: Schema.Literal("for_file"),
+	filePath: Schema.String,
+	count: Schema.Number,
+	testFiles: Schema.Array(Schema.String)
+}).annotations({ identifier: "TestForFile" });
+const TestForTagResult = Schema.Struct({
+	action: Schema.Literal("for_tag"),
+	tag: Schema.String,
+	count: Schema.Number,
+	groups: Schema.Array(TestListGroup)
+}).annotations({ identifier: "TestForTag" });
+const TestResult = Schema.Union(TestListResult, TestGetFound, TestGetMissing, TestForFileResult, TestForTagResult).annotations({
+	identifier: "TestResult",
+	title: "test result",
+	description: "Discriminate on `action`. `get` further discriminates on `found`. `list`, `for_file`, and `for_tag` all carry counted arrays — `list` and `for_tag` group by project."
+});
+const formatTestMarkdown = (data) => {
+	if (data.action === "list") {
+		if (data.count === 0) return "No tests found. Run run_tests({}) to execute tests and populate the database.";
+		const lines = ["## Tests", ""];
+		for (const g of data.groups) {
+			lines.push(`### ${g.project}`, "", "| ID | Full Name | State | Duration | Module | Classification |", "| --- | --- | --- | --- | --- | --- |");
+			for (const t of g.tests) {
+				const duration = t.duration !== null ? `${t.duration}ms` : "—";
+				const classification = t.classification ?? "—";
+				lines.push(`| ${t.id} | ${t.fullName} | ${t.state} | ${duration} | ${t.module} | ${classification} |`);
+			}
+			lines.push("");
+		}
+		return lines.join("\n").trimEnd();
+	}
+	if (data.action === "get") {
+		if (!data.found) return `Test not found: \`${data.fullName}\`\n\nUse test({ action: "list" }) to discover available tests (format: "Suite > test name").`;
+		const t = data.test;
+		const lines = [
+			`# Test: ${t.fullName}`,
+			"",
+			"## Details",
+			"",
+			"| Field | Value |",
+			"| --- | --- |",
+			`| State | ${t.state} |`,
+			`| Duration | ${t.duration !== null ? `${t.duration}ms` : "—"} |`,
+			`| Module | \`${t.module}\` |`,
+			`| Classification | ${t.classification ?? "—"} |`,
+			""
+		];
+		if (data.errors.length > 0) {
+			lines.push("## Errors", "");
+			for (const err of data.errors) {
+				lines.push(`**${err.name ?? "(unnamed)"}**`);
+				lines.push(`> ${err.message.split("\n").join("\n> ")}`);
+				if (err.diff !== null) {
+					lines.push("", "```diff", err.diff.slice(0, 1e3));
+					if (err.diff.length > 1e3) lines.push(`... (truncated, ${err.diff.length} chars total)`);
+					lines.push("```");
+				}
+				if (err.stack !== null && err.diff === null) {
+					lines.push("", "```", err.stack.slice(0, 1e3));
+					if (err.stack.length > 1e3) lines.push(`... (truncated, ${err.stack.length} chars total)`);
+					lines.push("```");
+				}
+				lines.push("");
+			}
+		}
+		if (data.runs.length > 0) {
+			const viz = data.runs.map((r) => r.state === "passed" ? "P" : "F").join("");
+			const passCount = data.runs.filter((r) => r.state === "passed").length;
+			const failCount = data.runs.filter((r) => r.state === "failed").length;
+			lines.push("## Run History", "", `Pass rate: ${passCount}/${data.runs.length} (${Math.round(passCount / data.runs.length * 100)}%)`, `Recent runs: \`${viz}\` (P=passed F=failed S=skipped, newest last)`);
+			if (failCount > 0 && passCount > 0) lines.push("Pattern: **flaky** (mixed pass/fail)");
+			else if (failCount > 0) lines.push(`Pattern: **persistent failure** (${failCount} consecutive)`);
+			lines.push("");
+		}
+		if (t.state === "failed") lines.push("## Next steps", "", `- Re-run: run_tests({ files: ["${t.module}"] })`, `- Use test({ action: "for_file", filePath: "${t.module}" }) to find related tests`, "- Use note({ action: \"create\", ... }) to record debugging findings");
+		return lines.join("\n");
+	}
+	if (data.action === "for_tag") {
+		if (data.count === 0) return `No tests found tagged \`${data.tag}\`. Use \`inventory({ kind: "tag" })\` to discover available tags.`;
+		const lines = [
+			`# Tests tagged \`${data.tag}\``,
+			"",
+			`Found ${data.count} test${data.count === 1 ? "" : "s"} across ${data.groups.length} project${data.groups.length === 1 ? "" : "s"}:`,
+			""
+		];
+		for (const g of data.groups) {
+			lines.push(`### ${g.project}`, "", "| ID | Full Name | State | Duration | Module |", "| --- | --- | --- | --- | --- |");
+			for (const t of g.tests) {
+				const duration = t.duration !== null ? `${t.duration}ms` : "—";
+				lines.push(`| ${t.id} | ${t.fullName} | ${t.state} | ${duration} | ${t.module} |`);
+			}
+			lines.push("");
+		}
+		return lines.join("\n").trimEnd();
+	}
+	if (data.count === 0) return `No test modules found covering \`${data.filePath}\`. Run run_tests({}) to populate the database, or check the file path.`;
+	const lines = [
+		`# Tests for \`${data.filePath}\``,
+		"",
+		`Found ${data.count} test module${data.count === 1 ? "" : "s"}:`,
+		""
+	];
+	for (const f of data.testFiles) lines.push(`- \`${f}\``);
+	return lines.join("\n");
+};
+const TestAsMarkdown = Schema.transformOrFail(TestResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTestMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TestAsMarkdown is one-way."))
+});
+const ListVariant = Schema.Struct({
+	action: Schema.Literal("list"),
+	project: Schema.optional(Schema.String),
+	state: Schema.optional(Schema.String),
+	module: Schema.optional(Schema.String),
+	limit: Schema.optional(Schema.Number)
+});
+const GetVariant = Schema.Struct({
+	action: Schema.Literal("get"),
+	fullName: Schema.String,
+	project: Schema.optional(Schema.String)
+});
+const ForFileVariant = Schema.Struct({
+	action: Schema.Literal("for_file"),
+	filePath: Schema.String
+});
+const ForTagVariant = Schema.Struct({
+	action: Schema.Literal("for_tag"),
+	tag: Schema.String,
+	project: Schema.optional(Schema.String)
+});
+const TestInput = Schema.Union(ListVariant, GetVariant, ForFileVariant, ForTagVariant);
+const test = publicProcedure.input(Schema.standardSchemaV1(TestInput)).query(async ({ ctx, input }) => {
+	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+		list: (variant) => Effect.gen(function* () {
+			const reader = yield* DataReader;
+			const opts = {};
+			if (variant.state !== void 0) opts.state = variant.state;
+			if (variant.module !== void 0) opts.module = variant.module;
+			if (variant.limit !== void 0) opts.limit = variant.limit;
+			const targets = variant.project ? [{ project: variant.project }] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => ({ project: r.project }))));
+			const groups = [];
+			let total = 0;
+			for (const t of targets) {
+				const tests = yield* reader.listTests(t.project, opts);
+				if (tests.length > 0) {
+					groups.push({
+						project: t.project,
+						tests
+					});
+					total += tests.length;
+				}
+			}
+			return {
+				action: "list",
+				count: total,
+				groups
+			};
+		}),
+		get: (variant) => Effect.gen(function* () {
+			const reader = yield* DataReader;
+			const candidates = variant.project ? [variant.project] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => r.project)));
+			for (const project of candidates) {
+				const testOpt = yield* reader.getTestByFullName(project, variant.fullName);
+				if (Option.isNone(testOpt)) continue;
+				const matchingErrors = (yield* reader.getErrors(project)).filter((e) => e.testFullName === variant.fullName).map((e) => ({
+					name: e.name,
+					message: e.message,
+					diff: e.diff,
+					stack: e.stack
+				}));
+				const testHistory = (yield* reader.getHistory(project)).tests.find((entry) => entry.fullName === variant.fullName);
+				return {
+					action: "get",
+					found: true,
+					project,
+					test: testOpt.value,
+					errors: matchingErrors,
+					runs: testHistory ? testHistory.runs : []
+				};
+			}
+			return {
+				action: "get",
+				found: false,
+				project: variant.project ?? candidates[0] ?? "",
+				fullName: variant.fullName
+			};
+		}),
+		for_file: (variant) => Effect.gen(function* () {
+			const testFiles = yield* (yield* DataReader).getTestsForFile(variant.filePath);
+			return {
+				action: "for_file",
+				filePath: variant.filePath,
+				count: testFiles.length,
+				testFiles
+			};
+		}),
+		for_tag: (variant) => Effect.gen(function* () {
+			const reader = yield* DataReader;
+			const targets = variant.project ? [{ project: variant.project }] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => ({ project: r.project }))));
+			const groups = [];
+			let total = 0;
+			for (const t of targets) {
+				const tests = yield* reader.listTestsForTag(variant.tag, { project: t.project });
+				if (tests.length > 0) {
+					groups.push({
+						project: t.project,
+						tests
+					});
+					total += tests.length;
+				}
+			}
+			return {
+				action: "for_tag",
+				tag: variant.tag,
+				count: total,
+				groups
+			};
+		})
+	})));
+});
+
+//#endregion
+export { TestAsMarkdown, TestResult, test };

package/tools/trends.js

@@ -0,0 +1,112 @@
+import { publicProcedure } from "../context.js";
+import { DataReader, TrendRecord } from "@vitest-agent/sdk";
+import { Effect, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/trends.ts
+/**
+* `test_trends` MCP tool — Schema-driven implementation.
+*
+* Wraps the existing `TrendRecord` Schema in a result envelope that
+* carries the project name and a `dataAvailable` flag, so callers
+* can distinguish "no trend data yet" from "data plus rendering"
+* without parsing prose.
+*
+* @packageDocumentation
+*/
+const TrendsAvailable = Schema.Struct({
+	dataAvailable: Schema.Literal(true).annotations({ description: "Discriminant — `true` when at least one trend entry exists for the project." }),
+	project: Schema.String,
+	trends: TrendRecord.annotations({ description: "Trend entries oldest-first; the latest entry drives `direction` and the headline metrics." })
+}).annotations({ identifier: "TestTrendsAvailable" });
+const TrendsAbsent = Schema.Struct({
+	dataAvailable: Schema.Literal(false).annotations({ description: "Discriminant — `false` when fewer than two runs have been recorded for the project." }),
+	project: Schema.String
+}).annotations({ identifier: "TestTrendsAbsent" });
+const TestTrendsResult = Schema.Union(TrendsAvailable, TrendsAbsent).annotations({
+	identifier: "TestTrendsResult",
+	title: "test_trends result",
+	description: "Coverage trend record per project. Discriminate on `dataAvailable` to handle the cold-start case."
+});
+const SPARKLINE_CHARS = [
+	"▁",
+	"▂",
+	"▃",
+	"▄",
+	"▅",
+	"▆",
+	"▇",
+	"█"
+];
+function toSparkline(values) {
+	if (values.length === 0) return "";
+	const min = Math.min(...values);
+	const range = Math.max(...values) - min;
+	return values.map((v) => {
+		return SPARKLINE_CHARS[range === 0 ? 4 : Math.round((v - min) / range * (SPARKLINE_CHARS.length - 1))] ?? "▄";
+	}).join("");
+}
+const directionIcon = (d) => d === "improving" ? "📈" : d === "regressing" ? "📉" : "➡️";
+const formatTestTrendsMarkdown = (data) => {
+	if (data.dataAvailable === false) return `No trend data available for project \`${data.project}\`. Run tests multiple times to build trend history.`;
+	const entries = data.trends.entries;
+	const latest = entries[entries.length - 1];
+	if (latest === void 0) return `No trend data available for project \`${data.project}\`.`;
+	const lines = [`# Coverage Trends: ${data.project}`, ""];
+	lines.push(`${directionIcon(latest.direction)} **Overall direction:** ${latest.direction} over ${entries.length} run${entries.length === 1 ? "" : "s"}`);
+	lines.push("", "## Latest Coverage", "", "| Metric | Value | Δ |", "| --- | --- | --- |");
+	const metrics = [
+		"statements",
+		"branches",
+		"functions",
+		"lines"
+	];
+	for (const metric of metrics) {
+		const value = latest.coverage[metric];
+		const delta = latest.delta[metric];
+		const deltaStr = delta > 0 ? `+${delta.toFixed(2)}%` : delta < 0 ? `${delta.toFixed(2)}%` : "—";
+		const deltaIcon = delta > .1 ? "↑" : delta < -.1 ? "↓" : "";
+		lines.push(`| ${metric} | ${value.toFixed(2)}% | ${deltaIcon} ${deltaStr} |`);
+	}
+	lines.push("");
+	if (entries.length >= 2) {
+		lines.push("## Trajectory", "");
+		for (const metric of metrics) {
+			const values = entries.map((e) => e.coverage[metric]);
+			lines.push(`- **${metric}**: \`${toSparkline(values)}\``);
+		}
+		lines.push("");
+	}
+	const recentEntries = entries.slice(-10);
+	if (recentEntries.length > 0) {
+		lines.push("## Recent Runs", "", "| Date | Lines | Branches | Functions | Statements | Direction |", "| --- | --- | --- | --- | --- | --- |");
+		for (const entry of recentEntries) {
+			const date = new Date(entry.timestamp).toLocaleDateString();
+			lines.push(`| ${date} | ${entry.coverage.lines.toFixed(1)}% | ${entry.coverage.branches.toFixed(1)}% | ${entry.coverage.functions.toFixed(1)}% | ${entry.coverage.statements.toFixed(1)}% | ${directionIcon(entry.direction)} |`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n");
+};
+const TestTrendsAsMarkdown = Schema.transformOrFail(TestTrendsResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTestTrendsMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TestTrendsAsMarkdown is one-way: markdown cannot be parsed back to TestTrendsResult."))
+});
+const testTrends = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	project: Schema.String,
+	limit: Schema.optional(Schema.Number)
+}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const trendsOpt = yield* (yield* DataReader).getTrends(input.project, input.limit);
+	if (Option.isNone(trendsOpt) || trendsOpt.value.entries.length === 0) return {
+		dataAvailable: false,
+		project: input.project
+	};
+	return {
+		dataAvailable: true,
+		project: input.project,
+		trends: trendsOpt.value
+	};
+})));
+
+//#endregion
+export { TestTrendsAsMarkdown, TestTrendsResult, testTrends };