@vitest-agent/mcp 1.0.0

package/tools/_tdd-error-envelope.js

@@ -0,0 +1,98 @@
+import { BehaviorNotFoundError, GoalNotFoundError, IllegalStatusTransitionError, TddTaskAlreadyEndedError, TddTaskNotFoundError } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+
+//#region src/tools/_tdd-error-envelope.ts
+/**
+* Shared error-to-success-shape envelope conversion for goal / behavior CRUD
+* tools. Maps each tagged TDD error to an ok:false response matching the
+* tdd_phase_transition_request accept/deny envelope shape, so the agent
+* sees a normal tool response instead of a transport error.
+*
+* `Effect.catchTags` returns `Effect.succeed(envelope)` so the success
+* channel carries the union `Success | ErrorEnvelope`.
+*/
+const goalNotFound = (e) => ({
+	ok: false,
+	error: {
+		_tag: e._tag,
+		id: e.id,
+		reason: e.reason,
+		remediation: {
+			suggestedTool: "tdd_goal",
+			suggestedArgs: { action: "list" },
+			humanHint: `No tdd_session_goals row with id=${e.id}. Call tdd_goal({ action: "list", tddTaskId }) to find the correct goal id.`
+		}
+	}
+});
+const behaviorNotFound = (e) => ({
+	ok: false,
+	error: {
+		_tag: e._tag,
+		id: e.id,
+		reason: e.reason,
+		remediation: {
+			suggestedTool: "tdd_behavior",
+			suggestedArgs: { action: "list_by_goal" },
+			humanHint: `No tdd_session_behaviors row with id=${e.id}. Call tdd_behavior({ action: "list_by_goal", goalId }) or tdd_behavior({ action: "list_by_tdd_task", tddTaskId }) to find the correct behavior id.`
+		}
+	}
+});
+const tddTaskNotFound = (e) => ({
+	ok: false,
+	error: {
+		_tag: e._tag,
+		id: e.id,
+		reason: e.reason,
+		remediation: {
+			suggestedTool: "tdd_task",
+			suggestedArgs: { action: "start" },
+			humanHint: `No tdd_tasks row with id=${e.id}. Call tdd_task({ action: "start" }) to open a TDD task before creating goals or behaviors.`
+		}
+	}
+});
+const tddTaskAlreadyEnded = (e) => ({
+	ok: false,
+	error: {
+		_tag: e._tag,
+		id: e.id,
+		endedAt: e.endedAt,
+		outcome: e.outcome,
+		remediation: {
+			suggestedTool: "tdd_task",
+			suggestedArgs: { action: "start" },
+			humanHint: `tdd_tasks row id=${e.id} is already ended (outcome=${e.outcome}). Open a new TDD task if you need to add more goals or behaviors.`
+		}
+	}
+});
+const illegalStatusTransition = (e) => ({
+	ok: false,
+	error: {
+		_tag: e._tag,
+		entity: e.entity,
+		id: e.id,
+		from: e.from,
+		to: e.to,
+		reason: e.reason,
+		remediation: {
+			suggestedTool: e.entity === "goal" ? "tdd_goal" : "tdd_behavior",
+			suggestedArgs: {
+				action: "update",
+				id: e.id,
+				status: "abandoned"
+			},
+			humanHint: `Cannot transition ${e.entity} id=${e.id} from ${e.from} to ${e.to}. Use status:'abandoned' to drop work; do not delete unless the entity was created by mistake.`
+		}
+	}
+});
+const isKnownTddError = (e) => e instanceof GoalNotFoundError || e instanceof BehaviorNotFoundError || e instanceof TddTaskNotFoundError || e instanceof TddTaskAlreadyEndedError || e instanceof IllegalStatusTransitionError;
+const tddErrorToEnvelope = (e) => {
+	if (e instanceof GoalNotFoundError) return goalNotFound(e);
+	if (e instanceof BehaviorNotFoundError) return behaviorNotFound(e);
+	if (e instanceof TddTaskNotFoundError) return tddTaskNotFound(e);
+	if (e instanceof TddTaskAlreadyEndedError) return tddTaskAlreadyEnded(e);
+	return illegalStatusTransition(e);
+};
+const catchTddErrorsAsEnvelope = (effect) => effect.pipe(Effect.catchAll((e) => isKnownTddError(e) ? Effect.succeed(tddErrorToEnvelope(e)) : Effect.fail(e)));
+
+//#endregion
+export { catchTddErrorsAsEnvelope };

