@vitest-agent/mcp 3.0.3 → 4.0.0

package/tools/tdd-task.js

@@ -1,20 +1,11 @@
-import { idempotentProcedure } from "../middleware/idempotency.js";
+import { RenderText } from "../annotations.js";
+import { IdempotentReplayMarker } from "../utils/replay-marker.js";
 import { Effect, Match, Option, Schema, SchemaGetter } from "effect";
-import { DataReader, DataStore, GoalDetail } from "@vitest-agent/sdk";
+import { DataReader, DataStore } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { GoalDetail } from "@vitest-agent/sdk";
 
 //#region src/tools/tdd-task.ts
-/**
-* Consolidated `tdd_task` MCP tool — Schema-driven implementation.
-*
-* `start` and `end` mutate; `get` and `resume` read. Every action
-* now returns a structured payload — `get` carries the full nested
-* `TddTaskDetail` tree plus the `currentPhase` lookup, and `resume`
-* carries a compact summary discriminated by `phaseAvailable`. The
-* boundary in server.ts uses `formatTddTaskMarkdown` to render
-* `get` / `resume` text.
-*
-* @packageDocumentation
-*/
 const TddPhaseRow = Schema.Struct({
 	id: Schema.Number,
 	behaviorId: Schema.NullOr(Schema.Number),
@@ -53,7 +44,8 @@ const TddTaskStartOk = Schema.Struct({
 	action: Schema.Literal("start"),
 	tddTaskId: Schema.Number,
 	goal: Schema.String,
-	runId: Schema.optional(Schema.String)
+	runId: Schema.optional(Schema.String),
+	...IdempotentReplayMarker
 }).annotate({ identifier: "TddTaskStartOk" });
 const TddTaskEndOk = Schema.Struct({
 	action: Schema.Literal("end"),
@@ -62,7 +54,8 @@ const TddTaskEndOk = Schema.Struct({
 		"succeeded",
 		"blocked",
 		"abandoned"
-	])
+	]),
+	...IdempotentReplayMarker
 }).annotate({ identifier: "TddTaskEndOk" });
 const TddTaskGetFound = Schema.Struct({
 	action: Schema.Literal("get"),
@@ -162,32 +155,37 @@ const TddTaskAsMarkdown = TddTaskResult.pipe(Schema.decodeTo(Schema.String, {
 	encode: SchemaGetter.forbidden(() => "TddTaskAsMarkdown is one-way.")
 }));
 const StartVariant = Schema.Struct({
-	action: Schema.Literal("start"),
-	goal: Schema.String,
-	sessionId: Schema.optional(Schema.Number),
-	chatId: Schema.optional(Schema.String),
-	parentTddTaskId: Schema.optional(Schema.Number),
-	startedAt: Schema.optional(Schema.String),
-	runId: Schema.optional(Schema.String)
+	action: Schema.Literal("start").annotate({ description: "Lifecycle discriminator" }),
+	goal: Schema.String.annotate({ description: "start: goal text" }),
+	sessionId: Schema.optionalKey(Schema.Finite).annotate({ description: "start: sessions.id (alternative to chatId)" }),
+	chatId: Schema.optionalKey(Schema.String).annotate({ description: "start: host chat UUID" }),
+	parentTddTaskId: Schema.optionalKey(Schema.Finite).annotate({ description: "start: parent task id when decomposing" }),
+	startedAt: Schema.optionalKey(Schema.String),
+	runId: Schema.optionalKey(Schema.String)
 });
 const EndVariant = Schema.Struct({
-	action: Schema.Literal("end"),
-	tddTaskId: Schema.Number,
+	action: Schema.Literal("end").annotate({ description: "Lifecycle discriminator" }),
+	tddTaskId: Schema.Finite.annotate({ description: "end/get/resume: tdd task id" }),
 	outcome: Schema.Literals([
 		"succeeded",
 		"blocked",
 		"abandoned"
-	]),
-	summaryNoteId: Schema.optional(Schema.Number)
+	]).annotate({ description: "end: final outcome" }),
+	summaryNoteId: Schema.optionalKey(Schema.Finite)
 });
 const GetVariant = Schema.Struct({
-	action: Schema.Literal("get"),
-	tddTaskId: Schema.Number
+	action: Schema.Literal("get").annotate({ description: "Lifecycle discriminator" }),
+	tddTaskId: Schema.Finite.annotate({ description: "end/get/resume: tdd task id" })
 });
 const ResumeVariant = Schema.Struct({
-	action: Schema.Literal("resume"),
-	tddTaskId: Schema.Number
+	action: Schema.Literal("resume").annotate({ description: "Lifecycle discriminator" }),
+	tddTaskId: Schema.Finite.annotate({ description: "end/get/resume: tdd task id" })
 });
