@vitest-agent/sdk 1.0.0

package/utils/format-terminal.js

@@ -0,0 +1,480 @@
+import { ansi } from "./ansi.js";
+import { relativePath } from "./format-console.js";
+import { compressLines } from "./compress-lines.js";
+
+//#region src/utils/format-terminal.ts
+/**
+* Compress a comma-separated line list into ranges where consecutive
+* numbers run together. Defensive: callers may pass already-compressed
+* strings (e.g. "29-32, 34-38") or uncompressed (e.g. "29,30,31,32") —
+* both are handled. If parsing fails, the original string is returned
+* unchanged.
+*
+* @internal
+*/
+const compressUncov = (uncoveredLines) => {
+	if (uncoveredLines.length === 0) return "";
+	if (uncoveredLines.includes("-")) return uncoveredLines;
+	const numbers = [];
+	for (const piece of uncoveredLines.split(",")) {
+		const n = Number.parseInt(piece.trim(), 10);
+		if (Number.isNaN(n)) return uncoveredLines;
+		numbers.push(n);
+	}
+	return compressLines(numbers);
+};
+const METRICS = [
+	{
+		key: "lines",
+		label: "lines"
+	},
+	{
+		key: "branches",
+		label: "branches"
+	},
+	{
+		key: "functions",
+		label: "funcs"
+	},
+	{
+		key: "statements",
+		label: "stmts"
+	}
+];
+/**
+* Format a duration in milliseconds as a short human string.
+*
+* Sub-second durations stay in ms (`"328ms"`); 1s and longer switch to
+* seconds with one decimal (`"5.6s"`). Avoids the noise of "5577ms" in
+* summary rows where second-level precision is plenty.
+*
+* @internal
+*/
+const formatDuration = (ms) => {
+	if (ms < 1e3) return `${Math.round(ms)}ms`;
+	return `${(ms / 1e3).toFixed(1)}s`;
+};
+/**
+* Decide whether the project label should appear in the row.
+*
+* Single-project setups with no explicit `project.name` (Vitest's
+* default) have `project` set to `"default"`. In that case there's
+* nothing to disambiguate; suppress the label.
+*
+* @internal
+*/
+const showProjectLabel = (reports) => {
+	if (reports.length > 1) return true;
+	const single = reports[0];
+	if (!single?.project) return false;
+	if (single.project === "default") return false;
+	return true;
+};
+/**
+* Right-pad a column value to a fixed width with spaces. Plain ASCII
+* width — does not account for ANSI escapes (caller is responsible).
+*
+* @internal
+*/
+const pad = (s, width) => s.length >= width ? s : s + " ".repeat(width - s.length);
+/**
+* Build an inline tag-count summary suffix for a project row.
+* Only shown when two or more distinct tag kinds are present.
+*
+* @internal
+*/
+const buildTagSummary = (tagCounts) => {
+	if (!tagCounts) return "";
+	const keys = Object.keys(tagCounts).sort();
+	if (keys.length < 2) return "";
+	return "  " + keys.map((k) => {
+		const c = tagCounts[k];
+		return `${k}:${(c?.passed ?? 0) + (c?.failed ?? 0) + (c?.skipped ?? 0)}`;
+	}).join("  ");
+};
+/**
+* Render indented per-tag pass/fail breakdown rows for a project that has failures.
+* The `s` (skipped) column only appears when skipped \> 0 for that tag.
+*
+* @internal
+*/
+const renderTagFailureBreakdown = (tagCounts) => {
+	const lines = [];
+	const keys = Object.keys(tagCounts).sort();
+	if (keys.length === 0) return lines;
+	const tagWidth = Math.max(...keys.map((k) => k.length));
+	for (const k of keys) {
+		const c = tagCounts[k];
+		const p = c?.passed ?? 0;
+		const f = c?.failed ?? 0;
+		const s = c?.skipped ?? 0;
+		const skipPart = s > 0 ? `  ${s}s` : "";
+		lines.push(`      ${k.padEnd(tagWidth)}  ${p}p  ${f}f${skipPart}`);
+	}
+	return lines;
+};
+/**
+* Project row: `✓ name      103 passed (2.1s)` or
+* `✗ name      102 passed, 1 failed (2.1s)`.
+*
+* @internal
+*/
+const renderProjectRow = (report, ao, nameWidth) => {
+	const failed = report.summary.failed;
+	const passed = report.summary.passed;
+	const skipped = report.summary.skipped;
+	const duration = formatDuration(report.summary.duration);
+	const name = report.project ?? "default";
+	const tick = failed === 0 ? ansi("✓", "green", ao) : ansi("✗", "red", ao);
+	const counts = [];
+	if (failed > 0) counts.push(`${failed} failed`);
+	counts.push(`${passed} passed`);
+	if (skipped > 0) counts.push(`${skipped} skipped`);
+	return `${`  ${tick} ${pad(name, nameWidth)}  ${counts.join(", ")} (${duration})`}${buildTagSummary(report.tagCounts)}`;
+};
+/**
+* Format the global target spec compactly.
+*
+* If every metric has the same target (the common case), collapse to
+* `≥ 80% lines, branches, funcs, stmts`. If targets differ, list per
+* metric: `lines ≥ 80%, branches ≥ 75%, funcs ≥ 70%, stmts ≥ 80%`.
+*
+* @internal
+*/
+const formatTargetSpec = (targets) => {
+	const set = /* @__PURE__ */ new Set();
+	const present = [];
+	for (const m of METRICS) {
+		const v = targets[m.key];
+		if (v == null) continue;
+		set.add(v);
+		present.push({
+			label: m.label,
+			v
+		});
+	}
+	if (present.length === 0) return "";
+	if (set.size === 1) {
+		const v = [...set][0];
+		return `${present.map((p) => p.label).join(", ")} ≥ ${v}%`;
+	}
+	return present.map((p) => `${p.label} ≥ ${p.v}%`).join(", ");
+};
+/**
+* Header labels for the v8-style coverage table. The order is fixed
+* and matches the column order rendered by {@link renderBelowTargetTable}.
+*
+* @internal
+*/
+const TABLE_HEADERS = {
+	file: "File",
+	stmts: "% Stmts",
+	branches: "% Branch",
+	funcs: "% Funcs",
+	lines: "% Lines",
+	uncov: "Uncovered Line #s"
+};
+/**
+* Pad a cell with one space on each side of its content. Numeric
+* cells are right-aligned, string cells are left-aligned. The width
+* argument is the inner content width (without the padding spaces).
+*
+* @internal
+*/
+const cell = (s, width, align) => {
+	return ` ${align === "right" ? s.padStart(width) : s.padEnd(width)} `;
+};
+/**
+* Render a separator row matching the column geometry of the header.
+* Width per column = inner width + 2 (the padding spaces) so the row
+* lines up with the headers and data rows when joined by `|`.
+*
+* @internal
+*/
+const sepRow = (widths) => widths.map((w) => "-".repeat(w + 2)).join("|");
+/**
+* v8-style coverage table for files below aspirational targets.
+*
+* Columns: File, % Stmts, % Branch, % Funcs, % Lines, Uncovered
+* Line #s. Numeric columns are right-aligned and show the file's
+* actual coverage value (no `%` suffix — the header carries it).
+* Showing every metric per row, not just the below-target ones,
+* matches v8's reporter and gives an LLM agent a complete picture
+* of where the file stands relative to all four metrics.
+*
+* Returns header rows + data rows + a trailing separator. The caller
+* is responsible for the surrounding caption and any truncation
+* footer.
+*
+* @internal
+*/
+const renderBelowTargetTable = (files) => {
+	if (files.length === 0) return [];
+	const rows = files.map((f) => ({
+		file: relativePath(f.file),
+		stmts: String(Math.round(f.summary.statements)),
+		branches: String(Math.round(f.summary.branches)),
+		funcs: String(Math.round(f.summary.functions)),
+		lines: String(Math.round(f.summary.lines)),
+		uncov: compressUncov(f.uncoveredLines)
+	}));
+	const widths = [
+		Math.max(TABLE_HEADERS.file.length, ...rows.map((r) => r.file.length)),
+		Math.max(TABLE_HEADERS.stmts.length, ...rows.map((r) => r.stmts.length)),
+		Math.max(TABLE_HEADERS.branches.length, ...rows.map((r) => r.branches.length)),
+		Math.max(TABLE_HEADERS.funcs.length, ...rows.map((r) => r.funcs.length)),
+		Math.max(TABLE_HEADERS.lines.length, ...rows.map((r) => r.lines.length)),
+		Math.max(TABLE_HEADERS.uncov.length, ...rows.map((r) => r.uncov.length))
+	];
+	const out = [];
+	out.push(sepRow(widths));
+	out.push([
+		cell(TABLE_HEADERS.file, widths[0], "left"),
+		cell(TABLE_HEADERS.stmts, widths[1], "right"),
+		cell(TABLE_HEADERS.branches, widths[2], "right"),
+		cell(TABLE_HEADERS.funcs, widths[3], "right"),
+		cell(TABLE_HEADERS.lines, widths[4], "right"),
+		cell(TABLE_HEADERS.uncov, widths[5], "left")
+	].join("|"));
+	out.push(sepRow(widths));
+	for (const r of rows) out.push([
+		cell(r.file, widths[0], "left"),
+		cell(r.stmts, widths[1], "right"),
+		cell(r.branches, widths[2], "right"),
+		cell(r.funcs, widths[3], "right"),
+		cell(r.lines, widths[4], "right"),
+		cell(r.uncov, widths[5], "left")
+	].join("|"));
+	out.push(sepRow(widths));
+	return out;
+};
+/**
+* Aggregated coverage state across reports.
+*
+* @internal
+*/
+const aggregateCoverage = (reports) => {
+	let hasCoverage = false;
+	let thresholdsGlobal;
+	let targetsGlobal;
+	const belowTargetByFile = /* @__PURE__ */ new Map();
+	const belowThresholdByFile = /* @__PURE__ */ new Map();
+	for (const r of reports) {
+		const cov = r.coverage;
+		if (!cov) continue;
+		hasCoverage = true;
+		thresholdsGlobal ??= cov.thresholds.global;
+		targetsGlobal ??= cov.targets?.global;
+		if (cov.lowCoverage) {
+			for (const f of cov.lowCoverage) if (!belowThresholdByFile.has(f.file)) belowThresholdByFile.set(f.file, f);
+		}
+		if (cov.belowTarget) {
+			for (const f of cov.belowTarget) if (!belowTargetByFile.has(f.file)) belowTargetByFile.set(f.file, f);
+		}
+	}
+	const belowTargetFiles = [...belowTargetByFile.values()];
+	const belowThresholdCount = belowThresholdByFile.size;
+	return {
+		hasCoverage,
+		thresholdsMet: belowThresholdCount === 0,
+		belowThresholdCount,
+		belowTargetFiles,
+		...thresholdsGlobal !== void 0 ? { thresholdsGlobal } : {},
+		...targetsGlobal !== void 0 ? { targetsGlobal } : {}
+	};
+};
+/**
+* Coverage section: one or two summary lines plus per-file rows.
+*
+* @internal
+*/
+const renderCoverageSection = (reports, options, ao) => {
+	const agg = aggregateCoverage(reports);
+	if (!agg.hasCoverage) return [];
+	const lines = [];
+	const thresholdSpec = agg.thresholdsGlobal ? formatTargetSpec(agg.thresholdsGlobal) : "";
+	const targetSpec = agg.targetsGlobal ? formatTargetSpec(agg.targetsGlobal) : "";
+	if (!agg.thresholdsMet) {
+		const cross = ansi("✗", "red", ao);
+		const fileWord = agg.belowThresholdCount === 1 ? "file" : "files";
+		lines.push(`Coverage: ${cross} ${agg.belowThresholdCount} ${fileWord} below minimum thresholds${thresholdSpec ? ` (${thresholdSpec})` : ""}`);
+	} else if (agg.belowTargetFiles.length > 0) {
+		const tick = ansi("✓", "green", ao);
+		const warn = ansi("⚠", "yellow", ao);
+		const fileWord = agg.belowTargetFiles.length === 1 ? "file" : "files";
+		lines.push(`Coverage: ${tick} minimum thresholds met${thresholdSpec ? ` (${thresholdSpec})` : ""}`);
+		lines.push(`Coverage: ${warn} ${agg.belowTargetFiles.length} ${fileWord} below aspirational targets${targetSpec ? ` (${targetSpec})` : ""}`);
+	} else {
+		const tick = ansi("✓", "green", ao);
+		if (agg.targetsGlobal) lines.push(`Coverage: ${tick} minimum thresholds + aspirational targets met${targetSpec ? ` (${targetSpec})` : ""}`);
+		else lines.push(`Coverage: ${tick} minimum thresholds met${thresholdSpec ? ` (${thresholdSpec})` : ""}`);
+	}
+	if (options.trendSummary) {
+		const { direction, runCount } = options.trendSummary;
+		lines.push(`Trend: ${direction} (${runCount} runs)`);
+	}
+	if (agg.belowTargetFiles.length > 0 && agg.targetsGlobal) {
+		lines.push("");
+		lines.push("Files below aspirational target:");
+		const limit = options.coverageConsoleLimit;
+		const shown = agg.belowTargetFiles.slice(0, limit);
+		lines.push(...renderBelowTargetTable(shown));
+		if (agg.belowTargetFiles.length > limit) lines.push(`… ${agg.belowTargetFiles.length - limit} more (use the test_coverage MCP tool for the full list)`);
+	}
+	return lines;
+};
+/**
+* Failures block: grouped by project, one entry per failed test with
+* inline error message and stack hint.
+*
+* @internal
+*/
+const renderFailuresSection = (reports, ao) => {
+	const lines = [];
+	const reportsWithFailures = reports.filter((r) => r.summary.failed > 0 || r.unhandledErrors.length > 0);
+	if (reportsWithFailures.length === 0) return lines;
+	lines.push("Failures:");
+	for (const report of reportsWithFailures) {
+		const projectName = report.project ?? "default";
+		lines.push(`  ${projectName}`);
+		for (const mod of report.failed) {
+			const file = relativePath(mod.file);
+			const failedTests = mod.tests.filter((t) => t.state === "failed");
+			for (const test of failedTests) lines.push(...renderFailedTest(file, test, ao));
+			if (mod.errors && mod.errors.length > 0) for (const err of mod.errors) {
+				lines.push(`    ${ansi("✗", "red", ao)} ${file} (module-level error)`);
+				lines.push(`        ${ansi(err.message, "red", ao)}`);
+			}
+		}
+		for (const err of report.unhandledErrors) {
+			lines.push(`    ${ansi("✗", "red", ao)} unhandled error`);
+			lines.push(`        ${ansi(err.message, "red", ao)}`);
+		}
+	}
+	return lines;
+};
+const renderFailedTest = (file, test, ao) => {
+	const cross = ansi("✗", "red", ao);
+	const cls = test.classification ? ansi(`  [${test.classification}]`, "dim", ao) : "";
+	const lines = [`    ${cross} ${file} > ${test.fullName}${cls}`];
+	if (test.errors && test.errors.length > 0) for (const err of test.errors) lines.push(`        ${ansi(err.message, "dim", ao)}`);
+	return lines;
+};
+/**
+* Total line: aggregated pass/fail/skip counts + max-project duration.
+*
+* @internal
+*/
+const renderTotal = (reports, ao) => {
+	let passed = 0;
+	let failed = 0;
+	let skipped = 0;
+	let maxDuration = 0;
+	for (const r of reports) {
+		passed += r.summary.passed;
+		failed += r.summary.failed;
+		skipped += r.summary.skipped;
+		if (r.summary.duration > maxDuration) maxDuration = r.summary.duration;
+	}
+	const parts = [];
+	if (failed > 0) parts.push(ansi(`${failed} failed`, "red", ao));
+	parts.push(`${passed} passed`);
+	if (skipped > 0) parts.push(`${skipped} skipped`);
+	return `Total: ${parts.join(", ")} (${formatDuration(maxDuration)})`;
+};
+/**
+* Re-run hints when failures exist.
+*
+* @internal
+*/
+const renderNextSteps = (reports, options) => {
+	const lines = [];
+	const allFailedFiles = /* @__PURE__ */ new Set();
+	for (const r of reports) for (const f of r.failedFiles) allFailedFiles.add(relativePath(f));
+	if (allFailedFiles.size === 0) return lines;
+	lines.push("Next steps:");
+	for (const file of allFailedFiles) lines.push(`  Re-run: pnpm vitest run ${file}`);
+	if (options.mcp) {
+		lines.push("  Use the test_history MCP tool to check failure trends");
+		lines.push("  Use the test_errors MCP tool to search errors by type");
+	}
+	return lines;
+};
+/**
+* Header line for multi-project runs.
+*
+* @internal
+*/
+const renderHeader = (reports) => {
+	const lines = [];
+	if (showProjectLabel(reports) && reports.length > 1) lines.push(`Projects (${reports.length}):`);
+	else if (showProjectLabel(reports) && reports.length === 1) lines.push(`Project: ${reports[0]?.project ?? "default"}`);
+	return lines;
+};
+/**
+* Public entry point: render a collection of `AgentReport` rows as
+* a single plain-text block for stdout.
+*
+* @public
+*/
+const formatTerminal = (reports, options) => {
+	if (reports.length === 0) return "";
+	const ao = { noColor: options.noColor };
+	const out = [];
+	const header = renderHeader(reports);
+	if (header.length > 0) out.push(...header);
+	if (reports.length > 1) {
+		const widths = reports.map((r) => (r.project ?? "default").length);
+		const nameWidth = Math.max(0, ...widths);
+		for (const r of reports) {
+			out.push(renderProjectRow(r, ao, nameWidth));
+			if (r.summary.failed > 0 && r.tagCounts) out.push(...renderTagFailureBreakdown(r.tagCounts));
+		}
+		out.push("");
+	} else if (showProjectLabel(reports)) {
+		const r = reports[0];
+		if (r) {
+			const tick = r.summary.failed === 0 ? ansi("✓", "green", ao) : ansi("✗", "red", ao);
+			const counts = [];
+			if (r.summary.failed > 0) counts.push(`${r.summary.failed} failed`);
+			counts.push(`${r.summary.passed} passed`);
+			if (r.summary.skipped > 0) counts.push(`${r.summary.skipped} skipped`);
+			const baseRow = `${tick} ${counts.join(", ")} (${formatDuration(r.summary.duration)})`;
+			const tagSummary = buildTagSummary(r.tagCounts);
+			out.push(`${baseRow}${tagSummary}`);
+			if (r.summary.failed > 0 && r.tagCounts) out.push(...renderTagFailureBreakdown(r.tagCounts));
+			out.push("");
+		}
+	} else if (reports.length === 1) {
+		const r = reports[0];
+		if (r) {
+			const tick = r.summary.failed === 0 ? ansi("✓", "green", ao) : ansi("✗", "red", ao);
+			const counts = [];
+			if (r.summary.failed > 0) counts.push(`${r.summary.failed} failed`);
+			counts.push(`${r.summary.passed} passed`);
+			if (r.summary.skipped > 0) counts.push(`${r.summary.skipped} skipped`);
+			out.push(`${tick} ${counts.join(", ")} (${formatDuration(r.summary.duration)})`);
+			out.push("");
+		}
+	}
+	const failures = renderFailuresSection(reports, ao);
+	if (failures.length > 0) {
+		out.push(...failures);
+		out.push("");
+	}
+	const coverage = renderCoverageSection(reports, options, ao);
+	if (coverage.length > 0) {
+		out.push(...coverage);
+		out.push("");
+	}
+	out.push(renderTotal(reports, ao));
+	const nextSteps = renderNextSteps(reports, options);
+	if (nextSteps.length > 0) {
+		out.push("");
+		out.push(...nextSteps);
+	}
+	return out.join("\n");
+};
+
+//#endregion
+export { formatTerminal };