package/tools/acceptance-metrics.js

@@ -0,0 +1,75 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/tools/acceptance-metrics.ts
+/**
+* `acceptance_metrics` MCP tool — Schema-driven implementation.
+*
+* Mirrors `DataReader.AcceptanceMetrics` as an Effect Schema so the
+* structured payload the agent receives, the markdown rendering on
+* the text channel, and the SDK-side `outputSchema` all derive from
+* one canonical contract.
+*
+* @packageDocumentation
+*/
+const totalAnnotation = { description: "Sample size — number of observations the metric ratio is computed over." };
+const ratioAnnotation = { description: "Compliance ratio in [0, 1]. Multiply by 100 for the percentage form rendered in the markdown view." };
+const AcceptanceMetricsResult = Schema.Struct({
+	phaseEvidenceIntegrity: Schema.Struct({
+		total: Schema.Number.annotations(totalAnnotation),
+		compliant: Schema.Number.annotations({ description: "Phase transitions that cited a valid artifact and passed binding-rule validation." }),
+		ratio: Schema.Number.annotations(ratioAnnotation)
+	}).annotations({
+		title: "Phase-evidence integrity",
+		description: "Fraction of accepted TDD phase transitions whose cited artifact satisfied the D2 binding rules. Spec target ≥80%."
+	}),
+	complianceHookResponsiveness: Schema.Struct({
+		total: Schema.Number.annotations(totalAnnotation),
+		withFollowup: Schema.Number.annotations({ description: "PreToolUse denials / `additionalContext` reminders the orchestrator acknowledged in the next turn." }),
+		ratio: Schema.Number.annotations(ratioAnnotation)
+	}).annotations({
+		title: "Compliance-hook responsiveness",
+		description: "Fraction of compliance signals from PreToolUse hooks the orchestrator acted on. Spec target ≥40%."
+	}),
+	orientationUsefulness: Schema.Struct({
+		total: Schema.Number.annotations(totalAnnotation),
+		referencedCount: Schema.Number.annotations({ description: "Sessions where `triage_brief` / `wrapup_prompt` content was referenced in subsequent decisions." }),
+		ratio: Schema.Number.annotations(ratioAnnotation)
+	}).annotations({
+		title: "Orientation usefulness",
+		description: "Fraction of sessions where orientation prompts measurably steered orchestrator behaviour. Spec target ≥50%."
+	}),
+	antiPatternDetectionRate: Schema.Struct({
+		total: Schema.Number.annotations(totalAnnotation),
+		cleanSessions: Schema.Number.annotations({ description: "Sessions that produced no `tdd_artifacts(kind='test_weakened')` rows or DATABASE_BYPASS notes." }),
+		ratio: Schema.Number.annotations(ratioAnnotation)
+	}).annotations({
+		title: "Anti-pattern detection rate",
+		description: "Fraction of sessions free of weakening edits or sqlite3 bypass attempts. Spec target ≥95%."
+	})
+}).annotations({
+	identifier: "AcceptanceMetricsResult",
+	title: "Acceptance metrics",
+	description: "The four spec Annex A metrics computed from the current database. Each carries a sample size, a count, and a ratio."
+});
+const fmtBucket = (r) => r.total === 0 ? "no data" : `${(r.ratio * 100).toFixed(1)}% (n=${r.total})`;
+const formatAcceptanceMetricsMarkdown = (m) => [
+	"# Acceptance metrics",
+	"",
+	`1. Phase-evidence integrity: ${fmtBucket(m.phaseEvidenceIntegrity)} — target ≥80%`,
+	`2. Compliance-hook responsiveness: ${fmtBucket(m.complianceHookResponsiveness)} — target ≥40%`,
+	`3. Orientation usefulness: ${fmtBucket(m.orientationUsefulness)} — target ≥50%`,
+	`4. Anti-pattern detection rate: ${fmtBucket(m.antiPatternDetectionRate)} — target ≥95%`
+].join("\n");
+const AcceptanceMetricsAsMarkdown = Schema.transformOrFail(AcceptanceMetricsResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatAcceptanceMetricsMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "AcceptanceMetricsAsMarkdown is one-way: markdown cannot be parsed back to AcceptanceMetricsResult."))
+});
+const acceptanceMetrics = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({}))).query(async ({ ctx }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	return yield* (yield* DataReader).computeAcceptanceMetrics();
+})));
+
+//#endregion
+export { AcceptanceMetricsAsMarkdown, AcceptanceMetricsResult, acceptanceMetrics };