+/**
+* The `tdd_task` tool's parameters — a union discriminated on `action`.
+*
+* @public
+*/
 const TddTaskInput = Schema.Union([
 	StartVariant,
 	EndVariant,
@@ -195,115 +193,119 @@ const TddTaskInput = Schema.Union([
 	ResumeVariant
 ]);
 /**
-* Single source of truth for the `tdd_task` 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 tddTaskTool}. A `start` with neither `sessionId` nor
+* `chatId`, an unknown `chatId`, or a blank `runId` fails as a defect (the
+* `UnexpectedToolError` envelope on the wire), as the retired tRPC procedure did.
+*
+* @public
 */
-const TDD_TASK_ACTIONS = [
-	"start",
-	"end",
-	"get",
-	"resume"
-];
-const tddTask = idempotentProcedure.input(Schema.toStandardSchemaV1(TddTaskInput)).mutation(async ({ ctx, input }) => {
-	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
-		start: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const store = yield* DataStore;
-			let sessionId;
-			if (variant.sessionId !== void 0) sessionId = variant.sessionId;
-			else if (variant.chatId !== void 0) {
-				const opt = yield* reader.getSessionByChatId(variant.chatId);
-				if (Option.isNone(opt)) return yield* Effect.fail(/* @__PURE__ */ new Error(`Unknown chatId: ${variant.chatId}. Run record session-start first.`));
-				sessionId = opt.value.id;
-			} else return yield* Effect.fail(/* @__PURE__ */ new Error("tdd_task action=start: provide sessionId or chatId"));
-			if (variant.runId !== void 0 && variant.runId.trim().length === 0) return yield* Effect.fail(/* @__PURE__ */ new Error("tdd_task action=start: runId must not be blank"));
-			return {
-				action: "start",
-				tddTaskId: yield* store.writeTddTask({
-					sessionId,
-					goal: variant.goal,
-					startedAt: variant.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-					...variant.runId !== void 0 && { runId: variant.runId },
-					...variant.parentTddTaskId !== void 0 && { parentTddTaskId: variant.parentTddTaskId }
-				}),
+const handleTddTask = (input) => Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+	start: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const store = yield* DataStore;
+		let sessionId;
+		if (variant.sessionId !== void 0) sessionId = variant.sessionId;
+		else if (variant.chatId !== void 0) {
+			const opt = yield* reader.getSessionByChatId(variant.chatId);
+			if (Option.isNone(opt)) return yield* Effect.fail(/* @__PURE__ */ new Error(`Unknown chatId: ${variant.chatId}. Run record session-start first.`));
+			sessionId = opt.value.id;
+		} else return yield* Effect.fail(/* @__PURE__ */ new Error("tdd_task action=start: provide sessionId or chatId"));
+		if (variant.runId !== void 0 && variant.runId.trim().length === 0) return yield* Effect.fail(/* @__PURE__ */ new Error("tdd_task action=start: runId must not be blank"));
+		return {
+			action: "start",
+			tddTaskId: yield* store.writeTddTask({
+				sessionId,
 				goal: variant.goal,
-				...variant.runId !== void 0 && { runId: variant.runId }
-			};
-		}),
-		end: (variant) => Effect.gen(function* () {
-			yield* (yield* DataStore).endTddTask({
-				id: variant.tddTaskId,
-				outcome: variant.outcome,
-				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
-				...variant.summaryNoteId !== void 0 && { summaryNoteId: variant.summaryNoteId }
-			});
-			return {
-				action: "end",
-				tddTaskId: variant.tddTaskId,
-				outcome: variant.outcome
-			};
-		}),
-		get: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const opt = yield* reader.getTddTaskById(variant.tddTaskId);
-			if (Option.isNone(opt)) return {
-				action: "get",
-				found: false,
-				tddTaskId: variant.tddTaskId
-			};
-			const currentOpt = yield* reader.getCurrentTddPhase(variant.tddTaskId);
-			const { id, ...rest } = opt.value;
-			return {
-				action: "get",
-				found: true,
-				task: {
-					tddTaskId: id,
-					...rest
-				},
-				currentPhase: Option.match(currentOpt, {
-					onNone: () => null,
-					onSome: (p) => ({
-						id: p.id,
-						phase: p.phase,
-						startedAt: p.startedAt,
-						behaviorId: p.behaviorId
-					})
+				startedAt: variant.startedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+				...variant.runId !== void 0 && { runId: variant.runId },
+				...variant.parentTddTaskId !== void 0 && { parentTddTaskId: variant.parentTddTaskId }
+			}),
+			goal: variant.goal,
+			...variant.runId !== void 0 && { runId: variant.runId }
+		};
+	}),
+	end: (variant) => Effect.gen(function* () {
+		yield* (yield* DataStore).endTddTask({
+			id: variant.tddTaskId,
+			outcome: variant.outcome,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...variant.summaryNoteId !== void 0 && { summaryNoteId: variant.summaryNoteId }
+		});
+		return {
+			action: "end",
+			tddTaskId: variant.tddTaskId,
+			outcome: variant.outcome
+		};
+	}),
+	get: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const opt = yield* reader.getTddTaskById(variant.tddTaskId);
+		if (Option.isNone(opt)) return {
+			action: "get",
+			found: false,
+			tddTaskId: variant.tddTaskId
+		};
+		const currentOpt = yield* reader.getCurrentTddPhase(variant.tddTaskId);
+		const { id, ...rest } = opt.value;
+		return {
+			action: "get",
+			found: true,
+			task: {
+				tddTaskId: id,
+				...rest
+			},
+			currentPhase: Option.match(currentOpt, {
+				onNone: () => null,
+				onSome: (p) => ({
+					id: p.id,
+					phase: p.phase,
+					startedAt: p.startedAt,
+					behaviorId: p.behaviorId
 				})
-			};
-		}),
-		resume: (variant) => Effect.gen(function* () {
-			const reader = yield* DataReader;
-			const tddOpt = yield* reader.getTddTaskById(variant.tddTaskId);
-			if (Option.isNone(tddOpt)) return {
-				action: "resume",
-				found: false,
-				tddTaskId: variant.tddTaskId
-			};
-			const tdd = tddOpt.value;
-			const currentOpt = yield* reader.getCurrentTddPhase(variant.tddTaskId);
-			return {
-				action: "resume",
-				found: true,
-				tddTaskId: tdd.id,
-				goal: tdd.goal,
-				status: tdd.outcome ?? "in progress",
-				currentPhase: Option.match(currentOpt, {
-					onNone: () => null,
-					onSome: (p) => ({
-						id: p.id,
-						phase: p.phase,
-						startedAt: p.startedAt,
-						behaviorId: p.behaviorId
-					})
-				}),
-				phasesRecorded: tdd.phases.length,
-				artifactsRecorded: tdd.artifacts.length
-			};
-		})
-	})));
-});
+			})
+		};
+	}),
+	resume: (variant) => Effect.gen(function* () {
+		const reader = yield* DataReader;
+		const tddOpt = yield* reader.getTddTaskById(variant.tddTaskId);
+		if (Option.isNone(tddOpt)) return {
+			action: "resume",
+			found: false,
+			tddTaskId: variant.tddTaskId
+		};
+		const tdd = tddOpt.value;
+		const currentOpt = yield* reader.getCurrentTddPhase(variant.tddTaskId);
+		return {
+			action: "resume",
+			found: true,
+			tddTaskId: tdd.id,
+			goal: tdd.goal,
+			status: tdd.outcome ?? "in progress",
+			currentPhase: Option.match(currentOpt, {
+				onNone: () => null,
+				onSome: (p) => ({
+					id: p.id,
+					phase: p.phase,
+					startedAt: p.startedAt,
+					behaviorId: p.behaviorId
+				})
+			}),
+			phasesRecorded: tdd.phases.length,
+			artifactsRecorded: tdd.artifacts.length
+		};
+	})
+})).pipe(Effect.orDie);
+/**
+* The Effect-native `tdd_task` tool.
+*
+* @public
+*/
+const tddTaskTool = Tool.make("tdd_task", {
+	description: "Use to manage a TDD task lifecycle, with an action discriminator: action='start' (goal, sessionId|chatId, parentTddTaskId?, startedAt?, runId?) opens a new task; action='end' (tddTaskId, outcome, summaryNoteId?) closes one; action='get' (tddTaskId) returns markdown details; action='resume' (tddTaskId) returns a compact digest.",
+	parameters: TddTaskInput,
+	success: TddTaskResult,
+	dependencies: [DataReader, DataStore]
+}).annotate(Tool.Title, "TDD task").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTddTaskMarkdown(encoded));
 
 //#endregion
-export { TDD_TASK_ACTIONS, TddTaskAsMarkdown, TddTaskResult, formatTddTaskMarkdown, tddTask };
+export { TddTaskInput, TddTaskResult, formatTddTaskMarkdown, handleTddTask, tddTaskTool };