@vitest-agent/mcp 3.0.4 → 4.0.0

package/{context.js → session.js}

@@ -1,9 +1,8 @@
-import { initTRPC } from "@trpc/server";
-import { MutableRef } from "effect";
+import { Context, Layer, MutableRef } from "effect";
 
-//#region src/context.ts
+//#region src/session.ts
 /**
-* Creates a new {@link CurrentSessionIdRef} with an optional initial value.
+* Creates a new `CurrentSessionIdRef` with an optional initial value.
 *
 * @param initial - the starting chat id, or `null` when unknown at construction time
 * @returns a mutable ref holding the current session id
@@ -19,7 +18,7 @@ const createCurrentSessionIdRef = (initial = null) => {
 	};
 };
 /**
-* Creates a new {@link SessionContextRef} with an optional initial value.
+* Creates a new `SessionContextRef` with an optional initial value.
 *
 * When a `recover` thunk is supplied, `get()` invokes it lazily while the
 * held value is `null` and caches the first non-null result. This is how
@@ -48,14 +47,17 @@ const createSessionContextRef = (initial = null, recover) => {
 	};
 };
 /**
-* Resolve the boot-time SessionContext from `process.env` (the
-* primary path: SessionStart wrote the exports to `CLAUDE_ENV_FILE`
-* and Claude Code auto-sources that file into the MCP server child).
+* Resolve the boot-time SessionContext from an environment map (the
+* primary path: SessionStart wrote the exports to `CLAUDE_ENV_FILE` and
+* Claude Code auto-sources that file into the MCP server child).
 *
-* Returns `null` when any required value is absent — callers can
-* still attempt the session-map fallback before giving up.
+* Returns `null` when any required value is absent — callers can still
+* attempt the session-map fallback before giving up.
+*
+* @param env - the environment map to read; the bin passes `process.env`
+* @public
 */