package/tools/cache-health.js

@@ -0,0 +1,83 @@
+import { publicProcedure } from "../context.js";
+import { CacheManifest, DataReader } from "@vitest-agent/sdk";
+import { Effect, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/cache-health.ts
+/**
+* `cache_health` MCP tool — Schema-driven implementation.
+*
+* Wraps the cache manifest in a `CacheHealthResult` Schema that
+* captures both the present and absent cases. The text channel
+* renders the same markdown the previous implementation produced;
+* the structured payload now exposes `manifestPresent` plus the
+* computed `ageMs` so agents can branch on freshness without parsing
+* prose.
+*
+* @packageDocumentation
+*/
+const ManifestPresent = Schema.Struct({
+	manifestPresent: Schema.Literal(true).annotations({ description: "Discriminant — `true` when a cache manifest exists." }),
+	manifest: CacheManifest.annotations({ description: "Full cache manifest content as written by the reporter." }),
+	ageMs: Schema.Number.annotations({ description: "Milliseconds since the manifest was last updated. Computed at query time, not stored." }),
+	stale: Schema.Boolean.annotations({ description: "Convenience flag — `true` when `ageMs` exceeds 24 hours, otherwise `false`." })
+}).annotations({
+	identifier: "CacheHealthPresent",
+	title: "Cache manifest present"
+});
+const ManifestAbsent = Schema.Struct({ manifestPresent: Schema.Literal(false).annotations({ description: "Discriminant — `false` when no manifest has been written yet (run tests to populate the cache)." }) }).annotations({
+	identifier: "CacheHealthAbsent",
+	title: "Cache manifest absent"
+});
+const CacheHealthResult = Schema.Union(ManifestPresent, ManifestAbsent).annotations({
+	identifier: "CacheHealthResult",
+	title: "cache_health result",
+	description: "Cache health snapshot. Discriminate on `manifestPresent` to see whether the manifest exists."
+});
+const STALE_AFTER_MS = 1440 * 60 * 1e3;
+const iconForResult = (r) => {
+	if (r === "passed") return "✅";
+	if (r === "failed") return "❌";
+	if (r === "interrupted") return "⚠️";
+	return "⬜";
+};
+const formatCacheHealthMarkdown = (data) => {
+	const lines = ["# Cache Health", ""];
+	if (data.manifestPresent === false) {
+		lines.push("- ❌ **Manifest:** not found — run tests to populate the cache");
+		return lines.join("\n");
+	}
+	const { manifest, ageMs, stale } = data;
+	const ageHours = ageMs / (1e3 * 60 * 60);
+	lines.push("- ✅ **Manifest:** present");
+	lines.push(`- ℹ️ **Projects:** ${manifest.projects.length}`);
+	lines.push(`- ℹ️ **Cache directory:** \`${manifest.cacheDir}\``);
+	lines.push(`- ℹ️ **Last updated:** ${manifest.updatedAt}`);
+	if (stale) lines.push(`- ⚠️ **Staleness:** cache is ${Math.round(ageHours)} hours old — consider re-running tests`);
+	else lines.push(`- ✅ **Staleness:** cache is ${Math.round(ageHours * 60)} minutes old`);
+	lines.push("", "## Projects", "");
+	for (const entry of manifest.projects) {
+		const lastRun = entry.lastRun ? new Date(entry.lastRun).toLocaleString() : "never";
+		lines.push(`- ${iconForResult(entry.lastResult)} **${entry.project}** — last run: ${lastRun}`);
+	}
+	return lines.join("\n");
+};
+const CacheHealthAsMarkdown = Schema.transformOrFail(CacheHealthResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatCacheHealthMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "CacheHealthAsMarkdown is one-way: markdown cannot be parsed back to CacheHealthResult."))
+});
+const cacheHealth = publicProcedure.query(async ({ ctx }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const manifestOpt = yield* (yield* DataReader).getManifest();
+	if (Option.isNone(manifestOpt)) return { manifestPresent: false };
+	const manifest = manifestOpt.value;
+	const ageMs = Date.now() - new Date(manifest.updatedAt).getTime();
+	return {
+		manifestPresent: true,
+		manifest,
+		ageMs,
+		stale: ageMs > STALE_AFTER_MS
+	};
+})));
+
+//#endregion
+export { CacheHealthAsMarkdown, CacheHealthResult, cacheHealth };

