@vitest-agent/mcp 1.0.0

package/tools/failure-signature-get.js

@@ -0,0 +1,73 @@
+import { publicProcedure } from "../context.js";
+import { DataReader } from "@vitest-agent/sdk";
+import { Effect, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/failure-signature-get.ts
+/**
+* `failure_signature_get` MCP tool — Schema-driven implementation.
+*
+* @packageDocumentation
+*/
+const RecentError = Schema.Struct({
+	runId: Schema.Number,
+	errorName: Schema.NullOr(Schema.String),
+	message: Schema.String
+});
+const SignatureFound = Schema.Struct({
+	found: Schema.Literal(true).annotations({ description: "Discriminant — `true` when a signature row matched." }),
+	signatureHash: Schema.String.annotations({
+		title: "failure_signatures.signature_hash",
+		description: "16-char SHA-256 over (error_name, normalized assertion shape, top-frame function name, function-boundary line)."
+	}),
+	firstSeenRunId: Schema.NullOr(Schema.Number),
+	firstSeenAt: Schema.String,
+	lastSeenAt: Schema.NullOr(Schema.String),
+	occurrenceCount: Schema.Number.annotations({ description: "Total times this signature has been observed." }),
+	recentErrors: Schema.Array(RecentError)
+});
+const SignatureMissing = Schema.Struct({
+	found: Schema.Literal(false),
+	requestedHash: Schema.String
+});
+const FailureSignatureGetResult = Schema.Union(SignatureFound, SignatureMissing).annotations({
+	identifier: "FailureSignatureGetResult",
+	title: "failure_signature_get result",
+	description: "Discriminate on `found`. Found rows carry first/last-seen timestamps and recent occurrences."
+});
+const formatFailureSignatureMarkdown = (data) => {
+	if (!data.found) return `No failure signature found with hash=${data.requestedHash}.`;
+	const lines = [
+		`# Failure Signature \`${data.signatureHash}\``,
+		"",
+		`**Hash:** ${data.signatureHash}`,
+		"",
+		`- first_seen_at: ${data.firstSeenAt}`,
+		`- last_seen_at: ${data.lastSeenAt ?? "unknown"}`,
+		`- first_seen_run_id: ${data.firstSeenRunId ?? "unknown"}`,
+		`- occurrence_count: ${data.occurrenceCount}`
+	];
+	if (data.recentErrors.length > 0) {
+		lines.push("", "## Recent Errors", "");
+		for (const e of data.recentErrors) lines.push(`- run=${e.runId} name=${e.errorName ?? "(none)"}: ${e.message.slice(0, 120)}`);
+	}
+	return lines.join("\n");
+};
+const FailureSignatureGetAsMarkdown = Schema.transformOrFail(FailureSignatureGetResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatFailureSignatureMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "FailureSignatureGetAsMarkdown is one-way."))
+});
+const failureSignatureGet = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({ hash: Schema.String }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const opt = yield* (yield* DataReader).getFailureSignatureByHash(input.hash);
+	if (Option.isNone(opt)) return {
+		found: false,
+		requestedHash: input.hash
+	};
+	return {
+		found: true,
+		...opt.value
+	};
+})));
+
+//#endregion
+export { FailureSignatureGetAsMarkdown, FailureSignatureGetResult, failureSignatureGet };

package/tools/file-coverage.js

