@vitest-agent/mcp 3.0.3 → 4.0.0

package/tools/test.js

@@ -1,7 +1,8 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { collectProjectRows, resolveProjectTargets } from "./_project-groups.js";
 import { Effect, Match, 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/test.ts
 const TestRowSchema = Schema.Struct({
@@ -141,6 +142,11 @@ const TestArtifactsResult = Schema.Struct({
 	count: Schema.Number,
 	artifacts: Schema.Array(ArtifactRowSchema)
 }).annotate({ identifier: "TestArtifacts" });
+/**
+* The `test` tool's success payload.
+*
+* @public
+*/
 const TestResult = Schema.Union([
 	TestListResult,
 	TestGetFound,
@@ -297,40 +303,47 @@ const TestAsMarkdown = TestResult.pipe(Schema.decodeTo(Schema.String, {
 }));
 const ListVariant = Schema.Struct({
 	action: Schema.Literal("list"),
-	project: Schema.optional(Schema.String),
-	state: Schema.optional(Schema.String),
-	module: Schema.optional(Schema.String),
-	limit: Schema.optional(Schema.Number)
+	project: Schema.optionalKey(Schema.String),
+	state: Schema.optionalKey(Schema.String).annotate({ description: "list: filter by state" }),
+	module: Schema.optionalKey(Schema.String).annotate({ description: "list: filter by module path" }),
+	limit: Schema.optionalKey(Schema.Finite).annotate({ description: "list: max rows to return" })
 });
 const GetVariant = Schema.Struct({
 	action: Schema.Literal("get"),
-	fullName: Schema.String,
-	project: Schema.optional(Schema.String),
-	modulePath: Schema.optional(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." })
+	fullName: Schema.String.annotate({ description: "get / annotations / artifacts: full test name" }),
+	project: Schema.optionalKey(Schema.String),
+	modulePath: Schema.optionalKey(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." })
 });
 const ForFileVariant = Schema.Struct({
 	action: Schema.Literal("for_file"),
-	filePath: Schema.String
+	filePath: Schema.String.annotate({ description: "for_file: source file path" })
 });
 const ForTagVariant = Schema.Struct({
 	action: Schema.Literal("for_tag"),
-	tag: Schema.String,
-	project: Schema.optional(Schema.String)
+	tag: Schema.String.annotate({ description: "for_tag: tag name" }),
+	project: Schema.optionalKey(Schema.String)
 });
 const AnnotationsVariant = Schema.Struct({
 	action: Schema.Literal("annotations"),
-	fullName: Schema.String,
-	project: Schema.optional(Schema.String),
-	modulePath: Schema.optional(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." }),
-	maxBytes: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).annotate({ description: "Total byte budget for inline attachment bodies across the whole response. Must be a non-negative integer. Defaults to 0 — descriptors only, no bodies." }))
+	fullName: Schema.String.annotate({ description: "get / annotations / artifacts: full test name" }),
+	project: Schema.optionalKey(Schema.String),
+	modulePath: Schema.optionalKey(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." }),
+	maxBytes: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).annotate({ description: "Total byte budget for inline attachment bodies across the whole response. Must be a non-negative integer. Defaults to 0 — descriptors only, no bodies." }))
 });
 const ArtifactsVariant = Schema.Struct({
 	action: Schema.Literal("artifacts"),
-	fullName: Schema.String,
-	project: Schema.optional(Schema.String),
-	modulePath: Schema.optional(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." }),
-	maxBytes: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).annotate({ description: "Total byte budget for inline attachment bodies across the whole response. Must be a non-negative integer. Defaults to 0 — descriptors only, no bodies." }))
+	fullName: Schema.String.annotate({ description: "get / annotations / artifacts: full test name" }),
+	project: Schema.optionalKey(Schema.String),
+	modulePath: Schema.optionalKey(Schema.String).annotate({ description: "Exact module_path match — disambiguates a fullName that exists in more than one test file." }),
+	maxBytes: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).annotate({ description: "Total byte budget for inline attachment bodies across the whole response. Must be a non-negative integer. Defaults to 0 — descriptors only, no bodies." }))
 });
+/**
+* The `test` tool's parameters — a union discriminated on `action`. The
+* served JSON Schema is a `oneOf` over the variants with
+* `x-discriminator: "action"`.
+*
+* @public
+*/
 const TestInput = Schema.Union([
 	ListVariant,
 	GetVariant,
@@ -340,132 +353,133 @@ const TestInput = Schema.Union([
 	ArtifactsVariant
 ]);
 /**
-* Single source of truth for the `test` tool's `action` discriminant,
-* consumed by `server.ts`'s served `z.enum(...)` so the MCP-SDK-side
-* registration cannot drift from this tRPC input union (issue #335).
+* Handler for {@link testTool}.
+*
+* @public
 */
-const TEST_ACTIONS = [
-	"list",
-	"get",
-	"for_file",
-	"for_tag",
-	"annotations",
-	"artifacts"
-];
-const test = publicProcedure.input(Schema.toStandardSchemaV1(TestInput)).query(async ({ ctx, input }) => {
-	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
-		list: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const opts = {};
-			if (variant.state !== void 0) opts.state = variant.state;
-			if (variant.module !== void 0) opts.module = variant.module;
-			if (variant.limit !== void 0) opts.limit = variant.limit;
-			const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
-			const grouped = yield* collectProjectRows(targets, (project) => reader.listTests(project, opts));
-			const groups = grouped.groups.map((group) => ({
-				project: group.project,
-				tests: group.rows
-			}));
-			return {
-				action: "list",
-				count: grouped.total,
-				groups
-			};
-		}),
-		get: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const candidates = variant.project ? [variant.project] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => r.project)));
-			for (const project of candidates) {
-				const modules = yield* reader.getTestModulesByFullName(project, variant.fullName);
-				if (modules.length === 0) continue;
-				if (variant.modulePath === void 0 && modules.length > 1) return {
-					action: "get",
-					found: false,
-					project,
-					fullName: variant.fullName,
-					ambiguous: true,
-					candidateModules: modules
-				};
-				const testOpt = yield* reader.getTestByFullName(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
-				if (Option.isNone(testOpt)) continue;
-				const matchingErrors = (yield* reader.getErrors(project)).filter((e) => e.testFullName === variant.fullName && e.moduleFile === testOpt.value.module).map((e) => ({
-					name: e.name,
-					message: e.message,
-					diff: e.diff,
-					stack: e.stack
-				}));
-				const testHistory = (yield* reader.getHistory(project, {
-					testName: variant.fullName,
-					modulePath: testOpt.value.module
-				})).tests.find((entry) => entry.fullName === variant.fullName);
-				return {
-					action: "get",
-					found: true,
-					project,
-					test: testOpt.value,
-					errors: matchingErrors,
-					runs: testHistory ? testHistory.runs : []
-				};
-			}
-			return {
+const handleTest = (input) => Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+	list: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const opts = {};
+		if (variant.state !== void 0) opts.state = variant.state;
+		if (variant.module !== void 0) opts.module = variant.module;
+		if (variant.limit !== void 0) opts.limit = variant.limit;
+		const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
+		const grouped = yield* collectProjectRows(targets, (project) => reader.listTests(project, opts));
+		const groups = grouped.groups.map((group) => ({
+			project: group.project,
+			tests: group.rows
+		}));
+		return {
+			action: "list",
+			count: grouped.total,
+			groups
+		};
+	}),
+	get: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const candidates = variant.project ? [variant.project] : yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs.map((r) => r.project)));
+		for (const project of candidates) {
+			const modules = yield* reader.getTestModulesByFullName(project, variant.fullName);
+			if (modules.length === 0) continue;
+			if (variant.modulePath === void 0 && modules.length > 1) return {
 				action: "get",
 				found: false,
-				project: variant.project ?? candidates[0] ?? "",
-				fullName: variant.fullName
-			};
-		}),
-		for_file: (variant) => Effect.gen(function* () {
-			const testFiles = yield* (yield* DataReader).getTestsForFile(variant.filePath);
-			return {
-				action: "for_file",
-				filePath: variant.filePath,
-				count: testFiles.length,
-				testFiles
-			};
-		}),
-		for_tag: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
-			const grouped = yield* collectProjectRows(targets, (project) => reader.listTestsForTag(variant.tag, { project }));
-			const groups = grouped.groups.map((group) => ({
-				project: group.project,
-				tests: group.rows
-			}));
-			return {
-				action: "for_tag",
-				tag: variant.tag,
-				count: grouped.total,
-				groups
-			};
-		}),
-		annotations: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const project = variant.project ?? (yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs[0]?.project ?? "")));
-			const rows = yield* reader.getAnnotationsForTest(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
-			const annotations = applyBodyBudget(rows, variant.maxBytes ?? 0);
-			return {
-				action: "annotations",
 				project,
 				fullName: variant.fullName,
-				count: annotations.length,
-				annotations
+				ambiguous: true,
+				candidateModules: modules
 			};
-		}),
-		artifacts: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const project = variant.project ?? (yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs[0]?.project ?? "")));
-			const rows = yield* reader.getArtifactsForTest(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
-			const artifacts = applyBodyBudget(rows, variant.maxBytes ?? 0);
+			const testOpt = yield* reader.getTestByFullName(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
+			if (Option.isNone(testOpt)) continue;
+			const matchingErrors = (yield* reader.getErrors(project)).filter((e) => e.testFullName === variant.fullName && e.moduleFile === testOpt.value.module).map((e) => ({
+				name: e.name,
+				message: e.message,
+				diff: e.diff,
+				stack: e.stack
+			}));
+			const testHistory = (yield* reader.getHistory(project, {
+				testName: variant.fullName,
+				modulePath: testOpt.value.module
+			})).tests.find((entry) => entry.fullName === variant.fullName);
 			return {
-				action: "artifacts",
+				action: "get",
+				found: true,
 				project,
-				fullName: variant.fullName,
-				count: artifacts.length,
-				artifacts
+				test: testOpt.value,
+				errors: matchingErrors,
+				runs: testHistory ? testHistory.runs : []
 			};
-		})
-	})));
-});
+		}
+		return {
+			action: "get",
+			found: false,
+			project: variant.project ?? candidates[0] ?? "",
+			fullName: variant.fullName
+		};
+	}),
+	for_file: (variant) => Effect.gen(function* () {
+		const testFiles = yield* (yield* DataReader).getTestsForFile(variant.filePath);
+		return {
+			action: "for_file",
+			filePath: variant.filePath,
+			count: testFiles.length,
+			testFiles
+		};
+	}),
+	for_tag: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
+		const grouped = yield* collectProjectRows(targets, (project) => reader.listTestsForTag(variant.tag, { project }));
+		const groups = grouped.groups.map((group) => ({
+			project: group.project,
+			tests: group.rows
+		}));
+		return {
+			action: "for_tag",
+			tag: variant.tag,
+			count: grouped.total,
+			groups
+		};
+	}),
+	annotations: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const project = variant.project ?? (yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs[0]?.project ?? "")));
+		const rows = yield* reader.getAnnotationsForTest(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
+		const annotations = applyBodyBudget(rows, variant.maxBytes ?? 0);
+		return {
+			action: "annotations",
+			project,
+			fullName: variant.fullName,
+			count: annotations.length,
+			annotations
+		};
+	}),
+	artifacts: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const project = variant.project ?? (yield* reader.getRunsByProject().pipe(Effect.map((rs) => rs[0]?.project ?? "")));
+		const rows = yield* reader.getArtifactsForTest(project, variant.fullName, { ...variant.modulePath !== void 0 && { modulePath: variant.modulePath } });
+		const artifacts = applyBodyBudget(rows, variant.maxBytes ?? 0);
+		return {
+			action: "artifacts",
+			project,
+			fullName: variant.fullName,
+			count: artifacts.length,
+			artifacts
+		};
+	})
+})).pipe(Effect.orDie);
+/**
+* The Effect-native `test` tool.
+*
+* @public
+*/
+const testTool = Tool.make("test", {
+	description: "Use to inspect tests, with an action discriminator: action='list' (project?, state?, module?, limit?) returns matching tests; action='get' (fullName, project?, modulePath?) returns details + errors + run history — a fullName that exists in more than one module returns found=false with ambiguous=true and candidateModules[], so pass modulePath to disambiguate; action='for_file' (filePath) returns test modules covering a source file; action='for_tag' (tag, project?) returns tests carrying a tag, grouped by project; action='annotations' (fullName, project?, modulePath?) returns the test annotations the author recorded via context.annotate; action='artifacts' (fullName, project?, modulePath?) returns the test artifacts recorded for the test — both return attachment descriptors (contentType, path, byteSize) and omit inline bodies unless maxBytes (a non-negative integer byte budget for the whole response, default 0) is passed, and neither has anything to do with TDD artifacts (see tdd_artifact_list). structuredContent carries the typed payload (discriminate on `action`, then on `found` for get).",
+	parameters: TestInput,
+	success: TestResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Test").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTestMarkdown(encoded));
 
 //#endregion
-export { TEST_ACTIONS, TestAsMarkdown, TestResult, formatTestMarkdown, test };
+export { TestInput, TestResult, formatTestMarkdown, handleTest, testTool };

package/tools/trends.js

@@ -1,18 +1,10 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Option, Schema, SchemaGetter } from "effect";
-import { DataReader, TrendRecord } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { TrendRecord } from "@vitest-agent/sdk";
 
 //#region src/tools/trends.ts
-/**
-* `test_trends` MCP tool — Schema-driven implementation.
-*
-* Wraps the existing `TrendRecord` Schema in a result envelope that
-* carries the project name and a `dataAvailable` flag, so callers
-* can distinguish "no trend data yet" from "data plus rendering"
-* without parsing prose.
-*
-* @packageDocumentation
-*/
 const TrendsAvailable = Schema.Struct({
 	dataAvailable: Schema.Literal(true).annotate({ description: "Discriminant — `true` when at least one trend entry exists for the project." }),
 	project: Schema.String,
@@ -22,6 +14,11 @@ const TrendsAbsent = Schema.Struct({
 	dataAvailable: Schema.Literal(false).annotate({ description: "Discriminant — `false` when fewer than two runs have been recorded for the project." }),
 	project: Schema.String
 }).annotate({ identifier: "TestTrendsAbsent" });
+/**
+* The `test_trends` tool's success payload.
+*
+* @public
+*/
 const TestTrendsResult = Schema.Union([TrendsAvailable, TrendsAbsent]).annotate({
 	identifier: "TestTrendsResult",
 	title: "test_trends result",
@@ -92,10 +89,21 @@ const TestTrendsAsMarkdown = TestTrendsResult.pipe(Schema.decodeTo(Schema.String
 	decode: SchemaGetter.transform((data) => formatTestTrendsMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "TestTrendsAsMarkdown is one-way: markdown cannot be parsed back to TestTrendsResult.")
 }));
-const testTrends = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
-	project: Schema.String,
-	limit: Schema.optional(Schema.Number)
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `test_trends` tool's parameters.
+*
+* @public
+*/
+const TestTrendsInput = Schema.Struct({
+	project: Schema.String.annotate({ description: "Project name (required)" }),
+	limit: Schema.optionalKey(Schema.Finite).annotate({ description: "Max number of trend entries to return" })
+});
+/**
+* Handler for {@link testTrendsTool}.
+*
+* @public
+*/
+const handleTestTrends = (input) => Effect.gen(function* () {
 	const trendsOpt = yield* (yield* DataReader).getTrends(input.project, input.limit);
 	if (Option.isNone(trendsOpt) || trendsOpt.value.entries.length === 0) return {
 		dataAvailable: false,
@@ -106,7 +114,18 @@ const testTrends = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct
 		project: input.project,
 		trends: trendsOpt.value
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `test_trends` tool.
+*
+* @public
+*/
+const testTrendsTool = Tool.make("test_trends", {
+	description: "Use when you want to see whether a project's coverage is trending up or down over time. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, project, trends? }).",
+	parameters: TestTrendsInput,
+	success: TestTrendsResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Test trends").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTestTrendsMarkdown(encoded));
 
 //#endregion
-export { TestTrendsAsMarkdown, TestTrendsResult, formatTestTrendsMarkdown, testTrends };
+export { TestTrendsInput, TestTrendsResult, formatTestTrendsMarkdown, handleTestTrends, testTrendsTool };

package/tools/triage-brief.js

@@ -1,17 +1,13 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Schema } from "effect";
-import { formatTriageEffect } from "@vitest-agent/sdk";
+import { DataReader, formatTriageEffect } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/triage-brief.ts
 /**
-* `triage_brief` MCP tool — Schema-driven implementation.
+* The `triage_brief` tool's success payload.
 *
-* The structured payload is a thin envelope around the markdown
-* rendering since this is a narrative tool — there's no underlying
-* record set the agent would parse separately. The `hasContent` flag
-* lets callers branch on the cold-start case without grepping prose.
-*
-* @packageDocumentation
+* @public
 */
 const TriageBriefResult = Schema.Struct({
 	hasContent: Schema.Boolean.annotate({ description: "`false` when no orientation signal is available yet (run tests to populate)." }),
@@ -21,10 +17,21 @@ const TriageBriefResult = Schema.Struct({
 	title: "triage_brief result",
 	description: "Orientation triage envelope. Branch on `hasContent` for cold-start; consume `markdown` for rendering."
 });
-const triageBrief = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
-	project: Schema.optional(Schema.String),
-	maxLines: Schema.optional(Schema.Number)
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `triage_brief` tool's parameters.
+*
+* @public
+*/
+const TriageBriefInput = Schema.Struct({
+	project: Schema.optionalKey(Schema.String).annotate({ description: "Filter to a specific project" }),
+	maxLines: Schema.optionalKey(Schema.Finite).annotate({ description: "Soft cap on rendered output lines" })
+});
+/**
+* Handler for {@link triageBriefTool}.
+*
+* @public
+*/
+const handleTriageBrief = (input) => Effect.gen(function* () {
 	const md = yield* formatTriageEffect({
 		...input.project !== void 0 && { project: input.project },
 		...input.maxLines !== void 0 && { maxLines: input.maxLines }
@@ -36,7 +43,19 @@ const triageBrief = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struc
 		hasContent: false,
 		markdown: "No orientation signal yet — run tests to populate the database."
 	};
-})));
+});
+/**
+* The Effect-native `triage_brief` tool. The text channel is the
+* pre-rendered `markdown` field itself.
+*
+* @public
+*/
+const triageBriefTool = Tool.make("triage_brief", {
+	description: "Use when you need to orient on the current test landscape: failing tests, flaky tests, open TDD sessions, and suggested next actions. Returns markdown in content[] and a typed envelope in structuredContent ({ hasContent, markdown }).",
+	parameters: TriageBriefInput,
+	success: TriageBriefResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Triage brief").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => encoded.markdown);
 
 //#endregion
-export { TriageBriefResult, triageBrief };
+export { TriageBriefInput, TriageBriefResult, handleTriageBrief, triageBriefTool };

package/tools/turn-search.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/turn-search.ts
-/**
-* `turn_search` MCP tool — Schema-driven implementation.
-*
-* @packageDocumentation
-*/
 const TurnRow = Schema.Struct({
 	id: Schema.Finite.annotate({ description: "Numeric primary key of this turn row." }),
 	sessionId: Schema.Finite.annotate({ description: "Owning `sessions.id` (integer FK)." }),
@@ -19,6 +15,11 @@ const TurnRow = Schema.Struct({
 	identifier: "TurnRow",
 	description: "One row from the turns log."
 });
+/**
+* The `turn_search` tool's success payload.
+*
+* @public
+*/
 const TurnSearchResult = Schema.Struct({
 	count: Schema.Finite.annotate({ description: "Number of matching turn rows returned." }),
 	turns: Schema.Array(TurnRow).annotate({ description: "Matching turns ordered by `occurredAt` ascending." })
@@ -37,10 +38,15 @@ const TurnSearchAsMarkdown = TurnSearchResult.pipe(Schema.decodeTo(Schema.String
 	decode: SchemaGetter.transform((data) => formatTurnSearchMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "TurnSearchAsMarkdown is one-way: markdown cannot be parsed back to TurnSearchResult.")
 }));
-const turnSearch = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
-	sessionId: Schema.optional(Schema.Number),
-	since: Schema.optional(Schema.String),
-	type: Schema.optional(Schema.Literals([
+/**
+* The `turn_search` tool's parameters.
+*
+* @public
+*/
+const TurnSearchInput = Schema.Struct({
+	sessionId: Schema.optionalKey(Schema.Finite).annotate({ description: "Filter to a specific session id" }),
+	since: Schema.optionalKey(Schema.String).annotate({ description: "ISO 8601 cutoff — return turns after this timestamp" }),
+	type: Schema.optionalKey(Schema.Literals([
 		"user_prompt",
 		"tool_call",
 		"tool_result",
@@ -48,9 +54,15 @@ const turnSearch = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct
 		"hook_fire",
 		"note",
 		"hypothesis"
-	])),
-	limit: Schema.optional(Schema.Number)
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	])).annotate({ description: "Filter by turn type" }),
+	limit: Schema.optionalKey(Schema.Finite).annotate({ description: "Max turns to return (default 100)" })
+});
+/**
+* Handler for {@link turnSearchTool}.
+*
+* @public
+*/
+const handleTurnSearch = (input) => Effect.gen(function* () {
 	const rows = yield* (yield* DataReader).searchTurns({
 		...input.sessionId !== void 0 && { sessionId: input.sessionId },
 		...input.since !== void 0 && { since: input.since },
@@ -61,7 +73,18 @@ const turnSearch = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct
 		count: rows.length,
 		turns: rows
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `turn_search` tool.
+*
+* @public
+*/
+const turnSearchTool = Tool.make("turn_search", {
+	description: "Use when you need to find past turns across sessions by type, time, or session. Returns markdown in content[] and a typed JSON object in structuredContent ({ count, turns[] }).",
+	parameters: TurnSearchInput,
+	success: TurnSearchResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Turn search").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTurnSearchMarkdown(encoded));
 
 //#endregion
-export { TurnSearchAsMarkdown, TurnSearchResult, formatTurnSearchMarkdown, turnSearch };
+export { TurnSearchInput, TurnSearchResult, formatTurnSearchMarkdown, handleTurnSearch, turnSearchTool };

package/tools/wrapup-prompt.js

@@ -1,16 +1,13 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Schema } from "effect";
-import { formatWrapupEffect } from "@vitest-agent/sdk";
+import { DataReader, formatWrapupEffect } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/wrapup-prompt.ts
 /**
-* `wrapup_prompt` MCP tool — Schema-driven implementation.
+* The `wrapup_prompt` tool's success payload.
 *
-* Same envelope shape as `triage_brief`: thin wrapper around the
-* markdown rendering with a `hasContent` discriminant for the empty
-* case.
-*
-* @packageDocumentation
+* @public
 */
 const WrapupPromptResult = Schema.Struct({
 	hasContent: Schema.Boolean.annotate({ description: "`false` when there is nothing to wrap up for the named session/kind." }),
@@ -27,18 +24,29 @@ const WrapupPromptResult = Schema.Struct({
 	title: "wrapup_prompt result",
 	description: "Wrap-up envelope. Branch on `hasContent` for the empty case; consume `markdown` for rendering."
 });
-const wrapupPrompt = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
-	sessionId: Schema.optional(Schema.Number),
-	chatId: Schema.optional(Schema.String),
-	kind: Schema.optional(Schema.Literals([
+/**
+* The `wrapup_prompt` tool's parameters.
+*
+* @public
+*/
+const WrapupPromptInput = Schema.Struct({
+	sessionId: Schema.optionalKey(Schema.Finite).annotate({ description: "sessions.id (integer); omit to use chatId" }),
+	chatId: Schema.optionalKey(Schema.String).annotate({ description: "Host chat UUID (alternative to sessionId)" }),
+	kind: Schema.optionalKey(Schema.Literals([
 		"stop",
 		"session_end",
 		"pre_compact",
 		"tdd_handoff",
 		"user_prompt_nudge"
-	])),
-	userPromptHint: Schema.optional(Schema.String)
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+	])).annotate({ description: "Wrap-up flavor (default: session_end)" }),
+	userPromptHint: Schema.optionalKey(Schema.String).annotate({ description: "For user_prompt_nudge: the prompt text to inspect" })
+});
+/**
+* Handler for {@link wrapupPromptTool}.
+*
+* @public
+*/
+const handleWrapupPrompt = (input) => Effect.gen(function* () {
 	const kind = input.kind ?? "session_end";
 	const md = yield* formatWrapupEffect({
 		...input.sessionId !== void 0 && { sessionId: input.sessionId },
@@ -55,7 +63,19 @@ const wrapupPrompt = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Stru
 		kind,
 		markdown: "Nothing to wrap up."
 	};
-})));
+});
+/**
+* The Effect-native `wrapup_prompt` tool. The text channel is the
+* pre-rendered `markdown` field itself.
+*
+* @public
+*/
+const wrapupPromptTool = Tool.make("wrapup_prompt", {
+	description: "Use when a session is ending and you need a tailored wrap-up prompt (Stop / SessionEnd / PreCompact / TDD handoff / UserPromptSubmit nudge variants). Returns markdown in content[] and a typed envelope in structuredContent ({ hasContent, kind, markdown }).",
+	parameters: WrapupPromptInput,
+	success: WrapupPromptResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Wrap-up prompt").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => encoded.markdown);
 
 //#endregion
-export { WrapupPromptResult, wrapupPrompt };
+export { WrapupPromptInput, WrapupPromptResult, handleWrapupPrompt, wrapupPromptTool };