@vitest-agent/mcp 3.0.3 → 4.0.0

package/tools/inventory.js

@@ -1,21 +1,10 @@
-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/inventory.ts
-/**
-* Consolidated `inventory` MCP tool — Schema-driven implementation.
-*
-* Each `kind` produces a structured result that the boundary in
-* server.ts can render as markdown via the exported
-* `formatInventoryMarkdown` helper. The structured payload uses an
-* `inventoryKind` discriminant (named separately from the input
-* `kind` because `session` collapses to two output shapes — one for
-* single-id lookup and one for list).
-*
-* @packageDocumentation
-*/
 const ProjectRunSummary = Schema.Struct({
 	project: Schema.String,
 	lastRun: Schema.NullOr(Schema.String),
@@ -121,6 +110,11 @@ const TagInventoryUnscoped = Schema.Struct({
 	count: Schema.Number,
 	tags: Schema.Array(TagRowUnscoped)
 }).annotate({ identifier: "TagInventoryUnscoped" });
+/**
+* The `inventory` tool's success payload.
+*
+* @public
+*/
 const InventoryResult = Schema.Union([
 	ProjectInventory,
 	ModuleInventory,
@@ -230,24 +224,31 @@ const InventoryAsMarkdown = InventoryResult.pipe(Schema.decodeTo(Schema.String,
 const ProjectVariant = Schema.Struct({ kind: Schema.Literal("project") });
 const ModuleVariant = Schema.Struct({
 	kind: Schema.Literal("module"),
-	project: Schema.optional(Schema.String)
+	project: Schema.optionalKey(Schema.String)
 });
 const SuiteVariant = Schema.Struct({
 	kind: Schema.Literal("suite"),
-	project: Schema.optional(Schema.String),
-	module: Schema.optional(Schema.String)
+	project: Schema.optionalKey(Schema.String),
+	module: Schema.optionalKey(Schema.String).annotate({ description: "suite: filter by module path" })
 });
 const SessionVariant = Schema.Struct({
 	kind: Schema.Literal("session"),
-	id: Schema.optional(Schema.Number),
-	project: Schema.optional(Schema.String),
-	agentKind: Schema.optional(Schema.Literals(["main", "subagent"])),
-	limit: Schema.optional(Schema.Number)
+	id: Schema.optionalKey(Schema.Finite).annotate({ description: "session: single-row lookup by id" }),
+	project: Schema.optionalKey(Schema.String),
+	agentKind: Schema.optionalKey(Schema.Literals(["main", "subagent"])).annotate({ description: "session: filter by agent kind" }),
+	limit: Schema.optionalKey(Schema.Finite).annotate({ description: "session: max rows" })
 });
 const TagVariant = Schema.Struct({
 	kind: Schema.Literal("tag"),
-	project: Schema.optional(Schema.String)
+	project: Schema.optionalKey(Schema.String)
 });
+/**
+* The `inventory` tool's parameters — a union discriminated on `kind`.
+* The served JSON Schema is a `oneOf` over the variants with
+* `x-discriminator: "kind"`.
+*
+* @public
+*/
 const InventoryInput = Schema.Union([
 	ProjectVariant,
 	ModuleVariant,
@@ -256,137 +257,139 @@ const InventoryInput = Schema.Union([
 	TagVariant
 ]);
 /**
-* Single source of truth for the `inventory` tool's `kind` 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 inventoryTool}.
+*
+* @public
 */
-const INVENTORY_KINDS = [
-	"project",
-	"module",
-	"suite",
-	"session",
-	"tag"
-];
-const inventory = publicProcedure.input(Schema.toStandardSchemaV1(InventoryInput)).query(async ({ ctx, input }) => {
-	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("kind")({
-		project: () => Effect.gen(function* () {
-			const projects = yield* (yield* DataReader).getRunsByProject();
-			return {
-				inventoryKind: "project",
-				count: projects.length,
-				projects: projects.map((p) => ({
-					project: p.project,
-					lastRun: p.lastRun,
-					lastResult: p.lastResult,
-					total: p.total,
-					passed: p.passed,
-					failed: p.failed,
-					skipped: p.skipped
-				}))
+const handleInventory = (input) => Match.value(input).pipe(Match.discriminatorsExhaustive("kind")({
+	project: () => Effect.gen(function* () {
+		const projects = yield* (yield* DataReader).getRunsByProject();
+		return {
+			inventoryKind: "project",
+			count: projects.length,
+			projects: projects.map((p) => ({
+				project: p.project,
+				lastRun: p.lastRun,
+				lastResult: p.lastResult,
+				total: p.total,
+				passed: p.passed,
+				failed: p.failed,
+				skipped: p.skipped
+			}))
+		};
+	}),
+	module: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
+		const grouped = yield* collectProjectRows(targets, (project) => reader.listModules(project));
+		return {
+			inventoryKind: "module",
+			count: grouped.total,
+			groups: grouped.groups.map((group) => ({
+				project: group.project,
+				modules: group.rows
+			}))
+		};
+	}),
+	suite: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const opts = {};
+		if (variant.module !== void 0) opts.module = variant.module;
+		const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
+		const grouped = yield* collectProjectRows(targets, (project) => reader.listSuites(project, opts));
+		return {
+			inventoryKind: "suite",
+			count: grouped.total,
+			groups: grouped.groups.map((group) => ({
+				project: group.project,
+				suites: group.rows
+			}))
+		};
+	}),
+	session: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		if (variant.id !== void 0) {
+			const opt = yield* reader.getSessionById(variant.id);
+			return Option.isNone(opt) ? {
+				inventoryKind: "session_detail",
+				found: false,
+				id: variant.id
+			} : {
+				inventoryKind: "session_detail",
+				found: true,
+				session: opt.value
 			};
-		}),
-		module: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
-			const grouped = yield* collectProjectRows(targets, (project) => reader.listModules(project));
-			return {
-				inventoryKind: "module",
-				count: grouped.total,
-				groups: grouped.groups.map((group) => ({
-					project: group.project,
-					modules: group.rows
-				}))
-			};
-		}),
-		suite: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const opts = {};
-			if (variant.module !== void 0) opts.module = variant.module;
-			const targets = yield* resolveProjectTargets(variant.project, () => reader.getRunsByProject());
-			const grouped = yield* collectProjectRows(targets, (project) => reader.listSuites(project, opts));
+		}
+		const rows = yield* reader.listSessions({
+			...variant.project !== void 0 && { project: variant.project },
+			...variant.agentKind !== void 0 && { agentKind: variant.agentKind },
+			...variant.limit !== void 0 && { limit: variant.limit }
+		});
+		return {
+			inventoryKind: "session_list",
+			count: rows.length,
+			sessions: rows
+		};
+	}),
+	tag: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		if (variant.project !== void 0) {
+			const rows = yield* reader.listTagInventory({ project: variant.project });
 			return {
-				inventoryKind: "suite",
-				count: grouped.total,
-				groups: grouped.groups.map((group) => ({
-					project: group.project,
-					suites: group.rows
+				inventoryKind: "tag_scoped",
+				project: variant.project,
+				count: rows.length,
+				tags: rows.map((r) => ({
+					tag: r.tag,
+					moduleCount: r.moduleCount,
+					testCount: r.testCount
 				}))
 			};
-		}),
-		session: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			if (variant.id !== void 0) {
-				const opt = yield* reader.getSessionById(variant.id);
-				return Option.isNone(opt) ? {
-					inventoryKind: "session_detail",
-					found: false,
-					id: variant.id
-				} : {
-					inventoryKind: "session_detail",
-					found: true,
-					session: opt.value
+		}
+		const rows = yield* reader.listTagInventory();
+		const byTag = /* @__PURE__ */ new Map();
+		for (const r of rows) {
+			let entry = byTag.get(r.tag);
+			if (entry === void 0) {
+				entry = {
+					moduleCount: 0,
+					testCount: 0,
+					byProject: []
 				};
+				byTag.set(r.tag, entry);
 			}
-			const rows = yield* reader.listSessions({
-				...variant.project !== void 0 && { project: variant.project },
-				...variant.agentKind !== void 0 && { agentKind: variant.agentKind },
-				...variant.limit !== void 0 && { limit: variant.limit }
+			entry.moduleCount += r.moduleCount;
+			entry.testCount += r.testCount;
+			entry.byProject.push({
+				project: r.project,
+				moduleCount: r.moduleCount,
+				testCount: r.testCount
 			});
-			return {
-				inventoryKind: "session_list",
-				count: rows.length,
-				sessions: rows
-			};
-		}),
-		tag: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			if (variant.project !== void 0) {
-				const rows = yield* reader.listTagInventory({ project: variant.project });
-				return {
-					inventoryKind: "tag_scoped",
-					project: variant.project,
-					count: rows.length,
-					tags: rows.map((r) => ({
-						tag: r.tag,
-						moduleCount: r.moduleCount,
-						testCount: r.testCount
-					}))
-				};
-			}
-			const rows = yield* reader.listTagInventory();
-			const byTag = /* @__PURE__ */ new Map();
-			for (const r of rows) {
-				let entry = byTag.get(r.tag);
-				if (entry === void 0) {
-					entry = {
-						moduleCount: 0,
-						testCount: 0,
-						byProject: []
-					};
-					byTag.set(r.tag, entry);
-				}
-				entry.moduleCount += r.moduleCount;
-				entry.testCount += r.testCount;
-				entry.byProject.push({
-					project: r.project,
-					moduleCount: r.moduleCount,
-					testCount: r.testCount
-				});
-			}
-			const tags = Array.from(byTag.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([tag, e]) => ({
-				tag,
-				moduleCount: e.moduleCount,
-				testCount: e.testCount,
-				byProject: e.byProject
-			}));
-			return {
-				inventoryKind: "tag_unscoped",
-				count: tags.length,
-				tags
-			};
-		})
-	})));
-});
+		}
+		const tags = Array.from(byTag.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([tag, e]) => ({
+			tag,
+			moduleCount: e.moduleCount,
+			testCount: e.testCount,
+			byProject: e.byProject
+		}));
+		return {
+			inventoryKind: "tag_unscoped",
+			count: tags.length,
+			tags
+		};
+	})
+})).pipe(Effect.orDie);
+/**
+* The Effect-native `inventory` tool.
+*
+* @public
+*/
+const inventoryTool = Tool.make("inventory", {
+	description: "Use to discover what exists in the workspace, with a kind discriminator: project / module / suite / session / tag. structuredContent discriminates on `inventoryKind` (project, module, suite, session_detail, session_list, tag_scoped, tag_unscoped) so callers can branch on the response shape without parsing markdown.",
+	parameters: InventoryInput,
+	success: InventoryResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Inventory").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatInventoryMarkdown(encoded));
 
 //#endregion
-export { INVENTORY_KINDS, InventoryAsMarkdown, InventoryResult, formatInventoryMarkdown, inventory };
+export { InventoryInput, InventoryResult, formatInventoryMarkdown, handleInventory, inventoryTool };

package/tools/note.js

@@ -1,6 +1,7 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Match, Option, Schema } from "effect";
-import { DataReader, DataStore } from "@vitest-agent/sdk";
+import { DataReader, DataStore } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/note.ts
 const NoteScope = Schema.Literals([
@@ -59,6 +60,11 @@ const NoteSearchOk = Schema.Struct({
 	count: Schema.Number,
 	notes: Schema.Array(NoteRowSchema).annotate({ description: "Notes whose title or content match the FTS5 query." })
 });
+/**
+* The `note` tool's success payload.
+*
+* @public
+*/
 const NoteResult = Schema.Union([
 	NoteCreateOk,
 	NoteListOk,
@@ -105,46 +111,57 @@ const formatNoteListMarkdown = (data) => {
 	}
 	return JSON.stringify(data, null, 2);
 };
+/**
+* The text channel: list/search render markdown; the mutation actions
+* (create/get/update/delete) render the pretty-printed JSON, exactly as
+* the old `structuredJsonResult` boundary did.
+*/
+const renderNoteText = (data) => data.action === "list" || data.action === "search" ? formatNoteListMarkdown(data) : JSON.stringify(data, null, 2);
 const CreateVariant = Schema.Struct({
-	action: Schema.Literal("create"),
+	action: Schema.Literal("create").annotate({ description: "CRUD discriminator" }),
 	title: Schema.String,
 	content: Schema.String,
-	scope: NoteScope,
-	project: Schema.optional(Schema.String),
-	testFullName: Schema.optional(Schema.String),
-	modulePath: Schema.optional(Schema.String),
-	parentNoteId: Schema.optional(Schema.Number),
-	createdBy: Schema.optional(Schema.String),
-	expiresAt: Schema.optional(Schema.String),
-	pinned: Schema.optional(Schema.Boolean)
+	scope: NoteScope.annotate({ description: "create: required scope; list: optional filter" }),
+	project: Schema.optionalKey(Schema.String),
+	testFullName: Schema.optionalKey(Schema.String),
+	modulePath: Schema.optionalKey(Schema.String),
+	parentNoteId: Schema.optionalKey(Schema.Finite),
+	createdBy: Schema.optionalKey(Schema.String),
+	expiresAt: Schema.optionalKey(Schema.String),
+	pinned: Schema.optionalKey(Schema.Boolean)
 });
 const ListVariant = Schema.Struct({
-	action: Schema.Literal("list"),
-	scope: Schema.optional(Schema.String),
-	project: Schema.optional(Schema.String),
-	testFullName: Schema.optional(Schema.String)
+	action: Schema.Literal("list").annotate({ description: "CRUD discriminator" }),
+	scope: Schema.optionalKey(NoteScope).annotate({ description: "create: required scope; list: optional filter" }),
+	project: Schema.optionalKey(Schema.String),
+	testFullName: Schema.optionalKey(Schema.String)
 });
 const GetVariant = Schema.Struct({
-	action: Schema.Literal("get"),
-	id: Schema.Number
+	action: Schema.Literal("get").annotate({ description: "CRUD discriminator" }),
+	id: Schema.Finite.annotate({ description: "get/update/delete: note id" })
 });
 const UpdateVariant = Schema.Struct({
-	action: Schema.Literal("update"),
-	id: Schema.Number,
-	title: Schema.optional(Schema.String),
-	content: Schema.optional(Schema.String),
-	pinned: Schema.optional(Schema.Boolean),
-	expiresAt: Schema.optional(Schema.String)
+	action: Schema.Literal("update").annotate({ description: "CRUD discriminator" }),
+	id: Schema.Finite.annotate({ description: "get/update/delete: note id" }),
+	title: Schema.optionalKey(Schema.String),
+	content: Schema.optionalKey(Schema.String),
+	pinned: Schema.optionalKey(Schema.Boolean),
+	expiresAt: Schema.optionalKey(Schema.String)
 });
 const DeleteVariant = Schema.Struct({
-	action: Schema.Literal("delete"),
-	id: Schema.Number
+	action: Schema.Literal("delete").annotate({ description: "CRUD discriminator" }),
+	id: Schema.Finite.annotate({ description: "get/update/delete: note id" })
 });
 const SearchVariant = Schema.Struct({
-	action: Schema.Literal("search"),
-	query: Schema.String
+	action: Schema.Literal("search").annotate({ description: "CRUD discriminator" }),
+	query: Schema.String.annotate({ description: "search: FTS5 query" })
 });
-const NoteInputUnion = Schema.Union([
+/**
+* The `note` tool's parameters — a union discriminated on `action`.
+*
+* @public
+*/
+const NoteParams = Schema.Union([
 	CreateVariant,
 	ListVariant,
 	GetVariant,
@@ -153,91 +170,92 @@ const NoteInputUnion = Schema.Union([
 	SearchVariant
 ]);
 /**
-* Single source of truth for the `note` 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 noteTool}.
+*
+* @public
 */
-const NOTE_ACTIONS = [
-	"create",
-	"list",
-	"get",
-	"update",
-	"delete",
-	"search"
-];
-const note = publicProcedure.input(Schema.toStandardSchemaV1(NoteInputUnion)).mutation(async ({ ctx, input }) => {
-	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
-		create: (variant) => Effect.gen(function* () {
-			const store = yield* DataStore;
-			const noteInput = {
-				title: variant.title,
-				content: variant.content,
-				scope: variant.scope,
-				...variant.project !== void 0 && { project: variant.project },
-				...variant.testFullName !== void 0 && { testFullName: variant.testFullName },
-				...variant.modulePath !== void 0 && { modulePath: variant.modulePath },
-				...variant.parentNoteId !== void 0 && { parentNoteId: variant.parentNoteId },
-				...variant.createdBy !== void 0 && { createdBy: variant.createdBy },
-				...variant.expiresAt !== void 0 && { expiresAt: variant.expiresAt },
-				...variant.pinned !== void 0 && { pinned: variant.pinned }
-			};
-			return {
-				action: "create",
-				id: yield* store.writeNote(noteInput)
-			};
-		}),
-		list: (variant) => Effect.gen(function* () {
-			const notes = yield* (yield* DataReader).getNotes(variant.scope, variant.project, variant.testFullName);
-			return {
-				action: "list",
-				count: notes.length,
-				notes
-			};
-		}),
-		get: (variant) => Effect.gen(function* () {
-			const noteOpt = yield* (yield* DataReader).getNoteById(variant.id);
-			return Option.isNone(noteOpt) ? {
-				action: "get",
-				found: false,
-				id: variant.id
-			} : {
-				action: "get",
-				found: true,
-				note: noteOpt.value
-			};
-		}),
-		update: (variant) => Effect.gen(function* () {
-			const store = yield* DataStore;
-			const fields = {
-				...variant.title !== void 0 && { title: variant.title },
-				...variant.content !== void 0 && { content: variant.content },
-				...variant.pinned !== void 0 && { pinned: variant.pinned },
-				...variant.expiresAt !== void 0 && { expiresAt: variant.expiresAt }
-			};
-			yield* store.updateNote(variant.id, fields);
-			return {
-				action: "update",
-				success: true
-			};
-		}),
-		delete: (variant) => Effect.gen(function* () {
-			yield* (yield* DataStore).deleteNote(variant.id);
-			return {
-				action: "delete",
-				success: true
-			};
-		}),
-		search: (variant) => Effect.gen(function* () {
-			const notes = yield* (yield* DataReader).searchNotes(variant.query);
-			return {
-				action: "search",
-				query: variant.query,
-				count: notes.length,
-				notes
-			};
-		})
-	})));
-});
+const handleNote = (input) => Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+	create: (variant) => Effect.gen(function* () {
+		const store = yield* DataStore;
+		const noteInput = {
+			title: variant.title,
+			content: variant.content,
+			scope: variant.scope,
+			...variant.project !== void 0 && { project: variant.project },
+			...variant.testFullName !== void 0 && { testFullName: variant.testFullName },
+			...variant.modulePath !== void 0 && { modulePath: variant.modulePath },
+			...variant.parentNoteId !== void 0 && { parentNoteId: variant.parentNoteId },
+			...variant.createdBy !== void 0 && { createdBy: variant.createdBy },
+			...variant.expiresAt !== void 0 && { expiresAt: variant.expiresAt },
+			...variant.pinned !== void 0 && { pinned: variant.pinned }
+		};
+		return {
+			action: "create",
+			id: yield* store.writeNote(noteInput)
+		};
+	}),
+	list: (variant) => Effect.gen(function* () {
+		const notes = yield* (yield* DataReader).getNotes(variant.scope, variant.project, variant.testFullName);
+		return {
+			action: "list",
+			count: notes.length,
+			notes
+		};
+	}),
+	get: (variant) => Effect.gen(function* () {
+		const noteOpt = yield* (yield* DataReader).getNoteById(variant.id);
+		return Option.isNone(noteOpt) ? {
+			action: "get",
+			found: false,
+			id: variant.id
+		} : {
+			action: "get",
+			found: true,
+			note: noteOpt.value
+		};
+	}),
+	update: (variant) => Effect.gen(function* () {
+		const store = yield* DataStore;
+		const fields = {
+			...variant.title !== void 0 && { title: variant.title },
+			...variant.content !== void 0 && { content: variant.content },
+			...variant.pinned !== void 0 && { pinned: variant.pinned },
+			...variant.expiresAt !== void 0 && { expiresAt: variant.expiresAt }
+		};
+		yield* store.updateNote(variant.id, fields);
+		return {
+			action: "update",
+			success: true
+		};
+	}),
+	delete: (variant) => Effect.gen(function* () {
+		yield* (yield* DataStore).deleteNote(variant.id);
+		return {
+			action: "delete",
+			success: true
+		};
+	}),
+	search: (variant) => Effect.gen(function* () {
+		const notes = yield* (yield* DataReader).searchNotes(variant.query);
+		return {
+			action: "search",
+			query: variant.query,
+			count: notes.length,
+			notes
+		};
+	})
+})).pipe(Effect.orDie);
+/**
+* The Effect-native `note` tool.
+*
+* @public
+*/
+const noteTool = Tool.make("note", {
+	description: "Use to manage notes, with a CRUD action discriminator: action='create' writes a scoped note; action='list' (scope?, project?, testFullName?) returns matching notes; action='get' (id) returns a structured note; action='update' (id, ...patch) edits; action='delete' (id) removes; action='search' (query) does FTS5 across title and content. structuredContent always carries the typed result (discriminate on `action`); list/search additionally render markdown in the text channel.",
+	parameters: NoteParams,
+	success: NoteResult,
+	dependencies: [DataReader, DataStore]
+}).annotate(Tool.Title, "Note").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false).annotate(RenderText, (encoded) => renderNoteText(encoded));
 
 //#endregion
-export { NOTE_ACTIONS, NoteResult, formatNoteListMarkdown, note };
+export { NoteParams, NoteResult, formatNoteListMarkdown, handleNote, noteTool };