@@ -0,0 +1,106 @@
+import { publicProcedure } from "../context.js";
+import { CoverageTotals, DataReader, FileCoverageReport } from "@vitest-agent/sdk";
+import { Effect, Option, ParseResult, Schema } from "effect";
+
+//#region src/tools/file-coverage.ts
+/**
+* `file_coverage` MCP tool — Schema-driven implementation.
+*
+* @packageDocumentation
+*/
+const CoverageGlobalThresholds = Schema.Struct({
+	statements: Schema.optional(Schema.Number),
+	branches: Schema.optional(Schema.Number),
+	functions: Schema.optional(Schema.Number),
+	lines: Schema.optional(Schema.Number)
+});
+const FileCoverageMatched = Schema.Struct({
+	dataAvailable: Schema.Literal(true),
+	matched: Schema.Literal(true),
+	filePath: Schema.String,
+	report: FileCoverageReport,
+	globalThresholds: CoverageGlobalThresholds,
+	relatedTestFiles: Schema.Array(Schema.String)
+}).annotations({ identifier: "FileCoverageMatched" });
+const FileCoverageNoMatch = Schema.Struct({
+	dataAvailable: Schema.Literal(true),
+	matched: Schema.Literal(false),
+	filePath: Schema.String,
+	totals: CoverageTotals,
+	relatedTestFiles: Schema.Array(Schema.String)
+}).annotations({ identifier: "FileCoverageNoMatch" });
+const FileCoverageAbsent = Schema.Struct({
+	dataAvailable: Schema.Literal(false),
+	filePath: Schema.String
+}).annotations({ identifier: "FileCoverageAbsent" });
+const FileCoverageResult = Schema.Union(FileCoverageMatched, FileCoverageNoMatch, FileCoverageAbsent).annotations({
+	identifier: "FileCoverageResult",
+	title: "file_coverage result",
+	description: "Per-file coverage with related tests. Discriminate on `dataAvailable` then on `matched`."
+});
+const formatFileCoverageMarkdown = (data) => {
+	if (!data.dataAvailable) return "No coverage data available. Run tests with coverage enabled.";
+	const lines = [`# Coverage: \`${data.filePath}\``, ""];
+	const metrics = [
+		"statements",
+		"branches",
+		"functions",
+		"lines"
+	];
+	if (data.matched) {
+		lines.push("## Metrics", "", "| Metric | Value | Threshold |", "| --- | --- | --- |");
+		for (const metric of metrics) {
+			const value = data.report.summary[metric];
+			const threshold = data.globalThresholds[metric];
+			const thresholdStr = threshold !== void 0 ? `${threshold}%` : "—";
+			const icon = threshold !== void 0 && value < threshold ? "❌" : "✅";
+			lines.push(`| ${metric} | ${icon} ${value.toFixed(2)}% | ${thresholdStr} |`);
+		}
+		if (data.report.uncoveredLines) lines.push("", "## Uncovered Lines", "", `\`${data.report.uncoveredLines}\``);
+		lines.push("", "## Next steps", "", "- Use test({ action: \"for_file\" }) to find tests covering this file", "- Write tests targeting the uncovered lines");
+	} else lines.push("This file is not in the low-coverage list.", "", "Possible reasons:", "- File meets all coverage thresholds", "- File was not included in the coverage run", "- File path does not match any tracked source file", "", "## Project Coverage Totals", "", "| Metric | Value |", "| --- | --- |", `| statements | ${data.totals.statements.toFixed(2)}% |`, `| branches | ${data.totals.branches.toFixed(2)}% |`, `| functions | ${data.totals.functions.toFixed(2)}% |`, `| lines | ${data.totals.lines.toFixed(2)}% |`);
+	if (data.relatedTestFiles.length > 0) {
+		lines.push("", "## Tests Covering This File", "");
+		for (const tf of data.relatedTestFiles) lines.push(`- \`${tf}\``);
+	}
+	return lines.join("\n");
+};
+const FileCoverageAsMarkdown = Schema.transformOrFail(FileCoverageResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatFileCoverageMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "FileCoverageAsMarkdown is one-way."))
+});
+const fileCoverage = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({
+	filePath: Schema.String,
+	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,
+		filePath: input.filePath
+	};
+	const coverage = coverageOpt.value;
+	const normalizedPath = input.filePath.replace(/^\.\//, "");
+	const match = coverage.lowCoverage.find((f) => f.file === normalizedPath) ?? coverage.lowCoverage.find((f) => f.file.endsWith(normalizedPath) || normalizedPath.endsWith(f.file));
+	const relatedTestFiles = yield* reader.getTestsForFile(normalizedPath);
+	if (match) return {
+		dataAvailable: true,
+		matched: true,
+		filePath: normalizedPath,
+		report: match,
+		globalThresholds: coverage.thresholds.global,
+		relatedTestFiles
+	};
+	return {
+		dataAvailable: true,
+		matched: false,
+		filePath: normalizedPath,
+		totals: coverage.totals,
+		relatedTestFiles
+	};
+})));
+
+//#endregion
+export { FileCoverageAsMarkdown, FileCoverageResult, fileCoverage };

