@vitest-agent/sdk 1.0.0

package/utils/compute-trend.js

@@ -0,0 +1,88 @@
+//#region src/utils/compute-trend.ts
+const STABLE_THRESHOLD = .1;
+const MAX_ENTRIES = 50;
+/**
+* Hash resolved targets to detect configuration changes.
+*
+* Note: JSON.stringify is order-sensitive, but resolveThresholds()
+* always produces keys in METRIC_KEYS iteration order, so the hash
+* is stable for the same logical configuration.
+* @public
+*/
+function hashTargets(targets) {
+	if (!targets) return void 0;
+	return JSON.stringify(targets);
+}
+/**
+* Compute direction from aggregate delta.
+*
+* Threshold is compared against the sum of all four metric deltas, not
+* per-metric. This means the sensitivity is higher when multiple metrics
+* move together vs. a single metric. This is intentional -- aggregate
+* movement is a better signal of overall trajectory.
+*/
+function computeDirection(delta) {
+	const sum = delta.lines + delta.functions + delta.branches + delta.statements;
+	if (sum > STABLE_THRESHOLD) return "improving";
+	if (sum < -.1) return "regressing";
+	return "stable";
+}
+/**
+* Compute a new trend entry and return the updated trend record.
+*
+* If targets have changed (different hash), the trend history is
+* cleared and the new entry becomes the first data point.
+* @public
+*/
+function computeTrend(current, existing, targets) {
+	const currentHash = hashTargets(targets);
+	const entries = existing?.entries ?? [];
+	const baseEntries = entries[entries.length - 1]?.targetsHash !== currentHash ? [] : entries;
+	const previous = baseEntries[baseEntries.length - 1];
+	const delta = previous ? {
+		lines: current.lines - previous.coverage.lines,
+		functions: current.functions - previous.coverage.functions,
+		branches: current.branches - previous.coverage.branches,
+		statements: current.statements - previous.coverage.statements
+	} : {
+		lines: 0,
+		functions: 0,
+		branches: 0,
+		statements: 0
+	};
+	const entry = {
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		coverage: { ...current },
+		delta,
+		direction: computeDirection(delta),
+		...currentHash ? { targetsHash: currentHash } : {}
+	};
+	const newEntries = [...baseEntries, entry];
+	if (newEntries.length > MAX_ENTRIES) newEntries.splice(0, newEntries.length - MAX_ENTRIES);
+	return { entries: newEntries };
+}
+/**
+* Get the overall direction from recent entries.
+* @public
+*/
+function getRecentDirection(record, count = 5) {
+	const entries = record.entries;
+	if (entries.length === 0) return {
+		direction: "stable",
+		runCount: 0
+	};
+	const recent = entries.slice(-count);
+	let improving = 0;
+	let regressing = 0;
+	for (const e of recent) {
+		if (e.direction === "improving") improving++;
+		if (e.direction === "regressing") regressing++;
+	}
+	return {
+		direction: improving > regressing ? "improving" : regressing > improving ? "regressing" : "stable",
+		runCount: recent.length
+	};
+}
+
+//#endregion
+export { computeTrend, getRecentDirection, hashTargets };

package/utils/detect-pm.js