package/tools/commit-changes.js

@@ -0,0 +1,64 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/tools/commit-changes.ts
+/**
+* `commit_changes` MCP tool — Schema-driven implementation.
+*
+* @packageDocumentation
+*/
+const FileRow = Schema.Struct({
+	filePath: Schema.String.annotations({ description: "Repo-relative path of the changed file." }),
+	changeKind: Schema.Literal("added", "modified", "deleted", "renamed", "untracked-modified").annotations({ description: "How the file changed in this commit (or `untracked-modified` for working-tree changes attributed to a commit)." })
+}).annotations({ identifier: "CommitFileRow" });
+const CommitRow = Schema.Struct({
+	sha: Schema.String.annotations({ description: "Full git commit SHA-1." }),
+	parentSha: Schema.NullOr(Schema.String).annotations({ description: "Parent commit SHA, or `null` for the root commit / when no parent was recorded." }),
+	message: Schema.NullOr(Schema.String).annotations({ description: "Commit message subject + body, or `null` if not captured." }),
+	author: Schema.NullOr(Schema.String).annotations({ description: "Commit author in `Name <email>` form when captured." }),
+	committedAt: Schema.NullOr(Schema.String).annotations({ description: "ISO-8601 commit timestamp." }),
+	branch: Schema.NullOr(Schema.String).annotations({ description: "Branch the commit was recorded on at hook fire time." }),
+	files: Schema.Array(FileRow).annotations({ description: "Files this commit changed, with per-file change kinds." })
+}).annotations({ identifier: "CommitRow" });
+const CommitChangesResult = Schema.Struct({
+	filterSha: Schema.optional(Schema.String).annotations({ description: "Echo of the optional `sha` filter the caller passed; absent when no filter was applied (recent commits returned)." }),
+	count: Schema.Number.annotations({ description: "Number of commit rows returned." }),
+	commits: Schema.Array(CommitRow).annotations({ description: "Matching commits, newest first when `sha` was omitted; up to 20 rows." })
+}).annotations({
+	identifier: "CommitChangesResult",
+	title: "commit_changes result",
+	description: "Commit metadata + per-file changes captured by the post-commit Bash hook."
+});
+const formatCommitChangesMarkdown = (data) => {
+	if (data.commits.length === 0) return data.filterSha !== void 0 ? `No commit recorded with sha ${data.filterSha}.` : "No commits recorded yet. The PostToolUse hook on `git commit` populates this table.";
+	const lines = [];
+	for (const e of data.commits) {
+		lines.push(`## ${e.sha.slice(0, 8)} ${e.message ?? "(no message)"}`);
+		if (e.author !== null) lines.push(`- Author: ${e.author}`);
+		if (e.committedAt !== null) lines.push(`- When: ${e.committedAt}`);
+		if (e.branch !== null) lines.push(`- Branch: ${e.branch}`);
+		if (e.files.length > 0) {
+			lines.push("- Changed files:");
+			for (const f of e.files) lines.push(`  - \`${f.filePath}\` (${f.changeKind})`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n").trim();
+};
+const CommitChangesAsMarkdown = Schema.transformOrFail(CommitChangesResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatCommitChangesMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "CommitChangesAsMarkdown is one-way: markdown cannot be parsed back to CommitChangesResult."))
+});
+const commitChanges = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({ sha: Schema.optional(Schema.String) }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const entries = yield* (yield* DataReader).getCommitChanges(input.sha);
+	return {
+		...input.sha !== void 0 && { filterSha: input.sha },
+		count: entries.length,
+		commits: entries
+	};
+})));
+
+//#endregion
+export { CommitChangesAsMarkdown, CommitChangesResult, commitChanges };

package/tools/configure.js