package/tools/help.js

@@ -0,0 +1,146 @@
+import { publicProcedure } from "../context.js";
+import { Schema } from "effect";
+
+//#region src/tools/help.ts
+const HelpResult = Schema.Struct({ helpText: Schema.String.annotations({ description: "Markdown table of every MCP tool with parameters and a one-line description." }) }).annotations({
+	identifier: "HelpResult",
+	title: "help result",
+	description: "Static help reference. Read structuredContent.helpText programmatically; the same string lives in content[].text for transcripts."
+});
+const HELP_TEXT = `# vitest-agent MCP Tools
+
+> Consolidated tool surface (Phase 3 of the agent-agnostic taxonomy).
+> Action-keyed tools collapse the prior 5–6 CRUD families into one tool
+> per noun: \`hypothesis\`, \`note\`, \`inventory\`, \`test\`,
+> \`tdd_goal\`, \`tdd_behavior\`, \`tdd_task\`.
+
+## General
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`help\` | _(none)_ | List all available MCP tools with parameters |
+| \`ping\` | _(none)_ | Ping the MCP server — returns 'pong'. Used to verify hot-patch reload |
+
+## Test Data (read-only)
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`test_status\` | \`project?\` | Per-project test pass/fail state |
+| \`test_overview\` | \`project?\` | Test landscape with run metrics |
+| \`test_coverage\` | \`project?\` | Coverage gaps with uncovered lines |
+| \`file_coverage\` | \`filePath\`, \`project?\` | Per-file coverage with uncovered lines and related tests |
+| \`test_history\` | \`project\` | Flaky/persistent/recovered tests |
+| \`test_trends\` | \`project\`, \`limit?\` | Coverage trajectory over time |
+| \`test_errors\` | \`project\`, \`errorName?\`, \`format?\` (\`markdown\` \\| \`xml\`) | Errors with diffs, stacks, and the cite-able \`testErrorId\` / \`topStackFrameId\` values needed by \`hypothesis (action: record)\` |
+| \`test\` | \`action\` (\`list\`/\`get\`/\`for_file\`/\`for_tag\`), plus per-action params | Consolidated test inspection: list/get/for_file/for_tag |
+
+\`test\` actions:
+- \`{ action: "list", project?, state?, module?, limit? }\`
+- \`{ action: "get", fullName, project? }\`
+- \`{ action: "for_file", filePath }\`
+- \`{ action: "for_tag", tag, project? }\` — list every test carrying a tag, grouped by project (or one group when project is supplied)
+
+## Discovery
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`inventory\` | \`kind\` (\`project\`/\`module\`/\`suite\`/\`session\`/\`tag\`), plus per-kind params | Consolidated entity discovery |
+| \`settings_list\` | _(none)_ | Vitest config snapshots |
+
+\`inventory\` kinds:
+- \`{ kind: "project" }\`
+- \`{ kind: "module", project? }\`
+- \`{ kind: "suite", project?, module? }\`
+- \`{ kind: "session", project?, agentKind?, limit? }\` (omit \`id\` to list)
+- \`{ kind: "session", id }\` (single-session detail)
+- \`{ kind: "tag", project? }\` — per-tag module/test counts; unscoped form carries a \`byProject\` breakdown per tag
+
+## Execution
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`run_tests\` | \`files?\`, \`project?\`, \`tags?\`, \`passWithNoTests?\`, \`timeout?\`, \`format?\` | Run vitest with optional filters. \`tags\` is a structured \`{ all?, any?, none? }\` filter that intersects with \`project\` and \`files\` via AND. When the resolved filter set matches zero test cases the result discriminator is \`no-match\` (carrying the resolved filter context) rather than \`ok\`. \`passWithNoTests\` is a per-call override of Vitest's project-level \`test.passWithNoTests\` policy |
+| \`register_agent\` | \`sessionId\`, \`agentType\`, \`hostKind?\`, \`parentAgentId?\`, \`clientNonce?\`, \`startGitBranch?\`, \`startGitCommitSha?\`, \`startWorktreeDir?\` | Idempotent agent invocation registration |
+
+## Diagnostics
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`cache_health\` | _(none)_ | Database health and staleness check |
+| \`configure\` | \`settingsHash?\` | View captured Vitest settings |
+| \`failure_signature_get\` | \`hash\` | Stable failure signature with recent example errors |
+| \`turn_search\` | \`sessionId?\`, \`since?\`, \`type?\`, \`limit?\` | Search turns (default limit 100) |
+| \`acceptance_metrics\` | _(none)_ | Four spec Annex A acceptance metrics |
+| \`triage_brief\` | \`project?\`, \`maxLines?\` | Orientation triage |
+| \`wrapup_prompt\` | \`sessionId?\`, \`chatId?\`, \`kind?\`, \`userPromptHint?\` | Tailored wrap-up prompt |
+| \`commit_changes\` | \`sha?\` | Commit metadata + changed files |
+
+## Notes
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`note\` | \`action\` (\`create\`/\`list\`/\`get\`/\`update\`/\`delete\`/\`search\`), plus per-action params | Consolidated note CRUD with FTS5 search |
+
+\`note\` actions:
+- \`{ action: "create", title, content, scope, project?, testFullName?, modulePath?, parentNoteId?, createdBy?, expiresAt?, pinned? }\`
+- \`{ action: "list", scope?, project?, testFullName? }\`
+- \`{ action: "get", id }\`
+- \`{ action: "update", id, title?, content?, pinned?, expiresAt? }\`
+- \`{ action: "delete", id }\`
+- \`{ action: "search", query }\`
+
+## Hypotheses
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`hypothesis\` | \`action\` (\`record\`/\`validate\`/\`list\`), plus per-action params | Consolidated hypothesis surface |
+
+\`hypothesis\` actions:
+- \`{ action: "record", sessionId, content, createdTurnId?, citedTestErrorId?, citedStackFrameId? }\`
+- \`{ action: "validate", id, outcome, validatedAt, validatedTurnId? }\`
+- \`{ action: "list", sessionId?, outcome?, limit? }\`
+
+## TDD lifecycle
+
+| Tool | Parameters | Description |
+| ---- | ---------- | ----------- |
+| \`tdd_task\` | \`action\` (\`start\`/\`end\`/\`get\`/\`resume\`), plus per-action params | TDD task lifecycle |
+| \`tdd_goal\` | \`action\` (\`create\`/\`update\`/\`delete\`/\`get\`/\`list\`), plus per-action params | Goals under a TDD task |
+| \`tdd_behavior\` | \`action\` (\`create\`/\`update\`/\`delete\`/\`get\`/\`list_by_goal\`/\`list_by_tdd_task\`), plus per-action params | Behaviors under a goal |
+| \`tdd_artifact_list\` | \`tddTaskId\`, \`artifactKind?\`, \`phaseId?\`, \`behaviorId?\`, \`limit?\`, \`format?\` | List recorded TDD artifacts (newest first); use to find the artifact id to cite in \`tdd_phase_transition_request\` |
+| \`tdd_phase_transition_request\` | \`tddTaskId\`, \`goalId\`, \`requestedPhase\`, \`citedArtifactId?\`, \`citedArtifactKind?\`, \`behaviorId?\`, \`reason?\` | Request a phase transition; validates D2 binding rules. \`citedArtifactId\` is optional — when omitted, the most recent matching artifact (kind from \`citedArtifactKind\` or the transition's required-evidence rule) is auto-resolved |
+| \`tdd_progress_push\` | \`payload\` | Push a TDD progress event to the main agent (best-effort) |
+
+\`tdd_task\` actions:
+- \`{ action: "start", goal, sessionId|chatId, parentTddTaskId?, startedAt?, runId? }\`
+- \`{ action: "end", tddTaskId, outcome, summaryNoteId? }\`
+- \`{ action: "get", tddTaskId }\`
+- \`{ action: "resume", tddTaskId }\`
+
+\`tdd_goal\` actions:
+- \`{ action: "create", tddTaskId, goal }\`
+- \`{ action: "update", id, goal?, status? }\`
+- \`{ action: "delete", id }\`
+- \`{ action: "get", id }\`
+- \`{ action: "list", tddTaskId }\`
+
+\`tdd_behavior\` actions:
+- \`{ action: "create", goalId, behavior, suggestedTestName?, dependsOnBehaviorIds? }\`
+- \`{ action: "update", id, behavior?, suggestedTestName?, status?, dependsOnBehaviorIds? }\`
+- \`{ action: "delete", id }\`
+- \`{ action: "get", id }\`
+- \`{ action: "list_by_goal", goalId }\`
+- \`{ action: "list_by_tdd_task", tddTaskId }\`
+
+## Parameter Key
+
+- **Required** parameters are unmarked
+- **Optional** parameters have \`?\` suffix
+- \`project\` filters to a Vitest project name
+- \`state\` accepts: \`passed\`, \`failed\`, \`skipped\`, \`pending\`
+- \`scope\` accepts: \`global\`, \`project\`, \`module\`, \`suite\`, \`test\`, \`note\`
+`;
+const help = publicProcedure.query(() => ({ helpText: HELP_TEXT }));
+
+//#endregion
+export { HelpResult, help };