package/utils/function-boundary.js

@@ -0,0 +1,75 @@
+import * as acorn from "acorn";
+import { tsPlugin } from "acorn-typescript";
+
+//#region src/utils/function-boundary.ts
+const Parser = acorn.Parser.extend(tsPlugin());
+const isFunctionLike = (node) => node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+const containsLine = (node, line) => node.loc !== void 0 && node.loc.start.line <= line && node.loc.end.line >= line;
+const nodeName = (node, parent) => {
+	if (node.id !== null && node.id !== void 0) return node.id.name;
+	if (parent !== null && parent.type === "VariableDeclarator") {
+		const decl = parent;
+		if (decl.id !== void 0 && decl.id.name !== void 0) return decl.id.name;
+	}
+	if (parent !== null && parent.type === "MethodDefinition") {
+		const method = parent;
+		if (method.key !== void 0 && method.key.name !== void 0) return method.key.name;
+	}
+	return "<anonymous>";
+};
+/**
+* Parse `source` (JavaScript or TypeScript, via `acorn` + `acorn-typescript`)
+* and return the smallest enclosing function's start line and name for `line`.
+*
+* Returns `null` only when the parser rejects the source outright (rare —
+* usually a syntax error). Type annotations, generics, decorators, and `as`
+* casts are all accepted.
+* @public
+*/
+const findFunctionBoundary = (source, line) => {
+	let ast;
+	try {
+		ast = Parser.parse(source, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			locations: true
+		});
+	} catch {
+		return null;
+	}
+	let smallest = null;
+	const walk = (node, parent) => {
+		if (node === null || node === void 0) return;
+		if (Array.isArray(node)) {
+			for (const child of node) walk(child, parent);
+			return;
+		}
+		if (typeof node !== "object") return;
+		if (isFunctionLike(node) && containsLine(node, line)) if (smallest === null) smallest = {
+			node,
+			parent
+		};
+		else {
+			const currSpan = smallest.node.loc.end.line - smallest.node.loc.start.line;
+			if (node.loc.end.line - node.loc.start.line < currSpan) smallest = {
+				node,
+				parent
+			};
+		}
+		for (const key of Object.keys(node)) {
+			if (key === "loc" || key === "type") continue;
+			const value = node[key];
+			if (value !== null && typeof value === "object") walk(value, node);
+		}
+	};
+	walk(ast, null);
+	if (smallest === null) return null;
+	const s = smallest;
+	return {
+		line: s.node.loc.start.line,
+		name: nodeName(s.node, s.parent)
+	};
+};
+
+//#endregion
+export { findFunctionBoundary };