@@ -0,0 +1,107 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/configure.ts
+/**
+* `configure` MCP tool — Schema-driven implementation.
+*
+* @packageDocumentation
+*/
+const SettingsRowSchema = Schema.Struct({
+	hash: Schema.String.annotations({ description: "Stable SHA-1 of the captured Vitest settings; `test_runs.settings_hash` foreign key." }),
+	reporters: Schema.NullOr(Schema.String).annotations({ description: "Comma-separated reporter list as resolved from the user's vitest config." }),
+	coverageEnabled: Schema.Boolean.annotations({ description: "Whether coverage was on for this run." }),
+	coverageProvider: Schema.NullOr(Schema.String).annotations({ description: "Coverage provider (`v8` or `istanbul`)." }),
+	coverageThresholds: Schema.NullOr(Schema.String).annotations({ description: "JSON-encoded threshold table when present; `null` when no thresholds were configured." }),
+	coverageTargets: Schema.NullOr(Schema.String).annotations({ description: "JSON-encoded aspirational target table when present." }),
+	pool: Schema.NullOr(Schema.String).annotations({ description: "Vitest pool (`forks` / `threads` / `vmThreads`)." }),
+	shard: Schema.NullOr(Schema.String).annotations({ description: "Shard descriptor when running sharded (`1/4` form)." }),
+	project: Schema.NullOr(Schema.String).annotations({ description: "Project name within a multi-project setup." }),
+	environment: Schema.NullOr(Schema.String).annotations({ description: "Test environment (`node`, `jsdom`, etc.)." }),
+	envVars: Schema.Record({
+		key: Schema.String,
+		value: Schema.String
+	}).annotations({ description: "Captured CI / test env vars associated with this settings hash." }),
+	capturedAt: Schema.String.annotations({ description: "ISO-8601 timestamp the settings row was first written." })
+}).annotations({
+	identifier: "SettingsRowSchema",
+	title: "Vitest settings snapshot"
+});
+const SettingsFound = Schema.Struct({
+	found: Schema.Literal(true).annotations({ description: "Discriminant — `true` when settings were located." }),
+	source: Schema.Literal("requested", "latest").annotations({ description: "`requested` when the caller supplied `settingsHash`; `latest` when the most-recent row was returned." }),
+	settings: SettingsRowSchema
+}).annotations({ identifier: "ConfigureFound" });
+const SettingsAbsent = Schema.Struct({
+	found: Schema.Literal(false).annotations({ description: "Discriminant — `false` when no settings matched." }),
+	source: Schema.Literal("requested", "latest"),
+	requestedHash: Schema.optional(Schema.String).annotations({ description: "Echo of the hash the caller passed; absent when the empty `latest` lookup found nothing." })
+}).annotations({ identifier: "ConfigureAbsent" });
+const ConfigureResult = Schema.Union(SettingsFound, SettingsAbsent).annotations({
+	identifier: "ConfigureResult",
+	title: "configure result",
+	description: "Captured Vitest settings for a run, or an absence record when the lookup found nothing."
+});
+const formatSettings = (s) => {
+	const lines = [`# Settings — \`${s.hash}\``, ""];
+	lines.push(`**Captured:** ${s.capturedAt}`);
+	if (s.project !== null) lines.push(`**Project:** ${s.project}`);
+	if (s.environment !== null) lines.push(`**Environment:** ${s.environment}`);
+	if (s.pool !== null) lines.push(`**Pool:** ${s.pool}`);
+	if (s.shard !== null) lines.push(`**Shard:** ${s.shard}`);
+	lines.push("", "## Coverage", `- **Enabled:** ${s.coverageEnabled ? "yes" : "no"}`);
+	if (s.coverageProvider !== null) lines.push(`- **Provider:** ${s.coverageProvider}`);
+	if (s.coverageThresholds !== null) lines.push(`- **Thresholds:** \`${s.coverageThresholds}\``);
+	if (s.coverageTargets !== null) lines.push(`- **Targets:** \`${s.coverageTargets}\``);
+	if (s.reporters !== null) lines.push("", "## Reporters", `\`${s.reporters}\``);
+	const envKeys = Object.keys(s.envVars);
+	if (envKeys.length > 0) {
+		lines.push("", "## Environment Variables");
+		for (const key of envKeys) lines.push(`- \`${key}\`: \`${s.envVars[key]}\``);
+	}
+	return lines.join("\n");
+};
+const formatConfigureMarkdown = (data) => {
+	if (data.found) return formatSettings(data.settings);
+	if (data.source === "latest") return [
+		"# Configure",
+		"",
+		"No settings captured yet. Run tests first.",
+		"",
+		"Configuration is written automatically by `AgentPlugin` when tests run."
+	].join("\n");
+	return `No settings found for hash \`${data.requestedHash ?? "(unknown)"}\`.`;
+};
+const ConfigureAsMarkdown = Schema.transformOrFail(ConfigureResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatConfigureMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "ConfigureAsMarkdown is one-way: markdown cannot be parsed back to ConfigureResult."))
+});
+const configure = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({ settingsHash: Schema.optional(Schema.String) }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const reader = yield* DataReader;
+	if (input.settingsHash === void 0) {
+		const latestOpt = yield* reader.getLatestSettings();
+		return Option.isNone(latestOpt) ? {
+			found: false,
+			source: "latest"
+		} : {
+			found: true,
+			source: "latest",
+			settings: latestOpt.value
+		};
+	}
+	const settingsOpt = yield* reader.getSettings(input.settingsHash);
+	return Option.isNone(settingsOpt) ? {
+		found: false,
+		source: "requested",
+		requestedHash: input.settingsHash
+	} : {
+		found: true,
+		source: "requested",
+		settings: settingsOpt.value
+	};
+})));
+
+//#endregion
+export { ConfigureAsMarkdown, ConfigureResult, configure };

