@vitest-agent/mcp 3.0.4 → 4.0.0

package/tools/failure-signature-get.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/failure-signature-get.ts
-/**
-* `failure_signature_get` MCP tool — Schema-driven implementation.
-*
-* @packageDocumentation
-*/
 const RecentError = Schema.Struct({
 	runId: Schema.Number,
 	errorName: Schema.NullOr(Schema.String),
@@ -29,6 +25,11 @@ const SignatureMissing = Schema.Struct({
 	found: Schema.Literal(false),
 	requestedHash: Schema.String
 });
+/**
+* The `failure_signature_get` tool's success payload.
+*
+* @public
+*/
 const FailureSignatureGetResult = Schema.Union([SignatureFound, SignatureMissing]).annotate({
 	identifier: "FailureSignatureGetResult",
 	title: "failure_signature_get result",
@@ -56,7 +57,18 @@ const FailureSignatureGetAsMarkdown = FailureSignatureGetResult.pipe(Schema.deco
 	decode: SchemaGetter.transform((data) => formatFailureSignatureMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "FailureSignatureGetAsMarkdown is one-way.")
 }));
-const failureSignatureGet = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({ hash: Schema.String }))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `failure_signature_get` tool's parameters.
+*
+* @public
+*/
+const FailureSignatureGetInput = Schema.Struct({ hash: Schema.String.annotate({ description: "16-char failure signature hash" }) });
+/**
+* Handler for {@link failureSignatureGetTool}.
+*
+* @public
+*/
+const handleFailureSignatureGet = (input) => Effect.gen(function* () {
 	const opt = yield* (yield* DataReader).getFailureSignatureByHash(input.hash);
 	if (Option.isNone(opt)) return {
 		found: false,
@@ -66,7 +78,18 @@ const failureSignatureGet = publicProcedure.input(Schema.toStandardSchemaV1(Sche
 		found: true,
 		...opt.value
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `failure_signature_get` tool.
+*
+* @public
+*/
+const failureSignatureGetTool = Tool.make("failure_signature_get", {
+	description: "Use when you have a failure-signature hash and need its first-seen date and occurrence history. Returns markdown in content[] and a typed JSON object in structuredContent ({ found, signatureHash?, firstSeenAt?, occurrenceCount?, recentErrors?[] } or absent variant).",
+	parameters: FailureSignatureGetInput,
+	success: FailureSignatureGetResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Failure signature").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatFailureSignatureMarkdown(encoded));
 
 //#endregion
-export { FailureSignatureGetAsMarkdown, FailureSignatureGetResult, failureSignatureGet, formatFailureSignatureMarkdown };
+export { FailureSignatureGetInput, FailureSignatureGetResult, failureSignatureGetTool, formatFailureSignatureMarkdown, handleFailureSignatureGet };

package/tools/file-coverage.js

@@ -1,13 +1,10 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Option, Schema, SchemaGetter } from "effect";
-import { CoverageTotals, DataReader, FileCoverageReport } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { CoverageTotals, FileCoverageReport } from "@vitest-agent/sdk";
 
 //#region src/tools/file-coverage.ts
-/**
-* `file_coverage` MCP tool — Schema-driven implementation.
-*
-* @packageDocumentation
-*/
 const CoverageGlobalThresholds = Schema.Struct({
 	statements: Schema.optional(Schema.Number),
 	branches: Schema.optional(Schema.Number),
@@ -33,6 +30,11 @@ const FileCoverageAbsent = Schema.Struct({
 	dataAvailable: Schema.Literal(false),
 	filePath: Schema.String
 }).annotate({ identifier: "FileCoverageAbsent" });
+/**
+* The `file_coverage` tool's success payload.
+*
+* @public
+*/
 const FileCoverageResult = Schema.Union([
 	FileCoverageMatched,
 	FileCoverageNoMatch,
@@ -73,10 +75,21 @@ const FileCoverageAsMarkdown = FileCoverageResult.pipe(Schema.decodeTo(Schema.St
 	decode: SchemaGetter.transform((data) => formatFileCoverageMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "FileCoverageAsMarkdown is one-way.")
 }));
-const fileCoverage = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
-	filePath: Schema.String,
-	project: Schema.optional(Schema.String)
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `file_coverage` tool's parameters.
+*
+* @public
+*/
+const FileCoverageInput = Schema.Struct({
+	filePath: Schema.String.annotate({ description: "Source file path to check coverage for" }),
+	project: Schema.optionalKey(Schema.String).annotate({ description: "Project name" })
+});
+/**
+* Handler for {@link fileCoverageTool}.
+*
+* @public
+*/
+const handleFileCoverage = (input) => Effect.gen(function* () {
 	const reader = yield* DataReader;
 	const project = input.project ?? "default";
 	const coverageOpt = yield* reader.getCoverage(project);
@@ -103,7 +116,18 @@ const fileCoverage = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Stru
 		totals: coverage.totals,
 		relatedTestFiles
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `file_coverage` tool.
+*
+* @public
+*/
+const fileCoverageTool = Tool.make("file_coverage", {
+	description: "Use when you need coverage for one source file: per-metric values, uncovered lines, and related tests. Returns markdown in content[] and a typed JSON object in structuredContent ({ dataAvailable, matched?, filePath, report?, totals?, relatedTestFiles[] }).",
+	parameters: FileCoverageInput,
+	success: FileCoverageResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "File coverage").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatFileCoverageMarkdown(encoded));
 
 //#endregion
-export { FileCoverageAsMarkdown, FileCoverageResult, fileCoverage, formatFileCoverageMarkdown };
+export { FileCoverageInput, FileCoverageResult, fileCoverageTool, formatFileCoverageMarkdown, handleFileCoverage };

package/tools/help.js

@@ -1,12 +1,24 @@
-import { publicProcedure } from "../context.js";
-import { Schema } from "effect";
+import { RenderText } from "../annotations.js";
+import { Effect, Schema } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/help.ts
+/**
+* The `help` tool's success payload.
+*
+* @public
+*/
 const HelpResult = Schema.Struct({ helpText: Schema.String.annotate({ description: "Markdown table of every MCP tool with parameters and a one-line description." }) }).annotate({
 	identifier: "HelpResult",
 	title: "help result",
 	description: "Static help reference. Read structuredContent.helpText programmatically; the same string lives in content[].text for transcripts."
 });
+/**
+* The static markdown `help` returns. Exported so `__test__/help-drift.test.ts`
+* can pin its tool and prompt rows to the served toolkit and prompt layer.
+*
+* @internal
+*/
 const HELP_TEXT = `# vitest-agent MCP Tools
 
 > Consolidated tool surface (Phase 3 of the agent-agnostic taxonomy).
@@ -135,6 +147,19 @@ const HELP_TEXT = `# vitest-agent MCP Tools
 - \`{ action: "list_by_goal", goalId }\`
 - \`{ action: "list_by_tdd_task", tddTaskId }\`
 
+## Prompts
+
+Six framing-only prompts (\`prompts/get\`; Claude Code surfaces them as slash commands):
+
+| Prompt | Arguments | Description |
+| ------ | --------- | ----------- |
+| \`triage\` | \`project?\` | Orient toward a triage workflow over the most recent run |
+| \`why-flaky\` | \`test\`, \`project?\` | Diagnose why a named test is flaky |
+| \`regression-since-pass\` | \`test\`, \`project?\` | Walk back from the last passing run to the change that broke it |
+| \`explain-failure\` | \`signature\` | Root-cause explanation from a failure signature's recurrence history |
+| \`tdd-resume\` | \`sessionId?\` | Resume the active TDD task from its current phase |
+| \`wrapup\` | \`kind?\`, \`since?\` | The same wrap-up content the post-hooks emit automatically |
+
 ## Parameter Key
 
 - **Required** parameters are unmarked
@@ -143,7 +168,23 @@ const HELP_TEXT = `# vitest-agent MCP Tools
 - \`state\` accepts: \`passed\`, \`failed\`, \`skipped\`, \`pending\`
 - \`scope\` accepts: \`global\`, \`project\`, \`module\`, \`suite\`, \`test\`, \`note\`
 `;
-const help = publicProcedure.query(() => ({ helpText: HELP_TEXT }));
+/**
+* The Effect-native `help` tool. Renders the help markdown as the text
+* channel via `RenderText` while `structuredContent.helpText` carries the
+* same string for programmatic readers.
+*
+* @public
+*/
+const helpTool = Tool.make("help", {
+	description: "List all available MCP tools with parameters. Read structuredContent.helpText programmatically; the same markdown lives in content[].text.",
+	success: HelpResult
+}).annotate(Tool.Title, "Help").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => encoded.helpText);
+/**
+* Handler for {@link helpTool}.
+*
+* @public
+*/
+const handleHelp = () => Effect.succeed({ helpText: HELP_TEXT });
 
 //#endregion
-export { HelpResult, help };
+export { HELP_TEXT, HelpResult, handleHelp, helpTool };

package/tools/history.js

@@ -1,17 +1,10 @@
-import { publicProcedure } from "../context.js";
+import { RenderText } from "../annotations.js";
 import { Effect, Schema, SchemaGetter } from "effect";
-import { DataReader, HistoryRecord } from "@vitest-agent/sdk";
+import { DataReader } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { HistoryRecord } from "@vitest-agent/sdk";
 
 //#region src/tools/history.ts
-/**
-* `test_history` MCP tool — Schema-driven implementation.
-*
-* The structured payload bundles the underlying `HistoryRecord` plus
-* the lighter `flaky` / `persistent` projections the UI uses, so an
-* agent doesn't need to recompute them from runs[].
-*
-* @packageDocumentation
-*/
 const FlakyTestRow = Schema.Struct({
 	fullName: Schema.String.annotate({ description: "Full hierarchical test name (`describe > it`)." }),
 	modulePath: Schema.String.annotate({ description: "Project-relative test module path -- disambiguates same-named tests across files." }),
@@ -44,6 +37,11 @@ const RecoveredTestRow = Schema.Struct({
 	identifier: "RecoveredTestRow",
 	description: "A test whose latest run passed after the previous one failed."
 });
+/**
+* The `test_history` tool's success payload.
+*
+* @public
+*/
 const TestHistoryResult = Schema.Struct({
 	project: Schema.String.annotate({ description: "Workspace project key the history was computed for." }),
 	hasData: Schema.Boolean.annotate({ description: "`false` when no history rows exist for the project — agent should suggest running tests first." }),
@@ -91,12 +89,23 @@ const TestHistoryAsMarkdown = TestHistoryResult.pipe(Schema.decodeTo(Schema.Stri
 	decode: SchemaGetter.transform((data) => formatTestHistoryMarkdown(data)),
 	encode: SchemaGetter.forbidden(() => "TestHistoryAsMarkdown is one-way: markdown cannot be parsed back to TestHistoryResult.")
 }));
-const testHistory = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struct({
-	project: Schema.String,
-	testName: Schema.optional(Schema.String).annotate({ description: "Exact full_name match — narrows to a single test's history." }),
-	modulePath: Schema.optional(Schema.String).annotate({ description: "Exact module_path match — narrows to tests in one file." }),
-	limit: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0)).annotate({ description: "Max runs kept per test, most-recent-first. Must be a positive integer. Default 20." }))
-}))).query(async ({ ctx, input }) => ctx.runtime.runPromise(Effect.gen(function* () {
+/**
+* The `test_history` tool's parameters.
+*
+* @public
+*/
+const TestHistoryInput = Schema.Struct({
+	project: Schema.String.annotate({ description: "Project name (required)" }),
+	testName: Schema.optionalKey(Schema.String).annotate({ description: "Exact full_name match — narrows to a single test's history." }),
+	modulePath: Schema.optionalKey(Schema.String).annotate({ description: "Exact module_path match — narrows to tests in one file." }),
+	limit: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0)).annotate({ description: "Max runs kept per test, most-recent-first. Must be a positive integer. Default 20." }))
+});
+/**
+* Handler for {@link testHistoryTool}.
+*
+* @public
+*/
+const handleTestHistory = (input) => Effect.gen(function* () {
 	const reader = yield* DataReader;
 	const scopeOptions = {
 		...input.testName !== void 0 && { testName: input.testName },
@@ -131,7 +140,18 @@ const testHistory = publicProcedure.input(Schema.toStandardSchemaV1(Schema.Struc
 		persistent,
 		recovered
 	};
-})));
+}).pipe(Effect.orDie);
+/**
+* The Effect-native `test_history` tool.
+*
+* @public
+*/
+const testHistoryTool = Tool.make("test_history", {
+	description: "Use when failures recur and you need flaky, persistent, and recovered test classifications. Returns markdown in content[] and a typed JSON object in structuredContent (project, hasData, history, flaky[], persistent[], recovered[]). Optional testName/modulePath narrow to a single test; limit caps runs kept per test (default 20) — omit all three only when you actually need the whole project's history.",
+	parameters: TestHistoryInput,
+	success: TestHistoryResult,
+	dependencies: [DataReader]
+}).annotate(Tool.Title, "Test history").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, true).annotate(RenderText, (encoded) => formatTestHistoryMarkdown(encoded));
 
 //#endregion
-export { TestHistoryAsMarkdown, TestHistoryResult, formatTestHistoryMarkdown, testHistory };
+export { TestHistoryInput, TestHistoryResult, formatTestHistoryMarkdown, handleTestHistory, testHistoryTool };

package/tools/hypothesis.js

@@ -1,18 +1,12 @@
-import { idempotentProcedure } from "../middleware/idempotency.js";
+import { RenderText } from "../annotations.js";
+import { McpSession } from "../session.js";
+import { IdempotentReplayMarker } from "../utils/replay-marker.js";
 import { Effect, Match, Option, Schema } from "effect";
-import { DataReader, DataStore, DataStoreError } from "@vitest-agent/sdk";
+import { DataReader, DataStore } from "@vitest-agent/engine";
+import { Tool } from "effect/unstable/ai";
+import { DataStoreError } from "@vitest-agent/sdk";
 
 //#region src/tools/hypothesis.ts
-/**
-* Consolidated `hypothesis` MCP tool — Schema-driven implementation.
-*
-* `record` and `validate` are mutations whose result is a small
-* structured envelope. `list` now returns a structured array; the
-* boundary in server.ts renders it as markdown via the exported
-* `formatHypothesisListMarkdown` helper.
-*
-* @packageDocumentation
-*/
 const HypothesisRowSchema = Schema.Struct({
 	id: Schema.Number,
 	sessionId: Schema.Number,
@@ -30,7 +24,10 @@ const HypothesisRecordOk = Schema.Struct({
 	action: Schema.Literal("record"),
 	id: Schema.Finite.annotate({ description: "Newly inserted hypothesis row primary key." })
 });
-const HypothesisValidateOk = Schema.Struct({ action: Schema.Literal("validate") });
+const HypothesisValidateOk = Schema.Struct({
+	action: Schema.Literal("validate"),
+	...IdempotentReplayMarker
+});
 const HypothesisListOk = Schema.Struct({
 	action: Schema.Literal("list"),
 	count: Schema.Number,
@@ -55,117 +52,136 @@ const formatHypothesisListMarkdown = (data) => {
 	}
 	return lines.join("\n");
 };
+/** Number-or-numeric-string id: LLM orchestrators routinely stringify numeric tool inputs. */
+const CoercibleId = Schema.Union([Schema.Finite, Schema.FiniteFromString]);
+/** The text channel: `list` renders markdown; `record` / `validate` render the pretty-printed JSON. */
+const renderHypothesisText = (data) => data.action === "list" ? formatHypothesisListMarkdown(data) : JSON.stringify(data, null, 2);
 const RecordVariant = Schema.Struct({
-	action: Schema.Literal("record"),
-	tddTaskId: Schema.optional(Schema.Union([Schema.Number, Schema.FiniteFromString])),
-	sessionId: Schema.optional(Schema.Union([Schema.Number, Schema.FiniteFromString])),
-	content: Schema.String,
-	createdTurnId: Schema.optional(Schema.Number),
-	citedTestErrorId: Schema.optional(Schema.Number),
-	citedStackFrameId: Schema.optional(Schema.Number)
+	action: Schema.Literal("record").annotate({ description: "CRUD discriminator" }),
+	tddTaskId: Schema.optionalKey(CoercibleId).annotate({ description: "record: tdd task id returned by tdd_task action='start' — binds the hypothesis to that task's session deterministically" }),
+	sessionId: Schema.optionalKey(CoercibleId).annotate({ description: "list: filter by session id. record: dev/test fallback only — ignored when host context is recovered; never pass a tddTaskId value here" }),
+	content: Schema.String.annotate({ description: "Hypothesis content (action=record)" }),
+	createdTurnId: Schema.optionalKey(Schema.Finite),
+	citedTestErrorId: Schema.optionalKey(Schema.Finite),
+	citedStackFrameId: Schema.optionalKey(Schema.Finite)
 });
 const ValidateVariant = Schema.Struct({
-	action: Schema.Literal("validate"),
-	id: Schema.Number,
+	action: Schema.Literal("validate").annotate({ description: "CRUD discriminator" }),
+	id: Schema.Finite.annotate({ description: "Hypothesis id (action=validate)" }),
 	outcome: Schema.Literals([
 		"confirmed",
 		"refuted",
 		"abandoned"
-	]),
-	validatedTurnId: Schema.optional(Schema.Number),
-	validatedAt: Schema.optional(Schema.String)
+	]).annotate({ description: "validate: 'confirmed'|'refuted'|'abandoned'; list filter may include 'open'" }),
+	validatedTurnId: Schema.optionalKey(Schema.Finite),
+	validatedAt: Schema.optionalKey(Schema.String).annotate({ description: "ISO 8601 timestamp (action=validate)" })
 });
 const ListVariant = Schema.Struct({
-	action: Schema.Literal("list"),
-	sessionId: Schema.optional(Schema.Number),
-	outcome: Schema.optional(Schema.Literals([
+	action: Schema.Literal("list").annotate({ description: "CRUD discriminator" }),
+	sessionId: Schema.optionalKey(Schema.Finite).annotate({ description: "list: filter by session id. record: dev/test fallback only — ignored when host context is recovered; never pass a tddTaskId value here" }),
+	outcome: Schema.optionalKey(Schema.Literals([
 		"confirmed",
 		"refuted",
 		"abandoned",
 		"open"
-	])),
-	limit: Schema.optional(Schema.Number)
+	])).annotate({ description: "validate: 'confirmed'|'refuted'|'abandoned'; list filter may include 'open'" }),
+	limit: Schema.optionalKey(Schema.Finite)
 });
+/**
+* The `hypothesis` tool's parameters — a union discriminated on `action`.
+*
+* @public
+*/
 const HypothesisInput = Schema.Union([
 	RecordVariant,
 	ValidateVariant,
 	ListVariant
 ]);
 /**
-* Single source of truth for the `hypothesis` 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 hypothesisTool}. `record` fails (as a defect, so it
+* reaches the agent as the `UnexpectedToolError` envelope) when the
+* binding session cannot be resolved.
+*
+* @public
 */
-const HYPOTHESIS_ACTIONS = [
-	"record",
-	"validate",
-	"list"
-];
-const hypothesis = idempotentProcedure.input(Schema.toStandardSchemaV1(HypothesisInput)).mutation(async ({ ctx, input }) => {
-	return ctx.runtime.runPromise(Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
-		record: (variant) => Effect.gen(function* () {
-			const store = yield* DataStore;
-			const reader = yield* DataReader;
-			let resolvedSessionId;
-			if (variant.tddTaskId !== void 0) {
-				const bound = yield* reader.getSessionByTddTaskId(variant.tddTaskId);
-				if (Option.isNone(bound)) return yield* Effect.fail(new DataStoreError({
-					operation: "write",
-					table: "hypotheses",
-					reason: `unknown tddTaskId ${variant.tddTaskId}: no session found to attribute hypothesis`
-				}));
-				resolvedSessionId = bound.value.id;
-			} else {
-				const sc = ctx.sessionContext.get();
-				resolvedSessionId = variant.sessionId;
-				if (sc !== null) {
-					const main = yield* reader.getSessionByChatId(sc.chatId);
-					if (Option.isSome(main)) {
-						const sub = yield* reader.findActiveSubagentSession(main.value.id);
-						resolvedSessionId = Option.isSome(sub) ? sub.value.id : main.value.id;
-					}
+const handleHypothesis = (input) => Match.value(input).pipe(Match.discriminatorsExhaustive("action")({
+	record: (variant) => Effect.gen(function* () {
+		const store = yield* DataStore;
+		const reader = yield* DataReader;
+		const session = yield* McpSession;
+		let resolvedSessionId;
+		if (variant.tddTaskId !== void 0) {
+			const bound = yield* reader.getSessionByTddTaskId(variant.tddTaskId);
+			if (Option.isNone(bound)) return yield* Effect.fail(new DataStoreError({
+				operation: "write",
+				table: "hypotheses",
+				reason: `unknown tddTaskId ${variant.tddTaskId}: no session found to attribute hypothesis`
+			}));
+			resolvedSessionId = bound.value.id;
+		} else {
+			const sc = session.sessionContext.get();
+			resolvedSessionId = variant.sessionId;
+			if (sc !== null) {
+				const main = yield* reader.getSessionByChatId(sc.chatId);
+				if (Option.isSome(main)) {
+					const sub = yield* reader.findActiveSubagentSession(main.value.id);
+					resolvedSessionId = Option.isSome(sub) ? sub.value.id : main.value.id;
 				}
-				if (resolvedSessionId === void 0) return yield* Effect.fail(new DataStoreError({
-					operation: "write",
-					table: "hypotheses",
-					reason: "no recovered session context: pass tddTaskId (the id returned by tdd_task action:start) to bind this hypothesis to your task's session — do not retry with a raw sessionId, and never pass tddTaskId under a sessionId key"
-				}));
 			}
-			return {
-				action: "record",
-				id: yield* store.writeHypothesis({
-					sessionId: resolvedSessionId,
-					content: variant.content,
-					...variant.createdTurnId !== void 0 && { createdTurnId: variant.createdTurnId },
-					...variant.citedTestErrorId !== void 0 && { citedTestErrorId: variant.citedTestErrorId },
-					...variant.citedStackFrameId !== void 0 && { citedStackFrameId: variant.citedStackFrameId }
-				})
-			};
-		}),
-		validate: (variant) => Effect.gen(function* () {
-			yield* (yield* DataStore).validateHypothesis({
-				id: variant.id,
-				outcome: variant.outcome,
-				validatedAt: variant.validatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-				...variant.validatedTurnId !== void 0 && { validatedTurnId: variant.validatedTurnId }
-			});
-			return { action: "validate" };
-		}),
-		list: (variant) => Effect.gen(function* () {
-			const rows = yield* (yield* DataReader).listHypotheses({
-				...variant.sessionId !== void 0 && { sessionId: variant.sessionId },
-				...variant.outcome !== void 0 && { outcome: variant.outcome },
-				...variant.limit !== void 0 && { limit: variant.limit }
-			});
-			return {
-				action: "list",
-				count: rows.length,
-				hypotheses: rows
-			};
-		})
-	})));
-});
+			if (resolvedSessionId === void 0) return yield* Effect.fail(new DataStoreError({
+				operation: "write",
+				table: "hypotheses",
+				reason: "no recovered session context: pass tddTaskId (the id returned by tdd_task action:start) to bind this hypothesis to your task's session — do not retry with a raw sessionId, and never pass tddTaskId under a sessionId key"
+			}));
+		}
+		return {
+			action: "record",
+			id: yield* store.writeHypothesis({
+				sessionId: resolvedSessionId,
+				content: variant.content,
+				...variant.createdTurnId !== void 0 && { createdTurnId: variant.createdTurnId },
+				...variant.citedTestErrorId !== void 0 && { citedTestErrorId: variant.citedTestErrorId },
+				...variant.citedStackFrameId !== void 0 && { citedStackFrameId: variant.citedStackFrameId }
+			})
+		};
+	}),
+	validate: (variant) => Effect.gen(function* () {
+		yield* (yield* DataStore).validateHypothesis({
+			id: variant.id,
+			outcome: variant.outcome,
+			validatedAt: variant.validatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+			...variant.validatedTurnId !== void 0 && { validatedTurnId: variant.validatedTurnId }
+		});
+		return { action: "validate" };
+	}),
+	list: (variant) => Effect.gen(function* () {
+		const rows = yield* (yield* DataReader).listHypotheses({
+			...variant.sessionId !== void 0 && { sessionId: variant.sessionId },
+			...variant.outcome !== void 0 && { outcome: variant.outcome },
+			...variant.limit !== void 0 && { limit: variant.limit }
+		});
+		return {
+			action: "list",
+			count: rows.length,
+			hypotheses: rows
+		};
+	})
+})).pipe(Effect.orDie);
+/**
+* The Effect-native `hypothesis` tool.
+*
+* @public
+*/
+const hypothesisTool = Tool.make("hypothesis", {
+	description: "Use to manage debugging hypotheses, with a CRUD action discriminator: action='record' (content, tddTaskId?, optional citation ids) writes a hypothesis — the binding session is resolved server-side from the recovered host context (active TDD subagent, else main session); pass tddTaskId (returned by tdd_task action='start') to bind deterministically to that task's session, and do not pass sessionId when recording; action='validate' (id, outcome, validatedAt?) records a validation outcome — validatedAt is optional and defaults server-side to now when omitted, or is honored verbatim when supplied; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
+	parameters: HypothesisInput,
+	success: HypothesisResult,
+	dependencies: [
+		DataReader,
+		DataStore,
+		McpSession
+	]
+}).annotate(Tool.Title, "Hypothesis").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, false).annotate(Tool.Idempotent, false).annotate(RenderText, (encoded) => renderHypothesisText(encoded));
 
 //#endregion
-export { HYPOTHESIS_ACTIONS, HypothesisResult, formatHypothesisListMarkdown, hypothesis };
+export { HypothesisInput, HypothesisResult, formatHypothesisListMarkdown, handleHypothesis, hypothesisTool };