@@ -0,0 +1,58 @@
+//#region src/utils/detect-pm.ts
+const LOCKFILE_MAP = [
+	["pnpm-lock.yaml", "pnpm"],
+	["package-lock.json", "npm"],
+	["yarn.lock", "yarn"],
+	["bun.lock", "bun"]
+];
+const RUN_COMMANDS = {
+	pnpm: "pnpm vitest run",
+	npm: "npx vitest run",
+	yarn: "yarn vitest run",
+	bun: "bun vitest run"
+};
+/**
+* Detect the package manager used in a project by inspecting the root directory.
+*
+* @remarks
+* Detection order:
+* 1. The `packageManager` field in `package.json` (e.g., `"pnpm\@10.32.1"`)
+* 2. Lockfile presence: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lock`
+*
+* Returns `null` when no package manager can be determined.
+*
+* @param root - Absolute path to the project root directory
+* @param fs - Filesystem adapter for reading files and checking existence
+* @returns The detected package manager, or `null`
+*
+* @internal
+*/
+async function detectPackageManager(root, fs) {
+	try {
+		const raw = await fs.readFile(`${root}/package.json`);
+		const pkg = JSON.parse(raw);
+		if (pkg.packageManager) {
+			const name = pkg.packageManager.split("@")[0];
+			if (name in RUN_COMMANDS) return name;
+		}
+	} catch {}
+	for (const [lockfile, pm] of LOCKFILE_MAP) if (await fs.exists(`${root}/${lockfile}`)) return pm;
+	return null;
+}
+/**
+* Return the vitest run command for the given package manager.
+*
+* Falls back to `"npx vitest run"` when `pm` is `null`.
+*
+* @param pm - Detected package manager, or `null` for unknown
+* @returns Shell command string for running vitest
+*
+* @internal
+*/
+function getRunCommand(pm) {
+	if (!pm) return "npx vitest run";
+	return RUN_COMMANDS[pm];
+}
+
+//#endregion
+export { detectPackageManager, getRunCommand };

package/utils/detect-timeout.js

@@ -0,0 +1,17 @@
+//#region src/utils/detect-timeout.ts
+const TIMEOUT_MESSAGE = /\btimed out in \d+\s*ms/i;
+const TIMEOUT_NAME = /timeout/i;
+/**
+* True when the error looks like a Vitest test or hook timeout. Either
+* the message matches "timed out in Nms" or the error name contains
+* "timeout".
+* @public
+*/
+const isTimeoutError = (error) => {
+	if (error.message !== void 0 && TIMEOUT_MESSAGE.test(error.message)) return true;
+	if (error.name !== void 0 && TIMEOUT_NAME.test(error.name)) return true;
+	return false;
+};
+
+//#endregion
+export { isTimeoutError };

package/utils/ensure-migrated.js

@@ -0,0 +1,52 @@
+import { LoggerLive } from "../layers/LoggerLive.js";
+import migration from "../migrations/0001_initial.js";
+import { Effect, Layer } from "effect";
+import { SqlClient } from "@effect/sql/SqlClient";
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import { layer } from "@effect/sql-sqlite-node/SqliteClient";
+import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+
+//#region src/utils/ensure-migrated.ts
+const GLOBAL_KEY = Symbol.for("vitest-agent/migration-promises");
+const getCache = () => {
+	const g = globalThis;
+	let cache = g[GLOBAL_KEY];
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		g[GLOBAL_KEY] = cache;
+	}
+	return cache;
+};
+/**
+* Ensure the SQLite database at `dbPath` is migrated. Runs migrations at
+* most once per dbPath in the current process; concurrent calls share the
+* same in-flight promise. Subsequent calls (after the first resolves) are
+* no-ops.
+* @public
+*/
+function ensureMigrated(dbPath, logLevel, logFile) {
+	const cache = getCache();
+	const cached = cache.get(dbPath);
+	if (cached) return cached;
+	const SqliteLayer = layer({ filename: dbPath });
+	const PlatformLayer = NodeContext.layer;
+	const MigratorLayer = SqliteMigrator.layer({ loader: SqliteMigrator.fromRecord({ "0001_initial": migration }) }).pipe(Layer.provide(Layer.merge(SqliteLayer, PlatformLayer)));
+	const program = Effect.gen(function* () {
+		yield* SqlClient;
+	}).pipe(Effect.provide(MigratorLayer), Effect.provide(Layer.merge(SqliteLayer, PlatformLayer)), Effect.provide(LoggerLive(logLevel, logFile)));
+	const promise = Effect.runPromise(program);
+	cache.set(dbPath, promise);
+	promise.catch(() => {});
+	return promise;
+}
+/**
+* Reset the migration cache. Test-only.
+*
+* @internal
+*/
+function _resetMigrationCacheForTesting() {
+	getCache().clear();
+}
+
+//#endregion
+export { _resetMigrationCacheForTesting, ensureMigrated };