package/tools/history.js

@@ -0,0 +1,121 @@
+import { publicProcedure } from "../context.js";
+import { DataReader, HistoryRecord } from "@vitest-agent/sdk";
+import { Effect, ParseResult, Schema } from "effect";
+
+//#region src/tools/history.ts
+/**
+* `test_history` MCP tool — Schema-driven implementation.
+*
+* The structured payload bundles the underlying `HistoryRecord` plus
+* the lighter `flaky` / `persistent` projections the UI uses, so an
+* agent doesn't need to recompute them from runs[].
+*
+* @packageDocumentation
+*/
+const FlakyTestRow = Schema.Struct({
+	fullName: Schema.String.annotations({ description: "Full hierarchical test name (`describe > it`)." }),
+	project: Schema.String,
+	passCount: Schema.Number.annotations({ description: "Number of passing runs in the recent window." }),
+	failCount: Schema.Number.annotations({ description: "Number of failing runs in the recent window." }),
+	lastState: Schema.Literal("passed", "failed").annotations({ description: "State of the most recent run." }),
+	lastTimestamp: Schema.String.annotations({ description: "ISO-8601 timestamp of the most recent run." })
+}).annotations({
+	identifier: "FlakyTestRow",
+	description: "A test that produced both passes and failures within the recent run window."
+});
+const PersistentFailureRow = Schema.Struct({
+	fullName: Schema.String,
+	project: Schema.String,
+	consecutiveFailures: Schema.Number.annotations({ description: "Length of the current uninterrupted failure streak." }),
+	firstFailedAt: Schema.String.annotations({ description: "ISO-8601 timestamp of the first failure in this streak." }),
+	lastFailedAt: Schema.String.annotations({ description: "ISO-8601 timestamp of the most recent failure." }),
+	lastErrorMessage: Schema.NullOr(Schema.String).annotations({ description: "Last error message reported by the failing test, when captured." })
+}).annotations({
+	identifier: "PersistentFailureRow",
+	description: "A test that has failed in every recent run since `firstFailedAt`."
+});
+const RecoveredTestRow = Schema.Struct({
+	fullName: Schema.String,
+	recentRuns: Schema.Array(Schema.Literal("passed", "failed")).annotations({ description: "Last 10 run states for this test, oldest first." })
+}).annotations({
+	identifier: "RecoveredTestRow",
+	description: "A test whose latest run passed after the previous one failed."
+});
+const TestHistoryResult = Schema.Struct({
+	project: Schema.String.annotations({ description: "Workspace project key the history was computed for." }),
+	hasData: Schema.Boolean.annotations({ description: "`false` when no history rows exist for the project — agent should suggest running tests first." }),
+	history: HistoryRecord.annotations({ description: "Raw per-test history record (stored in `test_runs` joins)." }),
+	flaky: Schema.Array(FlakyTestRow).annotations({ description: "Tests with mixed pass/fail outcomes recently." }),
+	persistent: Schema.Array(PersistentFailureRow).annotations({ description: "Tests failing across consecutive runs." }),
+	recovered: Schema.Array(RecoveredTestRow).annotations({ description: "Tests that just transitioned from failing to passing in the last run." })
+}).annotations({
+	identifier: "TestHistoryResult",
+	title: "test_history result",
+	description: "Per-project flaky/persistent/recovered test classifications computed from `test_runs` history."
+});
+const formatTestHistoryMarkdown = (data) => {
+	if (!data.hasData) return `No history data available for project \`${data.project}\`. Run tests first.`;
+	const lines = [`# Test History: ${data.project}`, ""];
+	if (data.flaky.length > 0) {
+		lines.push("## Flaky Tests", "", "Tests with mixed pass/fail results across recent runs:", "");
+		for (const test of data.flaky) {
+			const total = test.passCount + test.failCount;
+			const passRate = total > 0 ? (test.passCount / total * 100).toFixed(0) : "0";
+			lines.push(`### ⚠️ ${test.fullName}`, "", `- Pass rate: ${passRate}% (${test.passCount}/${total})`, `- Last state: ${test.lastState}`, `- Last run: ${new Date(test.lastTimestamp).toLocaleString()}`, "");
+		}
+	}
+	if (data.persistent.length > 0) {
+		lines.push("## Persistent Failures", "", "Tests that have failed in consecutive runs:", "");
+		for (const failure of data.persistent) {
+			lines.push(`### ❌ ${failure.fullName}`, "", `- Consecutive failures: ${failure.consecutiveFailures}`, `- First failed: ${new Date(failure.firstFailedAt).toLocaleString()}`, `- Last failed: ${new Date(failure.lastFailedAt).toLocaleString()}`);
+			if (failure.lastErrorMessage !== null) lines.push(`- Last error: ${failure.lastErrorMessage}`);
+			lines.push("");
+		}
+	}
+	if (data.recovered.length > 0) {
+		lines.push("## Recovered Tests", "", "Tests that previously failed but are now passing:", "");
+		for (const test of data.recovered) {
+			const runViz = test.recentRuns.map((s) => s === "passed" ? "P" : "F").join("");
+			lines.push(`- ✅ **${test.fullName}** — recent runs: \`${runViz}\``);
+		}
+		lines.push("");
+	}
+	if (data.flaky.length === 0 && data.persistent.length === 0 && data.recovered.length === 0) lines.push("✅ No flaky, persistent, or recently recovered tests.", "");
+	lines.push(`_History updated: ${data.history.updatedAt}_`);
+	return lines.join("\n");
+};
+const TestHistoryAsMarkdown = Schema.transformOrFail(TestHistoryResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(formatTestHistoryMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "TestHistoryAsMarkdown is one-way: markdown cannot be parsed back to TestHistoryResult."))
+});
+const testHistory = publicProcedure.input(Schema.standardSchemaV1(Schema.Struct({ project: Schema.String }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	const reader = yield* DataReader;
+	const [history, flaky, persistent] = yield* Effect.all([
+		reader.getHistory(input.project),
+		reader.getFlaky(input.project),
+		reader.getPersistentFailures(input.project)
+	]);
+	const recovered = history.tests.filter((t) => {
+		const runs = t.runs;
+		if (runs.length < 2) return false;
+		const last = runs[runs.length - 1];
+		const prev = runs[runs.length - 2];
+		return last !== void 0 && prev !== void 0 && last.state === "passed" && prev.state === "failed";
+	}).map((t) => ({
+		fullName: t.fullName,
+		recentRuns: t.runs.slice(-10).map((r) => r.state)
+	}));
+	const hasData = history.tests.length > 0 || flaky.length > 0 || persistent.length > 0;
+	return {
+		project: input.project,
+		hasData,
+		history,
+		flaky,
+		persistent,
+		recovered
+	};
+})));
+
+//#endregion
+export { TestHistoryAsMarkdown, TestHistoryResult, testHistory };