package/tools/coverage.js

@@ -0,0 +1,76 @@
+import { publicProcedure } from "../context.js";
+import { CoverageReport, DataReader } from "@vitest-agent/sdk";
+import { Effect, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/coverage.ts
+/**
+* `test_coverage` MCP tool — Schema-driven implementation.
+*
+* @packageDocumentation
+*/
+const CoverageAvailable = Schema.Struct({
+	dataAvailable: Schema.Literal(true),
+	project: Schema.String,
+	coverage: CoverageReport
+}).annotations({ identifier: "TestCoverageAvailable" });
+const CoverageAbsent = Schema.Struct({
+	dataAvailable: Schema.Literal(false),
+	project: Schema.String
+}).annotations({ identifier: "TestCoverageAbsent" });
+const TestCoverageResult = Schema.Union(CoverageAvailable, CoverageAbsent).annotations({
+	identifier: "TestCoverageResult",
+	title: "test_coverage result",
+	description: "Per-project coverage report. Discriminate on `dataAvailable` for cold-start handling."
+});
+const formatTestCoverageMarkdown = (data) => {
+	if (!data.dataAvailable) return "No coverage data available. Run tests with coverage enabled.";
+	const lines = ["# Coverage Report", ""];
+	const { totals, thresholds } = data.coverage;
+	lines.push("## Totals", "", "| Metric | Value | Threshold |", "| --- | --- | --- |");
+	const metrics = [
+		"statements",
+		"branches",
+		"functions",
+		"lines"
+	];
+	for (const metric of metrics) {
+		const value = totals[metric];
+		const threshold = thresholds.global[metric];
+		const thresholdStr = threshold !== void 0 ? `${threshold}%` : "—";
+		const icon = threshold !== void 0 && value < threshold ? "❌" : "✅";
+		lines.push(`| ${metric} | ${icon} ${value.toFixed(2)}% | ${thresholdStr} |`);
+	}
+	lines.push("");
+	if (data.coverage.lowCoverage.length > 0) {
+		lines.push("## Coverage Gaps", "", "Files below coverage threshold:", "");
+		for (const fileCoverage of data.coverage.lowCoverage) {
+			lines.push(`### \`${fileCoverage.file}\``, "", "| Metric | Value |", "| --- | --- |");
+			for (const metric of metrics) lines.push(`| ${metric} | ${fileCoverage.summary[metric].toFixed(2)}% |`);
+			if (fileCoverage.uncoveredLines) lines.push(`| Uncovered lines | \`${fileCoverage.uncoveredLines}\` |`);
+			lines.push("");
+		}
+	} else lines.push("✅ All files meet coverage thresholds.", "");
+	return lines.join("\n");
+};
+const TestCoverageAsMarkdown = Schema.transformOrFail(TestCoverageResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTestCoverageMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TestCoverageAsMarkdown is one-way."))
+});
+const testCoverage = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({ project: Schema.optional(Schema.String) }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const project = input.project ?? "default";
+	const coverageOpt = yield* reader.getCoverage(project);
+	if (Option.isNone(coverageOpt)) return {
+		dataAvailable: false,
+		project
+	};
+	return {
+		dataAvailable: true,
+		project,
+		coverage: coverageOpt.value
+	};
+})));
+
+//#endregion
+export { TestCoverageAsMarkdown, TestCoverageResult, testCoverage };