package/utils/hyperlink.js

@@ -0,0 +1,11 @@
+//#region src/utils/hyperlink.ts
+const ESC = "\x1B";
+const BEL = "\x07";
+/** @public */
+const osc8 = (url, label, options) => {
+	if (!options.enabled) return label;
+	return `${ESC}]8;;${url}${BEL}${label}${ESC}]8;;${BEL}`;
+};
+
+//#endregion
+export { osc8 };

package/utils/match-vitest-command.js

@@ -0,0 +1,88 @@
+//#region src/utils/match-vitest-command.ts
+const RE_DIRECT = /^\s*vitest(\s|$)/;
+const RE_RUNNER = /^\s*(npx|pnpx|bunx)\s+vitest(\s|$)/;
+const RE_PM_EXEC = /^\s*(npm|pnpm|yarn|bun)\s+(exec|dlx|x)\s+vitest(\s|$)/;
+const RE_NODE_BIN = /^\s*node\s+(\.\/)?node_modules\/\.bin\/vitest(\s|$)/;
+const matchPmScript = (command, scripts) => {
+	if (scripts.size === 0) return false;
+	const trimmed = command.trimStart();
+	for (const scriptName of scripts) {
+		const escaped = scriptName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		if (new RegExp(`^(npm|pnpm|yarn|bun)\\s+(run\\s+)?${escaped}(\\s|$)`).test(trimmed)) return true;
+	}
+	return false;
+};
+/**
+* Return `true` if the command invokes Vitest in any of the five
+* supported shapes. The `vitestScripts` set carries the names of
+* package.json scripts that were detected as containing `vitest`
+* (computed once per project and cached by the sidecar).
+* @public
+*/
+const isVitestInvocation = (command, vitestScripts) => {
+	if (RE_DIRECT.test(command)) return true;
+	if (RE_RUNNER.test(command)) return true;
+	if (RE_PM_EXEC.test(command)) return true;
+	if (RE_NODE_BIN.test(command)) return true;
+	if (matchPmScript(command, vitestScripts)) return true;
+	return false;
+};
+/**
+* Build the env-var prefix string to prepend to a matched command.
+*
+* Returns the assignments in the documented order:
+*   `VITEST_AGENT_CONVERSATION_ID=<uuid> VITEST_AGENT_AGENT_ID=<uuid> [VITEST_AGENT_PARENT_AGENT_ID=<uuid>]`
+*
+* POSIX env-prefix syntax scopes the assignments to the
+* immediately-following process — no sticky-env across subsequent
+* Bash calls, no risk of cross-contamination.
+* @public
+*/
+const buildEnvPrefix = (input) => {
+	const parts = [];
+	parts.push(`VITEST_AGENT_CONVERSATION_ID=${input.conversationId}`);
+	parts.push(`VITEST_AGENT_AGENT_ID=${input.agentId}`);
+	if (input.parentAgentId !== void 0) parts.push(`VITEST_AGENT_PARENT_AGENT_ID=${input.parentAgentId}`);
+	return parts.join(" ");
+};
+/**
+* Compute the rewritten command for a Bash tool invocation. When the
+* command does not match a Vitest shape, returns the original
+* unchanged. When it matches, prepends the env prefix.
+* @public
+*/
+const rewriteBashCommand = (input) => {
+	if (!isVitestInvocation(input.command, input.vitestScripts)) return input.command;
+	return `${buildEnvPrefix({
+		conversationId: input.conversationId,
+		agentId: input.agentId,
+		...input.parentAgentId !== void 0 && { parentAgentId: input.parentAgentId }
+	})} ${input.command}`;
+};
+/**
+* Detect which package.json scripts invoke Vitest by inspecting the
+* `scripts` field. Resolves one hop of script reference (e.g.,
+* `"test": "pnpm test:unit && pnpm test:int"` finds vitest if either
+* `test:unit` or `test:int` mentions vitest). Multi-hop indirection
+* is a documented limitation.
+* @public
+*/
+const detectVitestScripts = (scripts) => {
+	const directHits = /* @__PURE__ */ new Set();
+	for (const [name, body] of Object.entries(scripts)) if (/\bvitest\b/.test(body)) directHits.add(name);
+	const includesScriptRef = (body, scriptName) => {
+		const escaped = scriptName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		return new RegExp(`(npm|pnpm|yarn|bun)\\s+(run\\s+)?${escaped}(\\s|$|&)`).test(body);
+	};
+	for (const [name, body] of Object.entries(scripts)) {
+		if (directHits.has(name)) continue;
+		for (const hit of directHits) if (includesScriptRef(body, hit)) {
+			directHits.add(name);
+			break;
+		}
+	}
+	return directHits;
+};
+
+//#endregion
+export { buildEnvPrefix, detectVitestScripts, isVitestInvocation, rewriteBashCommand };