-const sessionContextFromEnv = (env = process.env) => {
+const sessionContextFromEnv = (env) => {
 	const chatId = env.VITEST_AGENT_CHAT_ID;
 	const conversationId = env.VITEST_AGENT_CONVERSATION_ID;
 	const mainAgentId = env.VITEST_AGENT_MAIN_AGENT_ID ?? env.VITEST_AGENT_AGENT_ID;
@@ -67,20 +69,34 @@ const sessionContextFromEnv = (env = process.env) => {
 		mainAgentId
 	};
 };
-const t = initTRPC.context().create();
-const router = t.router;
-const publicProcedure = t.procedure;
 /**
-* Factory for creating server-side tRPC callers for the MCP router.
-*
-* Use with {@link appRouter} in tests or programmatic contexts to invoke
-* tool procedures without starting the MCP server.
+* The per-process MCP session service consumed by tool handlers.
 *
 * @public
 */
-const createCallerFactory = t.createCallerFactory;
-/** Exported so middleware modules can attach to the same tRPC instance. */
-const middleware = t.middleware;
+var McpSession = class McpSession extends Context.Service()("@vitest-agent/mcp/McpSession") {
+	/**
+	* The live session: seeded from the bin's boot-time recovery, healing
+	* lazily through `recover` on the first `sessionContext.get()` that
+	* finds a `null` context.
+	*/
+	static layer = (options) => Layer.succeed(McpSession, {
+		cwd: options.cwd,
+		currentSessionId: createCurrentSessionIdRef(options.initialSessionId),
+		sessionContext: createSessionContextRef(options.initialContext, options.recover)
+	});
+	/**
+	* A test session: `cwd` is the caller's (this module is process-free,
+	* so the test harness passes `process.cwd()` itself), both refs start
+	* `null`, and either can be overridden.
+	*/
+	static layerTest = (overrides) => McpSession.layer({
+		cwd: overrides.cwd,
+		initialSessionId: overrides.initialSessionId ?? null,
+		initialContext: overrides.initialContext ?? null,
+		...overrides.recover === void 0 ? {} : { recover: overrides.recover }
+	});
+};
 
 //#endregion
-export { createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, middleware, publicProcedure, router, sessionContextFromEnv };
+export { McpSession, createCurrentSessionIdRef, createSessionContextRef, sessionContextFromEnv };

package/toolkit.js

@@ -0,0 +1,86 @@
+import { withIdempotency } from "./idempotency.js";
+import { acceptanceMetricsTool, handleAcceptanceMetrics } from "./tools/acceptance-metrics.js";
+import { cacheHealthTool, handleCacheHealth } from "./tools/cache-health.js";
+import { commitChangesTool, handleCommitChanges } from "./tools/commit-changes.js";
+import { configureTool, handleConfigure } from "./tools/configure.js";
+import { handleTestCoverage, testCoverageTool } from "./tools/coverage.js";
+import { handleTestErrors, testErrorsTool } from "./tools/errors.js";
+import { failureSignatureGetTool, handleFailureSignatureGet } from "./tools/failure-signature-get.js";
+import { fileCoverageTool, handleFileCoverage } from "./tools/file-coverage.js";
+import { handleHelp, helpTool } from "./tools/help.js";
+import { handleTestHistory, testHistoryTool } from "./tools/history.js";
+import { handleHypothesis, hypothesisTool } from "./tools/hypothesis.js";
+import { handleInventory, inventoryTool } from "./tools/inventory.js";
+import { handleNote, noteTool } from "./tools/note.js";
+import { handleTestOverview, testOverviewTool } from "./tools/overview.js";
+import { handlePing, pingTool } from "./tools/ping.js";
+import { handleRegisterAgent, registerAgentTool } from "./tools/register-agent.js";
+import { handleRunTests, runTestsTool } from "./tools/run-tests.js";
+import { handleSettingsList, settingsListTool } from "./tools/settings-list.js";
+import { handleTestStatus, testStatusTool } from "./tools/status.js";
+import { handleTddArtifactList, tddArtifactListTool } from "./tools/tdd-artifact.js";
+import { handleTddBehavior, tddBehaviorTool } from "./tools/tdd-behavior.js";
+import { handleTddGoal, tddGoalTool } from "./tools/tdd-goal.js";
+import { handlePhaseTransitionRequest, tddPhaseTransitionRequestTool } from "./tools/tdd-phase-transition-request.js";
+import { handleTddProgressPush, tddProgressPushTool } from "./tools/tdd-progress-push.js";
+import { handleTddTask, tddTaskTool } from "./tools/tdd-task.js";
+import { handleTest, testTool } from "./tools/test.js";
+import { handleTestTrends, testTrendsTool } from "./tools/trends.js";
+import { handleTriageBrief, triageBriefTool } from "./tools/triage-brief.js";
+import { handleTurnSearch, turnSearchTool } from "./tools/turn-search.js";
+import { handleWrapupPrompt, wrapupPromptTool } from "./tools/wrapup-prompt.js";
+import { Toolkit } from "effect/unstable/ai";
+
+//#region src/toolkit.ts
+/**
+* Every tool the server registers.
+*
+* @public
+*/
+const Kit = Toolkit.make(pingTool, helpTool, testStatusTool, testOverviewTool, testCoverageTool, testHistoryTool, testTrendsTool, testErrorsTool, fileCoverageTool, settingsListTool, cacheHealthTool, configureTool, commitChangesTool, turnSearchTool, failureSignatureGetTool, acceptanceMetricsTool, triageBriefTool, wrapupPromptTool, inventoryTool, testTool, registerAgentTool, noteTool, hypothesisTool, tddTaskTool, tddPhaseTransitionRequestTool, tddGoalTool, tddBehaviorTool, tddArtifactListTool, tddProgressPushTool, runTestsTool);
+/**
+* The handler for each tool in {@link Kit}, keyed by tool name.
+*
+* @public
+*/
+const toolHandlers = {
+	ping: handlePing,
+	help: handleHelp,
+	test_status: handleTestStatus,
+	test_overview: handleTestOverview,
+	test_coverage: handleTestCoverage,
+	test_history: handleTestHistory,
+	test_trends: handleTestTrends,
+	test_errors: handleTestErrors,
+	file_coverage: handleFileCoverage,
+	settings_list: handleSettingsList,
+	cache_health: handleCacheHealth,
+	configure: handleConfigure,
+	commit_changes: handleCommitChanges,
+	turn_search: handleTurnSearch,
+	failure_signature_get: handleFailureSignatureGet,
+	acceptance_metrics: handleAcceptanceMetrics,
+	triage_brief: handleTriageBrief,
+	wrapup_prompt: handleWrapupPrompt,
+	inventory: handleInventory,
+	test: handleTest,
+	register_agent: handleRegisterAgent,
+	note: handleNote,
+	hypothesis: withIdempotency("hypothesis", handleHypothesis),
+	tdd_task: withIdempotency("tdd_task", handleTddTask),
+	tdd_phase_transition_request: handlePhaseTransitionRequest,
+	tdd_goal: withIdempotency("tdd_goal", handleTddGoal),
+	tdd_behavior: withIdempotency("tdd_behavior", handleTddBehavior),
+	tdd_artifact_list: handleTddArtifactList,
+	tdd_progress_push: handleTddProgressPush,
+	run_tests: handleRunTests
+};
+/**
+* The handlers layer: provides `Tool.HandlersFor<typeof Kit.tools>`.
+*
+* @public
+*/
+const ToolsLayer = Kit.toLayer(toolHandlers);
+
+//#endregion
+export { Kit, ToolsLayer, toolHandlers };

package/tools/acceptance-metrics.js

@@ -1,20 +1,16 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Schema, SchemaGetter } from "effect";
-import { DataReader } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/acceptance-metrics.ts
+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." };
 /**
-* `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.
+* The `acceptance_metrics` tool's success payload.
 *
-* @packageDocumentation
+* @public
 */