package/tools/hypothesis.js

@@ -0,0 +1,127 @@
+import { idempotentProcedure } from "../middleware/idempotency.js";
+import { DataReader, DataStore, DataStoreError } from "@vitest-agent/sdk";
+import { Effect, Match, Option, Schema } from "effect";
+
+//#region src/tools/hypothesis.ts
+/**
+* Consolidated `hypothesis` MCP tool — Schema-driven implementation.
+*
+* `record` and `validate` are mutations whose result is a small
+* structured envelope. `list` now returns a structured array; the
+* boundary in server.ts renders it as markdown via the exported
+* `formatHypothesisListMarkdown` helper.
+*
+* @packageDocumentation
+*/
+const HypothesisRowSchema = Schema.Struct({
+	id: Schema.Number,
+	sessionId: Schema.Number,
+	content: Schema.String.annotations({ description: "Free-text hypothesis the agent recorded before attempting a fix." }),
+	citedTestErrorId: Schema.NullOr(Schema.Number).annotations({ description: "Optional `test_errors.id` the hypothesis cites as the failing observation." }),
+	citedStackFrameId: Schema.NullOr(Schema.Number).annotations({ description: "Optional `stack_frames.id` for the specific frame the hypothesis blames." }),
+	validationOutcome: Schema.NullOr(Schema.Literal("confirmed", "refuted", "abandoned")).annotations({ description: "Outcome recorded by `hypothesis (action: validate)`; `null` while still open." }),
+	validatedAt: Schema.NullOr(Schema.String).annotations({ description: "ISO-8601 validation timestamp; `null` while open." })
+}).annotations({ identifier: "HypothesisRow" });
+const HypothesisRecordOk = Schema.Struct({
+	action: Schema.Literal("record"),
+	id: Schema.Number.annotations({ description: "Newly inserted hypothesis row primary key." })
+});
+const HypothesisValidateOk = Schema.Struct({ action: Schema.Literal("validate") });
+const HypothesisListOk = Schema.Struct({
+	action: Schema.Literal("list"),
+	count: Schema.Number,
+	hypotheses: Schema.Array(HypothesisRowSchema)
+});
+const HypothesisResult = Schema.Union(HypothesisRecordOk, HypothesisValidateOk, HypothesisListOk).annotations({
+	identifier: "HypothesisResult",
+	title: "hypothesis result",
+	description: "Discriminate on `action`. record returns the new id; list returns the matching rows; validate returns an empty acknowledgement."
+});
+const formatHypothesisListMarkdown = (data) => {
+	if (data.action !== "list") return JSON.stringify(data, null, 2);
+	if (data.hypotheses.length === 0) return "No hypotheses matched.";
+	const lines = ["# Hypotheses", ""];
+	for (const h of data.hypotheses) {
+		const status = h.validationOutcome ?? "open";
+		lines.push(`- [${status}] id=${h.id} session=${h.sessionId}: ${h.content.slice(0, 120)}`);
+	}
+	return lines.join("\n");
+};
+const RecordVariant = Schema.Struct({
+	action: Schema.Literal("record"),
+	sessionId: Schema.optional(Schema.Number),
+	content: Schema.String,
+	createdTurnId: Schema.optional(Schema.Number),
+	citedTestErrorId: Schema.optional(Schema.Number),
+	citedStackFrameId: Schema.optional(Schema.Number)
+});
+const ValidateVariant = Schema.Struct({
+	action: Schema.Literal("validate"),
+	id: Schema.Number,
+	outcome: Schema.Literal("confirmed", "refuted", "abandoned"),
+	validatedTurnId: Schema.optional(Schema.Number),
+	validatedAt: Schema.String
+});
+const ListVariant = Schema.Struct({
+	action: Schema.Literal("list"),
+	sessionId: Schema.optional(Schema.Number),
+	outcome: Schema.optional(Schema.Literal("confirmed", "refuted", "abandoned", "open")),
+	limit: Schema.optional(Schema.Number)
+});
+const HypothesisInput = Schema.Union(RecordVariant, ValidateVariant, ListVariant);
+const hypothesis = idempotentProcedure.input(Schema.standardSchemaV1(HypothesisInput)).mutation(async ({ ctx, input }) => {
+	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+		record: (variant) => Effect.gen(function* () {
+			const store = yield* DataStore;
+			const reader = yield* DataReader;
+			const sc = ctx.sessionContext.get();
+			let resolvedSessionId = variant.sessionId;
+			if (sc !== null) {
+				const main = yield* reader.getSessionByChatId(sc.chatId);
+				if (Option.isSome(main)) {
+					const sub = yield* reader.findActiveSubagentSession(main.value.id);
+					resolvedSessionId = Option.isSome(sub) ? sub.value.id : main.value.id;
+				}
+			}
+			if (resolvedSessionId === void 0) return yield* Effect.fail(new DataStoreError({
+				operation: "write",
+				table: "hypotheses",
+				reason: "no recovered session context and no sessionId supplied to attribute hypothesis"
+			}));
+			return {
+				action: "record",
+				id: yield* store.writeHypothesis({
+					sessionId: resolvedSessionId,
+					content: variant.content,
+					...variant.createdTurnId !== void 0 && { createdTurnId: variant.createdTurnId },
+					...variant.citedTestErrorId !== void 0 && { citedTestErrorId: variant.citedTestErrorId },
+					...variant.citedStackFrameId !== void 0 && { citedStackFrameId: variant.citedStackFrameId }
+				})
+			};
+		}),
+		validate: (variant) => Effect.gen(function* () {
+			yield* (yield* DataStore).validateHypothesis({
+				id: variant.id,
+				outcome: variant.outcome,
+				validatedAt: variant.validatedAt,
+				...variant.validatedTurnId !== void 0 && { validatedTurnId: variant.validatedTurnId }
+			});
+			return { action: "validate" };
+		}),
+		list: (variant) => Effect.gen(function* () {
+			const rows = yield* (yield* DataReader).listHypotheses({
+				...variant.sessionId !== void 0 && { sessionId: variant.sessionId },
+				...variant.outcome !== void 0 && { outcome: variant.outcome },
+				...variant.limit !== void 0 && { limit: variant.limit }
+			});
+			return {
+				action: "list",
+				count: rows.length,
+				hypotheses: rows
+			};
+		})
+	})));
+});
+
+//#endregion
+export { HypothesisResult, formatHypothesisListMarkdown, hypothesis };