package/utils/normalize-workspace-key.js

@@ -0,0 +1,34 @@
+//#region src/utils/normalize-workspace-key.ts
+/**
+* Normalize a workspace name into a filesystem-safe directory segment.
+*
+* The workspace key drives the per-project subdirectory under the XDG data
+* directory (e.g. `$XDG_DATA_HOME/vitest-agent/<key>/data.db`). The
+* key must be deterministic for a given input and safe to use as a single
+* path segment on macOS, Linux, and Windows.
+*
+* Rules (applied in order):
+*
+* 1. Replace `/` with `__` so scoped names like `@org/pkg` collapse to
+*    `@org__pkg` rather than introducing a subdirectory boundary. Scoped
+*    npm names contain at most one `/` (between scope and name), and
+*    leading-`@` requires the scope/name form, so `@org__pkg` is not a
+*    valid unscoped npm name -- the `__` token is unambiguous in
+*    practice.
+* 2. Replace any character outside `[A-Za-z0-9._@-]` with `_`. This catches
+*    Windows-reserved characters (`\`, `:`, `*`, `?`, `"`, `<`, `>`, `|`),
+*    control characters, whitespace, and anything else that varies in
+*    interpretation across filesystems.
+* 3. Collapse runs of underscores produced by the substitution above into a
+*    single `_` so the output stays compact.
+*
+* @param name - The raw `name` field from a workspace's `package.json`.
+* @returns A filesystem-safe single path segment.
+* @public
+*/
+function normalizeWorkspaceKey(name) {
+	return name.replaceAll("/", "__").replace(/[^A-Za-z0-9._@-]/g, "_").replace(/_{3,}/g, "__");
+}
+
+//#endregion
+export { normalizeWorkspaceKey };