package/tools/errors.js

@@ -0,0 +1,151 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/tools/errors.ts
+/**
+* `test_errors` MCP tool — Schema-driven implementation.
+*
+* The Effect Schema `TestErrorsResult` is the canonical contract for
+* the tool's output. The same Schema:
+*   - types the procedure's return value;
+*   - drives `formatTestErrorsMarkdown` (input typed via `Schema.Type`);
+*   - composes into `TestErrorsAsMarkdown`, a one-way
+*     `Schema.transformOrFail` whose `encode` direction renders the
+*     markdown the text channel carries (decode is forbidden because
+*     markdown rendering is lossy);
+*   - bridges to zod via `effectToZodSchema` for the SDK's
+*     `outputSchema` field, so the structured shape we declare to MCP
+*     stays in lockstep with what the procedure actually emits.
+*
+* @packageDocumentation
+*/
+/** One row in the structured `errors[]` array. */
+const TestErrorRow = Schema.Struct({
+	id: Schema.Number.annotations({
+		title: "test_errors.id",
+		description: "Numeric primary key of this error row. Pass as `citedTestErrorId` when calling `hypothesis (action: record)`."
+	}),
+	topStackFrameId: Schema.NullOr(Schema.Number).annotations({
+		title: "stack_frames.id (top frame)",
+		description: "`stack_frames.id` of the top frame (ordinal=0); `null` when no frames were captured. Pass as `citedStackFrameId` to `hypothesis (action: record)`."
+	}),
+	name: Schema.NullOr(Schema.String).annotations({ description: "Error class name (e.g. `AssertionError`, `TypeError`); `null` when the underlying throw provided no name." }),
+	message: Schema.String.annotations({ description: "Error message text as the test framework reported it." }),
+	diff: Schema.NullOr(Schema.String).annotations({ description: "Unified-diff representation of expected vs. actual when the assertion produced one; `null` otherwise." }),
+	actual: Schema.NullOr(Schema.String).annotations({ description: "Actual value the assertion received, when captured." }),
+	expected: Schema.NullOr(Schema.String).annotations({ description: "Expected value the assertion compared against, when captured." }),
+	stack: Schema.NullOr(Schema.String).annotations({ description: "Newline-joined stack frames as the framework formatted them; structured frames live in `stack_frames`." }),
+	scope: Schema.Literal("test", "suite", "module", "unhandled").annotations({ description: "Where the error fired: `test` (a single test case), `suite` (a `describe` setup), `module` (collection / import time), or `unhandled` (uncaught from a background context)." }),
+	testFullName: Schema.NullOr(Schema.String).annotations({ description: "Full hierarchical test name (`describe > it`); `null` for non-test scopes (`module`, `unhandled`)." }),
+	moduleFile: Schema.NullOr(Schema.String).annotations({ description: "Repo-relative path of the test module the error originated in." })
+}).annotations({
+	identifier: "TestErrorRow",
+	title: "Test error row",
+	description: "Single error captured during a test run, joined with stack frame and source-location context."
+});
+/** Top-level structured payload — populates `structuredContent`. */
+const TestErrorsResult = Schema.Struct({
+	project: Schema.String.annotations({
+		title: "Project name",
+		description: "Workspace project key the run was attributed to (e.g. `playground`, `@org/pkg`).",
+		examples: ["playground", "@org/pkg"]
+	}),
+	errorName: Schema.optional(Schema.String).annotations({ description: "Echo of the optional `errorName` filter the caller passed; absent when no filter was applied." }),
+	count: Schema.Number.annotations({ description: "Total error rows in `errors`." }),
+	errors: Schema.Array(TestErrorRow).annotations({ description: "Errors from the most recent test run for this project, optionally filtered by `errorName`. Empty when no errors matched." })
+}).annotations({
+	identifier: "TestErrorsResult",
+	title: "test_errors result",
+	description: "Structured payload of the `test_errors` MCP tool. Carries the cite-able test_errors.id and stack_frames.id values agents need for `hypothesis (action: record)`."
+});
+const TRUNCATION_LIMIT = 500;
+const truncate = (s) => s.length <= TRUNCATION_LIMIT ? {
+	value: s,
+	truncated: false
+} : {
+	value: s.slice(0, TRUNCATION_LIMIT),
+	truncated: true
+};
+/**
+* Pure markdown renderer. Exposed so the formatter tests can exercise
+* it without rebuilding a `Schema.encode` runtime.
+*/
+const formatTestErrorsMarkdown = (data) => {
+	if (data.errors.length === 0) return `No errors found for project \`${data.project}\`.`;
+	const lines = [`# Test Errors — ${data.project}`, ""];
+	for (const error of data.errors) {
+		const name = error.name ?? "(unnamed)";
+		const idTokens = `[testErrorId=${error.id}${error.topStackFrameId !== null ? ` topStackFrameId=${error.topStackFrameId}` : ""}]`;
+		lines.push(`## ${name} ${idTokens}`);
+		lines.push("");
+		lines.push(`**Scope:** ${error.scope}`);
+		if (error.testFullName !== null) lines.push(`**Test:** ${error.testFullName}`);
+		if (error.moduleFile !== null) lines.push(`**File:** \`${error.moduleFile}\``);
+		lines.push("");
+		lines.push("**Cite-able IDs (for `hypothesis (action: record)`):**");
+		lines.push(`- citedTestErrorId: ${error.id}`);
+		if (error.topStackFrameId !== null) lines.push(`- citedStackFrameId: ${error.topStackFrameId}`);
+		else lines.push("- citedStackFrameId: (none — no stack frames recorded for this error)");
+		lines.push("");
+		lines.push("**Message:**");
+		lines.push(`> ${error.message.split("\n").join("\n> ")}`);
+		if (error.diff !== null) {
+			lines.push("");
+			lines.push("**Diff:**");
+			lines.push("```diff");
+			const t = truncate(error.diff);
+			lines.push(t.value);
+			if (t.truncated) lines.push("... (truncated)");
+			lines.push("```");
+		}
+		if (error.stack !== null && error.diff === null) {
+			lines.push("");
+			lines.push("**Stack:**");
+			lines.push("```");
+			const t = truncate(error.stack);
+			lines.push(t.value);
+			if (t.truncated) lines.push("... (truncated)");
+			lines.push("```");
+		}
+		lines.push("");
+	}
+	return lines.join("\n");
+};
+/**
+* One-way codec: structured `TestErrorsResult` → markdown text.
+*
+* `Schema.transformOrFail`'s `decode` direction goes
+* `From.Type → To.Encoded`; in this transform `From = TestErrorsResult`
+* and `To = Schema.String`, so the resulting schema is
+* `Schema<string, TestErrorsResultType>` — its parsed Type is the
+* markdown string and its Encoded form is the structured row. That
+* means `Schema.decode(TestErrorsAsMarkdown)(data)` produces markdown
+* (the rendering direction) and `Schema.encode(...)` would attempt
+* the lossy reverse, which is forbidden here.
+*
+* Boundary callers should use
+* `Schema.decodeSync(TestErrorsAsMarkdown)(data)` to render. Test
+* suites can drive the same path without mocking anything — the
+* transform IS the rendering contract.
+*/
+const TestErrorsAsMarkdown = Schema.transformOrFail(TestErrorsResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTestErrorsMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TestErrorsAsMarkdown is one-way: markdown cannot be parsed back to TestErrorsResult. Consume the procedure's structured output (or MCP structuredContent) directly."))
+});
+const testErrors = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	project: Schema.String,
+	errorName: Schema.optional(Schema.String)
+}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const errors = yield* (yield* DataReader).getErrors(input.project, input.errorName);
+	return {
+		project: input.project,
+		...input.errorName !== void 0 && { errorName: input.errorName },
+		count: errors.length,
+		errors
+	};
+})));
+
+//#endregion
+export { TestErrorsAsMarkdown, TestErrorsResult, testErrors };