package/utils/failure-signature.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+
+//#region src/utils/failure-signature.ts
+const ASSERTION_REGEX = /(toBe|toEqual|toContain|toMatch|toThrow|toBeNull|toBeUndefined|toBeTruthy|toBeFalsy|toBeGreaterThan|toBeLessThan|toBeInstanceOf|toBeCloseTo|toHaveBeenCalled|toHaveBeenCalledWith|toHaveProperty|toHaveLength)\s*\(([^)]*)\)/;
+const typeTagOf = (literal) => {
+	const trimmed = literal.trim();
+	if (trimmed === "" || trimmed === ")") return "";
+	if (/^\d+(\.\d+)?$/.test(trimmed)) return "<number>";
+	if (/^["'`]/.test(trimmed)) return "<string>";
+	if (/^(true|false)$/.test(trimmed)) return "<boolean>";
+	if (/^null$/.test(trimmed)) return "<null>";
+	if (/^undefined$/.test(trimmed)) return "<undefined>";
+	if (/^[{[]/.test(trimmed)) return "<object>";
+	return "<expr>";
+};
+/** @public */
+const normalizeAssertionShape = (message) => {
+	const match = message.match(ASSERTION_REGEX);
+	if (match === null) return null;
+	const matcher = match[1];
+	const arg = typeTagOf(match[2]);
+	return arg === "" ? matcher : `${matcher}(${arg})`;
+};
+/** @public */
+const computeFailureSignature = (input) => {
+	const shape = normalizeAssertionShape(input.assertion_message) ?? "<unknown>";
+	const lineCoord = input.top_frame_function_boundary_line !== null ? `fb:${input.top_frame_function_boundary_line}` : input.top_frame_raw_line !== void 0 ? `raw:${Math.floor(input.top_frame_raw_line / 10) * 10}` : "raw:?";
+	const key = `${input.error_name}|${shape}|${input.top_frame_function_name}|${lineCoord}`;
+	return createHash("sha256").update(key).digest("hex").substring(0, 16);
+};
+
+//#endregion
+export { computeFailureSignature, normalizeAssertionShape };

package/utils/format-console.js

@@ -0,0 +1,219 @@
+import { ansi } from "./ansi.js";
+
+//#region src/utils/format-console.ts
+/**
+* Return the metric with the lowest percentage from a `FileCoverageReport`.
+*
+* @remarks
+* Used to surface the single worst coverage metric per file in console output,
+* keeping the display compact. Labels are abbreviated: `"Stmts"`, `"Branch"`,
+* `"Funcs"`, `"Lines"`.
+*
+* @param f - File coverage report to analyze
+* @returns Object with `label` and `pct` of the worst metric
+*
+* @internal
+*/
+function getWorstMetric(f) {
+	return [
+		{
+			label: "Stmts",
+			pct: f.summary.statements
+		},
+		{
+			label: "Branch",
+			pct: f.summary.branches
+		},
+		{
+			label: "Funcs",
+			pct: f.summary.functions
+		},
+		{
+			label: "Lines",
+			pct: f.summary.lines
+		}
+	].reduce((worst, m) => m.pct < worst.pct ? m : worst);
+}
+/**
+* Strip the working directory prefix from a file path to produce a
+* project-relative path for display.
+*
+* @param filePath - Absolute or relative file path
+* @param cwd - Working directory to strip; defaults to `process.cwd()`
+* @returns Project-relative path string
+*
+* @internal
+*/
+function relativePath(filePath, cwd) {
+	const root = cwd ?? process.cwd();
+	if (filePath.startsWith(root)) {
+		const rel = filePath.slice(root.length);
+		return rel.startsWith("/") ? rel.slice(1) : rel;
+	}
+	return filePath;
+}
+/**
+* Determine the output tier based on test results and coverage state.
+*
+* - `"red"` -- failures, unhandled errors, or files below threshold
+* - `"yellow"` -- all tests pass but coverage targets exist (room to improve)
+* - `"green"` -- all tests pass, all coverage targets met
+*
+* @internal
+*/
+function determineTier(report) {
+	if (report.summary.failed > 0 || report.unhandledErrors.length > 0) return "red";
+	if (report.coverage) {
+		if (report.coverage.lowCoverage.length > 0) return "red";
+		if (report.coverage.targets && report.coverage.belowTarget && report.coverage.belowTarget.length > 0) return "yellow";
+	}
+	return "green";
+}
+/**
+* Format an {@link (AgentReport:variable)} as compact, actionable console markdown.
+*
+* @remarks
+* The output is structured for LLM agent consumption with four sections:
+*
+* 1. **Compact header** with pass/fail counts and duration
+* 2. **Failed test details** with error messages and diffs (the core value)
+* 3. **Coverage gaps** showing only files below threshold, worst metric first
+* 4. **Next steps** with re-run commands and cache file pointer
+*
+* When all tests pass, the output collapses to a single success line
+* with an optional cache file reference.
+*
+* Returns an empty string when `consoleOutput` is `"silent"`.
+*
+* @param report - The report to format
+* @param options - Formatting options controlling verbosity and color
+* @returns Formatted markdown string, or empty string for silent mode
+*
+* @internal
+*/
+function formatConsoleMarkdown(report, options) {
+	const { consoleOutput, coverageConsoleLimit, noColor } = options;
+	if (consoleOutput === "silent") return "";
+	const ao = { noColor };
+	const lines = [];
+	const hasFailures = report.summary.failed > 0;
+	const duration = Math.round(report.summary.duration);
+	const projectLabel = report.project ? ` (${report.project})` : "";
+	if (hasFailures) lines.push(`## ${ansi("✗", "red", ao)} Vitest${projectLabel} \u2014 ${report.summary.failed} failed, ${report.summary.passed} passed (${duration}ms)`);
+	else lines.push(`## ${ansi("✓", "green", ao)} Vitest${projectLabel} \u2014 ${report.summary.passed} passed (${duration}ms)`);
+	lines.push("");
+	if (options.trendSummary && report.coverage) {
+		const { direction, runCount, firstMetric } = options.trendSummary;
+		const tier = determineTier(report);
+		if (tier === "green") {
+			const trendNote = `Coverage: all targets met | trending ${direction} over ${runCount} runs`;
+			lines[0] = `${lines[0]} — ${trendNote}`;
+		} else if (tier === "yellow") {
+			const belowTargetCount = report.coverage.belowTarget?.length ?? 0;
+			let summary = `Coverage: ${belowTargetCount} file${belowTargetCount !== 1 ? "s" : ""} below target`;
+			summary += ` | trending ${direction} over ${runCount} runs`;
+			if (firstMetric) {
+				summary += ` (${firstMetric.name}: ${firstMetric.from}% -> ${firstMetric.to}%`;
+				if (firstMetric.target) summary += `, target: ${firstMetric.target}%`;
+				summary += ")";
+			}
+			lines.push(summary);
+			lines.push("");
+		} else {
+			let summary = "Coverage:";
+			if (report.coverage.lowCoverage.length > 0) summary += ` ${report.coverage.lowCoverage.length} file${report.coverage.lowCoverage.length !== 1 ? "s" : ""} below threshold`;
+			summary += ` | trending ${direction} over ${runCount} runs`;
+			if (firstMetric) summary += ` (${firstMetric.name}: ${firstMetric.from}% -> ${firstMetric.to}%)`;
+			lines.push(summary);
+			lines.push("");
+		}
+	}
+	if (hasFailures) for (const mod of report.failed) {
+		const file = relativePath(mod.file);
+		lines.push(`### ${ansi("✗", "red", ao)} \`${file}\``);
+		lines.push("");
+		if (mod.errors && mod.errors.length > 0) for (const err of mod.errors) {
+			lines.push(ansi(err.message, "red", ao));
+			if (err.diff) {
+				lines.push("");
+				lines.push("```diff");
+				lines.push(err.diff);
+				lines.push("```");
+			}
+			lines.push("");
+		}
+		const failedTests = mod.tests.filter((t) => t.state === "failed");
+		for (const test of failedTests) {
+			const label = test.classification ? ` [${test.classification}]` : "";
+			lines.push(`- ${ansi("✗", "red", ao)} **${test.fullName}**${label}`);
+			if (test.errors && test.errors.length > 0) for (const err of test.errors) {
+				lines.push(`  ${ansi(err.message, "dim", ao)}`);
+				if (err.diff) {
+					lines.push("");
+					lines.push("  ```diff");
+					for (const diffLine of err.diff.split("\n")) lines.push(`  ${diffLine}`);
+					lines.push("  ```");
+				}
+			}
+			lines.push("");
+		}
+	}
+	if (report.coverage) {
+		const cov = report.coverage;
+		const globalThresholds = cov.thresholds.global;
+		const filesToShow = cov.lowCoverage.slice(0, coverageConsoleLimit);
+		if (filesToShow.length > 0) {
+			lines.push(`### Coverage gaps`);
+			lines.push("");
+			for (const f of filesToShow) {
+				const file = relativePath(f.file);
+				const worst = getWorstMetric(f);
+				const thresholdValue = globalThresholds[worst.label === "Stmts" ? "statements" : worst.label === "Branch" ? "branches" : worst.label === "Funcs" ? "functions" : "lines"];
+				const thresholdSuffix = thresholdValue != null ? ` (threshold: ${thresholdValue}%)` : "";
+				lines.push(`- \`${file}\` \u2014 ${worst.label}: ${worst.pct}%${thresholdSuffix} \u2014 uncovered: ${f.uncoveredLines}`);
+			}
+			lines.push("");
+		}
+		if (cov.targets && cov.belowTarget && cov.belowTarget.length > 0) {
+			lines.push(`### Coverage improvements needed`);
+			lines.push("");
+			for (const f of cov.belowTarget.slice(0, coverageConsoleLimit)) {
+				const file = relativePath(f.file);
+				const worst = getWorstMetric(f);
+				const metricKey = worst.label === "Stmts" ? "statements" : worst.label === "Branch" ? "branches" : worst.label === "Funcs" ? "functions" : "lines";
+				const targetValue = cov.targets.global[metricKey];
+				const targetSuffix = targetValue != null ? ` (target: ${targetValue}%)` : "";
+				lines.push(`- \`${file}\` \u2014 ${worst.label}: ${worst.pct}%${targetSuffix} \u2014 uncovered: ${f.uncoveredLines}`);
+			}
+			lines.push("");
+		}
+	}
+	if (hasFailures || report.coverage && report.coverage.lowCoverage.length > 0) {
+		lines.push("### Next steps");
+		lines.push("");
+		if (hasFailures) {
+			const allFailedTests = report.failed.flatMap((m) => m.tests.filter((t) => t.state === "failed"));
+			const newFailures = allFailedTests.filter((t) => t.classification === "new-failure");
+			const persistent = allFailedTests.filter((t) => t.classification === "persistent");
+			const flaky = allFailedTests.filter((t) => t.classification === "flaky");
+			if (newFailures.length > 0) {
+				const files = [...new Set(report.failed.filter((m) => m.tests.some((t) => t.classification === "new-failure")).map((m) => relativePath(m.file)))];
+				lines.push(`- Fix ${newFailures.length} new failure${newFailures.length > 1 ? "s" : ""} in ${files.map((f) => `\`${f}\``).join(", ")} (likely caused by recent changes)`);
+			}
+			if (persistent.length > 0) lines.push(`- ${persistent.length} persistent failure${persistent.length > 1 ? "s" : ""} (pre-existing, may not be yours)`);
+			if (flaky.length > 0) lines.push(`- ${flaky.length} flaky test${flaky.length > 1 ? "s" : ""} (may pass on retry)`);
+			for (const file of report.failedFiles) lines.push(`- Re-run: \`vitest run ${relativePath(file)}\``);
+			if (options.mcp) {
+				lines.push("- Use `test_history` for failure trends");
+				lines.push("- Use `test_errors` to search errors by type");
+				lines.push("- Use `test_coverage` for coverage gap analysis");
+				lines.push("- Use `note({ action: \"create\" })` to record debugging findings");
+			}
+		}
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { determineTier, formatConsoleMarkdown, getWorstMetric, relativePath };

package/utils/format-fatal-error.js

@@ -0,0 +1,35 @@
+import { Cause } from "effect";
+
+//#region src/utils/format-fatal-error.ts
+const ISSUE_URL = "https://github.com/spencerbeggs/vitest-agent/issues";
+const FIBER_FAILURE_CAUSE_KEY = Symbol.for("effect/Runtime/FiberFailure/Cause");
+/**
+* Format an unknown error into a human-readable string with issue URL.
+*
+* Extraction order:
+* 1. Effect Cause — use `Cause.pretty()` for full formatting
+* 2. Effect FiberFailure — extract Cause and use `Cause.pretty()`
+* 3. Plain Error — extract `.message` and `.stack`
+* 4. Unknown — `String(err)`
+*
+* @public
+*/
+function formatFatalError(err) {
+	let detail;
+	if (Cause.isCause(err)) detail = Cause.pretty(err);
+	else if (err != null && typeof err === "object" && FIBER_FAILURE_CAUSE_KEY in err) {
+		const cause = err[FIBER_FAILURE_CAUSE_KEY];
+		if (Cause.isCause(cause)) detail = Cause.pretty(cause);
+		else detail = String(err);
+	} else if (err instanceof Error) detail = err.stack ?? err.message;
+	else if (err !== null && typeof err === "object") try {
+		detail = JSON.stringify(err, null, 2);
+	} catch {
+		detail = String(err);
+	}
+	else detail = String(err);
+	return `${detail}\nPlease report at ${ISSUE_URL}`;
+}
+
+//#endregion
+export { formatFatalError };

package/utils/format-gfm.js

@@ -0,0 +1,161 @@
+//#region src/utils/format-gfm.ts
+/**
+* Format a number as a percentage string.
+*
+* @internal
+*/
+function pct(n) {
+	return `${n}%`;
+}
+/**
+* Find the worst (lowest) coverage metric for a file.
+*
+* @internal
+*/
+function worstCoverage(f) {
+	return [
+		{
+			label: "Stmts",
+			pct: f.summary.statements
+		},
+		{
+			label: "Branch",
+			pct: f.summary.branches
+		},
+		{
+			label: "Funcs",
+			pct: f.summary.functions
+		},
+		{
+			label: "Lines",
+			pct: f.summary.lines
+		}
+	].reduce((worst, m) => m.pct < worst.pct ? m : worst);
+}
+/**
+* Format the body of a single project's GFM output.
+*
+* @internal
+*/
+function formatProjectBody(report) {
+	const lines = [];
+	if (report.failed.length > 0) {
+		lines.push("## Failed Tests");
+		lines.push("");
+		for (const mod of report.failed) {
+			lines.push(`### \`${mod.file}\``);
+			lines.push("");
+			if (mod.errors && mod.errors.length > 0) for (const err of mod.errors) {
+				lines.push(`> ${err.message}`);
+				if (err.diff) {
+					lines.push("");
+					lines.push("```diff");
+					lines.push(err.diff);
+					lines.push("```");
+				}
+				lines.push("");
+			}
+			const failedTests = mod.tests.filter((t) => t.state === "failed");
+			for (const test of failedTests) {
+				lines.push(`**${test.fullName}**`);
+				lines.push("");
+				if (test.errors && test.errors.length > 0) for (const err of test.errors) {
+					lines.push(`> ${err.message}`);
+					if (err.diff) {
+						lines.push("");
+						lines.push("```diff");
+						lines.push(err.diff);
+						lines.push("```");
+					}
+				}
+				lines.push("");
+			}
+		}
+	}
+	if (report.coverage) {
+		const cov = report.coverage;
+		lines.push("## Coverage");
+		lines.push("");
+		lines.push("| Metric | Coverage |");
+		lines.push("| --- | --- |");
+		lines.push(`| Statements | ${pct(cov.totals.statements)} |`);
+		lines.push(`| Branches | ${pct(cov.totals.branches)} |`);
+		lines.push(`| Functions | ${pct(cov.totals.functions)} |`);
+		lines.push(`| Lines | ${pct(cov.totals.lines)} |`);
+		lines.push("");
+		if (cov.lowCoverage.length > 0) {
+			const thresholdParts = [];
+			const g = cov.thresholds.global;
+			if (g.lines !== void 0) thresholdParts.push(`lines: ${g.lines}%`);
+			if (g.functions !== void 0) thresholdParts.push(`functions: ${g.functions}%`);
+			if (g.branches !== void 0) thresholdParts.push(`branches: ${g.branches}%`);
+			if (g.statements !== void 0) thresholdParts.push(`statements: ${g.statements}%`);
+			const thresholdDisplay = thresholdParts.length > 0 ? thresholdParts.join(", ") : "configured thresholds";
+			lines.push("> [!WARNING]");
+			lines.push(`> ${cov.lowCoverage.length} file(s) below coverage threshold (${thresholdDisplay}):`);
+			lines.push(">");
+			for (const f of cov.lowCoverage) {
+				const worst = worstCoverage(f);
+				lines.push(`> - \`${f.file}\` — ${worst.label} ${pct(worst.pct)}`);
+			}
+			lines.push("");
+		}
+	}
+	return lines;
+}
+/**
+* Format one or more {@link (AgentReport:variable) | AgentReports} as a GitHub-Flavored
+* Markdown string for writing to `GITHUB_STEP_SUMMARY`.
+*
+* @remarks
+* GFM-specific features used in the output:
+*
+* - **Summary table** with pass/fail counts across all projects
+* - **Collapsible `<details>` blocks** for per-project results in monorepo setups
+* - **Tables** for coverage metrics
+* - **Diff-fenced code blocks** for expected/received comparison output
+* - **GitHub Alert callouts** (`[!WARNING]`) for coverage threshold violations
+*
+* For a single report, the project body is rendered directly without
+* a `<details>` wrapper. For multiple reports (monorepo), each project
+* gets its own collapsible section with a status icon in the summary line.
+*
+* @param reports - One or more agent reports to format
+* @returns GFM-formatted string ready for appending to `GITHUB_STEP_SUMMARY`
+*
+* @public
+*/
+function formatGfm(reports) {
+	const lines = [];
+	const headerIcon = reports.some((r) => r.summary.failed > 0) ? "❌" : "✅";
+	lines.push(`# ${headerIcon} Vitest Results`);
+	lines.push("");
+	const totalPassed = reports.reduce((acc, r) => acc + r.summary.passed, 0);
+	const totalFailed = reports.reduce((acc, r) => acc + r.summary.failed, 0);
+	const totalTests = reports.reduce((acc, r) => acc + r.summary.total, 0);
+	lines.push("| | Count |");
+	lines.push("| --- | --- |");
+	lines.push(`| Passed | **${totalPassed}** |`);
+	lines.push(`| Failed | **${totalFailed}** |`);
+	lines.push(`| Total | **${totalTests}** |`);
+	lines.push("");
+	if (reports.length > 1) for (const report of reports) {
+		const projectLabel = report.project ?? "default";
+		const statusIcon = report.summary.failed > 0 ? "❌" : "✅";
+		lines.push(`<details>`);
+		lines.push(`<summary>${statusIcon} ${projectLabel}</summary>`);
+		lines.push("");
+		const bodyLines = formatProjectBody(report);
+		lines.push(...bodyLines);
+		lines.push("</details>");
+		lines.push("");
+	}
+	else if (reports.length === 1) {
+		const bodyLines = formatProjectBody(reports[0]);
+		lines.push(...bodyLines);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { formatGfm };