-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.Finite.annotate(totalAnnotation),
@@ -66,9 +62,25 @@ const AcceptanceMetricsAsMarkdown = AcceptanceMetricsResult.pipe(Schema.decodeTo
 	decode: SchemaGetter.transform((data) => formatAcceptanceMetricsMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "AcceptanceMetricsAsMarkdown is one-way: markdown cannot be parsed back to AcceptanceMetricsResult.")
 }));
-const acceptanceMetrics = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({}))).query(async ({ ctx }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* Handler for {@link acceptanceMetricsTool}.
+*
+* @public
+*/
+const handleAcceptanceMetrics = () => Effect.gen(function* () {
 	return yield* (yield* DataReader).computeAcceptanceMetrics();
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `acceptance_metrics` tool. No parameters (the default
+* `Tool.EmptyParams` serves as a strict empty object).
+*
+* @public
+*/
+const acceptanceMetricsTool = Tool.make("acceptance_metrics", {
+	description: "Use when you need the four spec Annex A acceptance metrics computed from the current database. Returns markdown in content[] and a typed JSON object in structuredContent (per-metric { total, ratio, ... }).",
+	success: AcceptanceMetricsResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Acceptance metrics").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatAcceptanceMetricsMarkdown(encoded));
 
 //#endregion
-export { AcceptanceMetricsAsMarkdown, AcceptanceMetricsResult, acceptanceMetrics, formatAcceptanceMetricsMarkdown };
+export { AcceptanceMetricsResult, acceptanceMetricsTool, formatAcceptanceMetricsMarkdown, handleAcceptanceMetrics };

package/tools/cache-health.js

@@ -1,20 +1,10 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Option, Schema, SchemaGetter } from "effect";
-import { CacheManifest, DataReader } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { CacheManifest } from "@vitest-agent/sdk";
 
 //#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).annotate({ description: "Discriminant — `true` when a cache manifest exists." }),
 	manifest: CacheManifest.annotate({ description: "Full cache manifest content as written by the reporter." }),
@@ -28,6 +18,11 @@ const ManifestAbsent = Schema.Struct({ manifestPresent: Schema.Literal(false).an
 	identifier: "CacheHealthAbsent",
 	title: "Cache manifest absent"
 });
+/**
+* The `cache_health` tool's success payload.
+*
+* @public
+*/
 const CacheHealthResult = Schema.Union([ManifestPresent, ManifestAbsent]).annotate({
 	identifier: "CacheHealthResult",
 	title: "cache_health result",
@@ -65,7 +60,12 @@ const CacheHealthAsMarkdown = CacheHealthResult.pipe(Schema.decodeTo(Schema.Stri
 	decode: SchemaGetter.transform((data) => formatCacheHealthMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "CacheHealthAsMarkdown is one-way: markdown cannot be parsed back to CacheHealthResult.")
 }));
-const cacheHealth = publicProcedure.query(async ({ ctx }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* Handler for {@link cacheHealthTool}.
+*
+* @public
+*/
+const handleCacheHealth = () => Effect.gen(function* () {
 	const manifestOpt = yield* (yield* DataReader).getManifest();
 	if (Option.isNone(manifestOpt)) return { manifestPresent: false };
 	const manifest = manifestOpt.value;
@@ -76,7 +76,18 @@ const cacheHealth = publicProcedure.query(async ({ ctx }) => ctx.runtime.runProm
 		ageMs,
 		stale: ageMs > STALE_AFTER_MS
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `cache_health` tool. No parameters (the default
+* `Tool.EmptyParams` serves as a strict empty object).
+*
+* @public
+*/
+const cacheHealthTool = Tool.make("cache_health", {
+	description: "Use when you suspect stale data and need manifest presence, project states, and staleness. Returns markdown in content[] and a typed JSON object in structuredContent ({ manifestPresent, manifest?, ageMs?, stale? }).",
+	success: CacheHealthResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Cache health").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatCacheHealthMarkdown(encoded));
 
 //#endregion
-export { CacheHealthAsMarkdown, CacheHealthResult, cacheHealth, formatCacheHealthMarkdown };
+export { CacheHealthResult, cacheHealthTool, formatCacheHealthMarkdown, handleCacheHealth };

package/tools/commit-changes.js

@@ -1,13 +1,9 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Schema, SchemaGetter } from "effect";
-import { DataReader } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/commit-changes.ts
-/**
-* `commit_changes` MCP tool — Schema-driven implementation.
-*
-* @packageDocumentation
-*/
 const FileRow = Schema.Struct({
 	filePath: Schema.String.annotate({ description: "Repo-relative path of the changed file." }),
 	changeKind: Schema.Literals([
@@ -27,6 +23,11 @@ const CommitRow = Schema.Struct({
 	branch: Schema.NullOr(Schema.String).annotate({ description: "Branch the commit was recorded on at hook fire time." }),
 	files: Schema.Array(FileRow).annotate({ description: "Files this commit changed, with per-file change kinds." })
 }).annotate({ identifier: "CommitRow" });
+/**
+* The `commit_changes` tool's success payload.
+*
+* @public
+*/
 const CommitChangesResult = Schema.Struct({
 	filterSha: Schema.optional(Schema.String).annotate({ description: "Echo of the optional `sha` filter the caller passed; absent when no filter was applied (recent commits returned)." }),
 	count: Schema.Finite.annotate({ description: "Number of commit rows returned." }),
@@ -56,14 +57,36 @@ const CommitChangesAsMarkdown = CommitChangesResult.pipe(Schema.decodeTo(Schema.
 	decode: SchemaGetter.transform((data) => formatCommitChangesMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "CommitChangesAsMarkdown is one-way: markdown cannot be parsed back to CommitChangesResult.")
 }));
-const commitChanges = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({ sha: Schema.optional(Schema.String) }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `commit_changes` tool's parameters.
+*
+* @public
+*/
+const CommitChangesInput = Schema.Struct({ sha: Schema.optionalKey(Schema.String).annotate({ description: "Specific commit sha to fetch; omit for recent commits" }) });
+/**
+* Handler for {@link commitChangesTool}.
+*
+* @public
+*/
+const handleCommitChanges = (input) => Effect.gen(function* () {
 	const entries = yield* (yield* DataReader).getCommitChanges(input.sha);
 	return {
 		...input.sha !== void 0 && { filterSha: input.sha },
 		count: entries.length,
 		commits: entries
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `commit_changes` tool.
+*
+* @public
+*/
+const commitChangesTool = Tool.make("commit_changes", {
+	description: "Use when you need commit metadata and changed files captured by the post-commit hook. Returns up to 20 most-recent when sha is omitted. Returns markdown in content[] and a typed JSON object in structuredContent ({ filterSha?, count, commits[] }).",
+	parameters: CommitChangesInput,
+	success: CommitChangesResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Commit changes").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatCommitChangesMarkdown(encoded));
 
 //#endregion
-export { CommitChangesAsMarkdown, CommitChangesResult, commitChanges, formatCommitChangesMarkdown };
+export { CommitChangesInput, CommitChangesResult, commitChangesTool, formatCommitChangesMarkdown, handleCommitChanges };

package/tools/configure.js

@@ -1,13 +1,9 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Option, Schema, SchemaGetter } from "effect";
-import { DataReader } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/configure.ts
-/**
-* `configure` MCP tool — Schema-driven implementation.
-*
-* @packageDocumentation
-*/
 const SettingsRowSchema = Schema.Struct({
 	hash: Schema.String.annotate({ description: "Stable SHA-1 of the captured Vitest settings; `test_runs.settings_hash` foreign key." }),
 	reporters: Schema.NullOr(Schema.String).annotate({ description: "Comma-separated reporter list as resolved from the user's vitest config." }),
@@ -35,6 +31,11 @@ const SettingsAbsent = Schema.Struct({
 	source: Schema.Literals(["requested", "latest"]),
 	requestedHash: Schema.optional(Schema.String).annotate({ description: "Echo of the hash the caller passed; absent when the empty `latest` lookup found nothing." })
 }).annotate({ identifier: "ConfigureAbsent" });
+/**
+* The `configure` tool's success payload.
+*
+* @public
+*/
 const ConfigureResult = Schema.Union([SettingsFound, SettingsAbsent]).annotate({
 	identifier: "ConfigureResult",
 	title: "configure result",
@@ -74,7 +75,18 @@ const ConfigureAsMarkdown = ConfigureResult.pipe(Schema.decodeTo(Schema.String,
 	decode: SchemaGetter.transform((data) => formatConfigureMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "ConfigureAsMarkdown is one-way: markdown cannot be parsed back to ConfigureResult.")
 }));
-const configure = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({ settingsHash: Schema.optional(Schema.String) }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `configure` tool's parameters.
+*
+* @public
+*/
+const ConfigureInput = Schema.Struct({ settingsHash: Schema.optionalKey(Schema.String).annotate({ description: "Settings hash from a manifest entry or test run" }) });
+/**
+* Handler for {@link configureTool}.
+*
+* @public
+*/
+const handleConfigure = (input) => Effect.gen(function* () {
 	const reader = yield* DataReader;
 	if (input.settingsHash === void 0) {
 		const latestOpt = yield* reader.getLatestSettings();
@@ -97,7 +109,18 @@ const configure = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct(
 		source: "requested",
 		settings: settingsOpt.value
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `configure` tool.
+*
+* @public
+*/
+const configureTool = Tool.make("configure", {
+	description: "Use when you need the captured Vitest settings for a test run. Returns markdown in content[] and a typed JSON object in structuredContent ({ found, source, settings?, requestedHash? }).",
+	parameters: ConfigureInput,
+	success: ConfigureResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Configure").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatConfigureMarkdown(encoded));
 
 //#endregion
-export { ConfigureAsMarkdown, ConfigureResult, configure, formatConfigureMarkdown };
+export { ConfigureInput, ConfigureResult, configureTool, formatConfigureMarkdown, handleConfigure };

package/tools/coverage.js

@@ -1,6 +1,8 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Option, Schema, SchemaGetter } from "effect";
-import { CoverageReport, DataReader } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { CoverageReport } from "@vitest-agent/sdk";
 
 //#region src/tools/coverage.ts
 const CoverageAvailable = Schema.Struct({
@@ -12,6 +14,11 @@ const CoverageAbsent = Schema.Struct({
 	dataAvailable: Schema.Literal(false),
 	project: Schema.String
 }).annotate({ identifier: "TestCoverageAbsent" });
+/**
+* The `test_coverage` tool's success payload.
+*
+* @public
+*/
 const TestCoverageResult = Schema.Union([CoverageAvailable, CoverageAbsent]).annotate({
 	identifier: "TestCoverageResult",
 	title: "test_coverage result",
@@ -66,7 +73,18 @@ const TestCoverageAsMarkdown = TestCoverageResult.pipe(Schema.decodeTo(Schema.St
 	decode: SchemaGetter.transform((data) => formatTestCoverageMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "TestCoverageAsMarkdown is one-way.")
 }));
-const testCoverage = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({ project: Schema.optional(Schema.String) }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `test_coverage` tool's parameters.
+*
+* @public
+*/
+const TestCoverageInput = Schema.Struct({ project: Schema.optionalKey(Schema.String).annotate({ description: "Project name" }) });
+/**
+* Handler for {@link testCoverageTool}.
+*
+* @public
+*/
+const handleTestCoverage = (input) => Effect.gen(function* () {
 	const reader = yield* DataReader;
 	const project = input.project ?? "default";
 	const coverageOpt = yield* reader.getCoverage(project);
@@ -79,7 +97,18 @@ const testCoverage = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Stru
 		project,
 		coverage: coverageOpt.value
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `test_coverage` tool.
+*
+* @public
+*/
+const testCoverageTool = Tool.make("test_coverage", {
+	description: "Use when coverage drops and you need per-metric gap analysis against thresholds and targets. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, project, coverage } or absent variant).",
+	parameters: TestCoverageInput,
+	success: TestCoverageResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Test coverage").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTestCoverageMarkdown(encoded));
 
 //#endregion
-export { TestCoverageAsMarkdown, TestCoverageResult, formatTestCoverageMarkdown, testCoverage };
+export { TestCoverageInput, TestCoverageResult, formatTestCoverageMarkdown, handleTestCoverage, testCoverageTool };

package/tools/errors.js

@@ -1,25 +1,9 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Schema, SchemaGetter } from "effect";
-import { DataReader } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#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.decodeTo` whose `decode` direction renders the
-*     markdown the text channel carries (encode 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 annotation attached to a failing test, surfaced with its error. */
 const TestErrorAnnotation = Schema.Struct({
 	type: Schema.String.annotate({ description: "Annotation type as the test author wrote it — an arbitrary string, not an enum." }),
@@ -60,7 +44,11 @@ const TestErrorRow = Schema.Struct({
 	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`. */
+/**
+* The `test_errors` tool's success payload — populates `structuredContent`.
+*
+* @public
+*/
 const TestErrorsResult = Schema.Struct({
 	project: Schema.String.annotate({
 		title: "Project name",
@@ -153,10 +141,21 @@ const TestErrorsAsMarkdown = TestErrorsResult.pipe(Schema.decodeTo(Schema.String
 	decode: SchemaGetter.transform((data) => formatTestErrorsMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "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.toStandardSchemaV1(Schema.Struct({
-	project: Schema.String,
-	errorName: Schema.optional(Schema.String)
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `test_errors` tool's parameters.
+*
+* @public
+*/
+const TestErrorsInput = Schema.Struct({
+	project: Schema.String.annotate({ description: "Project name (required)" }),
+	errorName: Schema.optionalKey(Schema.String).annotate({ description: "Filter to a specific error name" })
+});
+/**
+* Handler for {@link testErrorsTool}.
+*
+* @public
+*/
+const handleTestErrors = (input) => Effect.gen(function* () {
 	const reader = yield* DataReader;
 	const errors = yield* reader.getErrors(input.project, input.errorName);
 	const cache = /* @__PURE__ */ new Map();
@@ -190,7 +189,18 @@ const testErrors = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct
 		count: rows.length,
 		errors: rows
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `test_errors` tool.
+*
+* @public
+*/
+const testErrorsTool = Tool.make("test_errors", {
+	description: "Use when a test fails and you need error detail, diffs, and the cite-able test_errors.id / stack_frames.id values needed by hypothesis (action: record). Returns both a markdown rendering (in content[].text) and a typed JSON object (in structuredContent) — agents should prefer structuredContent.errors[].",
+	parameters: TestErrorsInput,
+	success: TestErrorsResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Test errors").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTestErrorsMarkdown(encoded));
 
 //#endregion
-export { TestErrorAnnotation, TestErrorRow, TestErrorsAsMarkdown, TestErrorsResult, formatTestErrorsMarkdown, testErrors };
+export { TestErrorAnnotation, TestErrorRow, TestErrorsInput, TestErrorsResult, formatTestErrorsMarkdown, handleTestErrors, testErrorsTool };