@vitest-agent/mcp 2.0.4 → 2.0.6

package/README.md

@@ -13,6 +13,7 @@ The `vitest-agent-mcp` MCP server bin. Exposes action-keyed tools over stdio tha
 - **29 action-keyed tools** — per-CRUD families collapse into single tools dispatching on an `action` discriminator; covers `test_status`, `test_overview`, `test_coverage`, `test_errors`, `run_tests`, `note`, `hypothesis`, `tdd_task`, `tdd_goal`, `tdd_behavior` and more
 - **Six framing prompts** — `triage`, `why-flaky`, `regression-since-pass`, `explain-failure`, `tdd-resume`, `wrapup`
 - **Idempotency middleware** — `tdd_task`, `tdd_goal`, `tdd_behavior` and `hypothesis` create-actions are idempotent on derived keys
+- **Programmatic API** — `buildMcpServer` constructs the server without connecting a transport; `parseSessionEnvExports` and `recoverSessionContextFromSessionEnv` recover the host session context from the Claude Code plugin's session-env files, so agent attribution survives a plugin reload
 
 ## Install
 

package/bin/vitest-agent-mcp.js

@@ -2,6 +2,7 @@
 import { createCurrentSessionIdRef, createSessionContextRef, sessionContextFromEnv } from "../context.js";
 import { McpLive } from "../layers/McpLive.js";
 import { startMcpServer } from "../server.js";
+import { recoverSessionContextFromSessionEnv } from "../session-env.js";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { PathResolutionLive, formatFatalError, resolveDataPath, resolveLogFile, resolveLogLevel } from "@vitest-agent/sdk";
 import { Effect, ManagedRuntime } from "effect";
@@ -58,7 +59,7 @@ async function main() {
 		runtime,
 		cwd: projectDir,
 		currentSessionId: createCurrentSessionIdRef(initialSessionId ?? recoveredContext?.chatId ?? null),
-		sessionContext: createSessionContextRef(recoveredContext)
+		sessionContext: createSessionContextRef(recoveredContext, () => recoverSessionContextFromSessionEnv({ projectDir }))
 	};
 	const chatIdResolved = initialSessionId ?? recoveredContext?.chatId ?? null;
 	console.error("[vitest-agent-mcp] Starting...");

package/context.js

@@ -20,14 +20,27 @@ const createCurrentSessionIdRef = (initial = null) => {
 /**
 * Creates a new {@link 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
+* a null boot-time context heals at the first tool call that needs it:
+* boot-time env recovery loses both the fresh-launch race (the MCP child
+* can spawn before SessionStart writes `CLAUDE_ENV_FILE`) and the
+* `/reload-plugins` restart (fresh environment, no session exports), but
+* by first-tool-call time the SessionStart hook's session-env file is on
+* disk for the recover thunk to read.
+*
 * @param initial - the starting session context, or `null` when not yet recovered
+* @param recover - optional call-time recovery attempted by `get()` while the value is `null`
 * @returns a mutable ref holding the current session context
 * @public
 */
-const createSessionContextRef = (initial = null) => {
+const createSessionContextRef = (initial = null, recover) => {
 	let value = initial;
 	return {
-		get: () => value,
+		get: () => {
+			if (value === null && recover !== void 0) value = recover();
+			return value;
+		},
 		set: (ctx) => {
 			value = ctx;
 		}

package/index.d.ts

@@ -2,6 +2,7 @@ import { DataReader, DataStore, OutputRenderer, ProjectDiscovery } from "@vitest
 import { Layer, LogLevel, ManagedRuntime } from "effect";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 //#region src/context.d.ts
 /**
  * Mutable holder for the MCP server's currently-associated host chat
@@ -58,11 +59,21 @@ interface SessionContextRef {
 /**
  * Creates a new {@link 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
+ * a null boot-time context heals at the first tool call that needs it:
+ * boot-time env recovery loses both the fresh-launch race (the MCP child
+ * can spawn before SessionStart writes `CLAUDE_ENV_FILE`) and the
+ * `/reload-plugins` restart (fresh environment, no session exports), but
+ * by first-tool-call time the SessionStart hook's session-env file is on
+ * disk for the recover thunk to read.
+ *
  * @param initial - the starting session context, or `null` when not yet recovered
+ * @param recover - optional call-time recovery attempted by `get()` while the value is `null`
  * @returns a mutable ref holding the current session context
  * @public
  */
-declare const createSessionContextRef: (initial?: SessionContext | null) => SessionContextRef;
+declare const createSessionContextRef: (initial?: SessionContext | null, recover?: () => SessionContext | null) => SessionContextRef;
 /**
  * tRPC context carrying a ManagedRuntime for Effect service access.
  *
@@ -1410,7 +1421,8 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
   hypothesis: import("@trpc/server").TRPCMutationProcedure<{
     input: {
       readonly action: "record";
-      readonly sessionId?: number | undefined;
+      readonly tddTaskId?: string | number | undefined;
+      readonly sessionId?: string | number | undefined;
       readonly content: string;
       readonly createdTurnId?: number | undefined;
       readonly citedTestErrorId?: number | undefined;
@@ -1530,18 +1542,58 @@ declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
 }>>;
 //#endregion
 //#region src/server.d.ts
+/**
+ * Builds the fully-registered MCP server without connecting a transport.
+ *
+ * Constructs the MCP server instance, registers all tRPC-backed tools
+ * (wired through `ctx.runtime`), and calls `registerAllPrompts`. Split
+ * from {@link startMcpServer} so tests can connect the identical server
+ * to an in-memory transport and assert the *served* tool schemas — the
+ * MCP-SDK-side registrations here are hand-synced with the tRPC inputs
+ * in `tools/`, and a missed sync is invisible to router-level tests.
+ *
+ * @param ctx - the MCP context carrying the shared ManagedRuntime and session refs
+ * @public
+ */
+declare function buildMcpServer(ctx: McpContext): McpServer;
 /**
  * Starts the MCP server over stdio, registering all tools and prompts.
  *
- * Constructs the MCP server instance, registers all tRPC-backed tools (wired through
- * `ctx.runtime`), calls `registerAllPrompts`, then connects
- * a `StdioServerTransport`. Returns when the transport disconnects.
+ * Builds the server via {@link buildMcpServer}, then connects a
+ * `StdioServerTransport`. Returns when the transport disconnects.
  *
  * @param ctx - the MCP context carrying the shared ManagedRuntime and session refs
  * @public
  */
 declare function startMcpServer(ctx: McpContext): Promise<void>;
 //#endregion
+//#region src/session-env.d.ts
+/**
+ * Parse `export KEY=value` lines from a session-env hook file into a
+ * plain record. Non-export lines are ignored.
+ *
+ * @param content - the raw text of a session-env hook file
+ * @returns a record of export names to unquoted values
+ * @public
+ */
+declare const parseSessionEnvExports: (content: string) => Record<string, string>;
+/**
+ * Recover a {@link SessionContext} from the newest session-env hook file
+ * whose `VITEST_AGENT_PROJECT_DIR` matches `projectDir`.
+ *
+ * Returns `null` when the session-env root is missing, unreadable, or no
+ * session dir matches the project. Never throws — recovery is best-effort
+ * and callers fall back to their existing null-context behavior.
+ *
+ * @param opts - `projectDir` to match against; `sessionEnvRoot` overrides
+ *   the default `~/.claude/session-env` (tests)
+ * @public
+ */
+declare const recoverSessionContextFromSessionEnv: (opts: {
+  readonly projectDir: string;
+  readonly sessionEnvRoot?: string;
+}) => SessionContext | null;
+//#endregion
 //#region src/tools/_tdd-error-envelope.d.ts
 /**
  * Suggested recovery action attached to a TDD error envelope.
@@ -1584,5 +1636,5 @@ interface TddErrorEnvelope {
  */
 declare const CURRENT_MCP_VERSION: string;
 //#endregion
-export { CURRENT_MCP_VERSION, type CurrentSessionIdRef, type McpContext, McpLive, type Remediation, type SessionContext, type SessionContextRef, type TddErrorEnvelope, appRouter, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, startMcpServer };
+export { CURRENT_MCP_VERSION, type CurrentSessionIdRef, type McpContext, McpLive, type Remediation, type SessionContext, type SessionContextRef, type TddErrorEnvelope, appRouter, buildMcpServer, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, parseSessionEnvExports, recoverSessionContextFromSessionEnv, startMcpServer };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,7 +1,8 @@
 import { createCallerFactory, createCurrentSessionIdRef, createSessionContextRef } from "./context.js";
 import { McpLive } from "./layers/McpLive.js";
 import { appRouter } from "./router.js";
-import { startMcpServer } from "./server.js";
+import { buildMcpServer, startMcpServer } from "./server.js";
+import { parseSessionEnvExports, recoverSessionContextFromSessionEnv } from "./session-env.js";
 
 //#region src/index.ts
 /**
@@ -11,7 +12,7 @@ import { startMcpServer } from "./server.js";
 *
 * @public
 */
-const CURRENT_MCP_VERSION = "2.0.4";
+const CURRENT_MCP_VERSION = "2.0.6";
 
 //#endregion
-export { CURRENT_MCP_VERSION, McpLive, appRouter, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, startMcpServer };
+export { CURRENT_MCP_VERSION, McpLive, appRouter, buildMcpServer, createCallerFactory, createCurrentSessionIdRef, createSessionContextRef, parseSessionEnvExports, recoverSessionContextFromSessionEnv, startMcpServer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/mcp",
-	"version": "2.0.4",
+	"version": "2.0.6",
 	"private": false,
 	"description": "Model Context Protocol server for vitest-agent. Exposes 53 tools for agent access to test data, TDD lifecycle, and session management.",
 	"keywords": [
@@ -42,7 +42,7 @@
 		"@effect/sql-sqlite-node": "4.0.0-beta.99",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@trpc/server": "^11.18.0",
-		"@vitest-agent/sdk": "2.0.4",
+		"@vitest-agent/sdk": "2.0.6",
 		"effect": "4.0.0-beta.99",
 		"zod": "^4.4.3"
 	},

package/server.js

@@ -122,16 +122,19 @@ function structuredJsonResult(value) {
 	return structuredResult(JSON.stringify(value, null, 2), value);
 }
 /**
-* Starts the MCP server over stdio, registering all tools and prompts.
+* Builds the fully-registered MCP server without connecting a transport.
 *
-* Constructs the MCP server instance, registers all tRPC-backed tools (wired through
-* `ctx.runtime`), calls `registerAllPrompts`, then connects
-* a `StdioServerTransport`. Returns when the transport disconnects.
+* Constructs the MCP server instance, registers all tRPC-backed tools
+* (wired through `ctx.runtime`), and calls `registerAllPrompts`. Split
+* from {@link startMcpServer} so tests can connect the identical server
+* to an in-memory transport and assert the *served* tool schemas — the
+* MCP-SDK-side registrations here are hand-synced with the tRPC inputs
+* in `tools/`, and a missed sync is invisible to router-level tests.
 *
 * @param ctx - the MCP context carrying the shared ManagedRuntime and session refs
 * @public
 */
-async function startMcpServer(ctx) {
+function buildMcpServer(ctx) {
 	const server = new McpServer({
 		name: "vitest-agent",
 		version: "0.1.0"
@@ -701,14 +704,15 @@ async function startMcpServer(ctx) {
 		return structuredResult(Schema.decodeSync(TddArtifactListAsMarkdown)(data), data);
 	});
 	server.registerTool("hypothesis", {
-		description: "Use to manage debugging hypotheses, with a CRUD action discriminator: action='record' (sessionId, content, optional citation ids) writes a hypothesis; action='validate' (id, outcome, validatedAt) records a validation outcome; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
+		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; action='list' (sessionId?, outcome?, limit?) returns matching hypotheses as markdown.",
 		inputSchema: {
 			action: z.enum([
 				"record",
 				"validate",
 				"list"
 			]).describe("CRUD discriminator"),
-			sessionId: z.optional(z.coerce.number()).describe("Session id (required for record; filter for list)"),
+			sessionId: z.optional(z.coerce.number()).describe("list: filter by session id. record: dev/test fallback only — ignored when host context is recovered; never pass a tddTaskId value here"),
+			tddTaskId: z.optional(z.coerce.number()).describe("record: tdd task id returned by tdd_task action='start' — binds the hypothesis to that task's session deterministically"),
 			content: z.optional(z.string()).describe("Hypothesis content (action=record)"),
 			createdTurnId: z.optional(z.coerce.number()),
 			citedTestErrorId: z.optional(z.coerce.number()),
@@ -728,8 +732,9 @@ async function startMcpServer(ctx) {
 	}, async (args) => {
 		if (args.action === "record") return structuredJsonResult(await caller.hypothesis({
 			action: "record",
-			sessionId: args.sessionId,
 			content: args.content,
+			...args.tddTaskId !== void 0 && { tddTaskId: args.tddTaskId },
+			...args.sessionId !== void 0 && { sessionId: args.sessionId },
 			...args.createdTurnId !== void 0 && { createdTurnId: args.createdTurnId },
 			...args.citedTestErrorId !== void 0 && { citedTestErrorId: args.citedTestErrorId },
 			...args.citedStackFrameId !== void 0 && { citedStackFrameId: args.citedStackFrameId }
@@ -828,9 +833,22 @@ async function startMcpServer(ctx) {
 		return structuredResult(data.message, data);
 	});
 	registerAllPrompts(server);
+	return server;
+}
+/**
+* Starts the MCP server over stdio, registering all tools and prompts.
+*
+* Builds the server via {@link buildMcpServer}, then connects a
+* `StdioServerTransport`. Returns when the transport disconnects.
+*
+* @param ctx - the MCP context carrying the shared ManagedRuntime and session refs
+* @public
+*/
+async function startMcpServer(ctx) {
+	const server = buildMcpServer(ctx);
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 }
 
 //#endregion
-export { startMcpServer };
+export { buildMcpServer, startMcpServer };

package/session-env.js

@@ -0,0 +1,112 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+//#region src/session-env.ts
+/**
+* Call-time SessionContext recovery from the per-session env files the
+* plugin's SessionStart hook writes to `~/.claude/session-env/`.
+*
+* The boot-time env recovery (`sessionContextFromEnv`) depends on Claude
+* Code auto-sourcing `CLAUDE_ENV_FILE` into the MCP child — which loses
+* two races:
+*
+* 1. **Boot race.** On a fresh Claude Code launch the MCP child can spawn
+*    before the SessionStart hook has written `CLAUDE_ENV_FILE`, so the
+*    child's `process.env` never carries the canonical UUIDs (observed
+*    live: MCP spawn at 00:41:50, env file written 00:41:51).
+* 2. **`/reload-plugins`.** A plugin reload restarts the MCP server
+*    mid-session with a fresh environment that has no session exports.
+*
+* In both cases the SessionStart hook has (or will have) written the same
+* exports to a second, known-name surface:
+* `~/.claude/session-env/<chat_id>/vitest-agent-hook.sh`. This module
+* reads that surface directly, so a null boot context can be recovered
+* lazily at the first tool call that needs it.
+*
+* Selection rule: among all session dirs whose exports name this server's
+* `projectDir`, the newest-mtime file wins — the most recently started
+* session for this project. With two live Claude Code windows on the same
+* project this can name the other window's session; that ambiguity is
+* inherent to a per-project (not per-process) surface and is accepted —
+* the pre-existing alternative was no attribution at all.
+*
+* @packageDocumentation
+*/
+const EXPORT_LINE = /^export ([A-Z_][A-Z0-9_]*)=(.*)$/;
+/**
+* Undo the `printf '%q'` quoting the SessionStart hook applies to export
+* values. UUIDs and plain paths arrive bare; values with specials arrive
+* as `$'...'`, `'...'`, `"..."`, or backslash-escaped words.
+*/
+const unquote = (raw) => {
+	let v = raw.trim();
+	if (v.startsWith("$'") && v.endsWith("'") && v.length >= 3) v = v.slice(2, -1);
+	else if (v.startsWith("'") && v.endsWith("'") || v.startsWith("\"") && v.endsWith("\"")) {
+		if (v.length >= 2) v = v.slice(1, -1);
+	}
+	return v.replace(/\\(.)/g, "$1");
+};
+/**
+* Parse `export KEY=value` lines from a session-env hook file into a
+* plain record. Non-export lines are ignored.
+*
+* @param content - the raw text of a session-env hook file
+* @returns a record of export names to unquoted values
+* @public
+*/
+const parseSessionEnvExports = (content) => {
+	const out = {};
+	for (const line of content.split("\n")) {
+		const m = EXPORT_LINE.exec(line.trim());
+		if (m?.[1] !== void 0 && m[2] !== void 0) out[m[1]] = unquote(m[2]);
+	}
+	return out;
+};
+/**
+* Recover a {@link SessionContext} from the newest session-env hook file
+* whose `VITEST_AGENT_PROJECT_DIR` matches `projectDir`.
+*
+* Returns `null` when the session-env root is missing, unreadable, or no
+* session dir matches the project. Never throws — recovery is best-effort
+* and callers fall back to their existing null-context behavior.
+*
+* @param opts - `projectDir` to match against; `sessionEnvRoot` overrides
+*   the default `~/.claude/session-env` (tests)
+* @public
+*/
+const recoverSessionContextFromSessionEnv = (opts) => {
+	const root = opts.sessionEnvRoot ?? join(homedir(), ".claude", "session-env");
+	const wantDir = resolve(opts.projectDir);
+	let entries;
+	try {
+		entries = readdirSync(root);
+	} catch {
+		return null;
+	}
+	let best = null;
+	for (const entry of entries) {
+		const file = join(root, entry, "vitest-agent-hook.sh");
+		try {
+			const st = statSync(file);
+			const env = parseSessionEnvExports(readFileSync(file, "utf8"));
+			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;
+			const fileProjectDir = env.VITEST_AGENT_PROJECT_DIR;
+			if (chatId === void 0 || chatId.length === 0 || conversationId === void 0 || conversationId.length === 0 || mainAgentId === void 0 || mainAgentId.length === 0 || fileProjectDir === void 0 || resolve(fileProjectDir) !== wantDir) continue;
+			if (best === null || st.mtimeMs > best.mtimeMs) best = {
+				mtimeMs: st.mtimeMs,
+				ctx: {
+					chatId,
+					conversationId,
+					mainAgentId
+				}
+			};
+		} catch {}
+	}
+	return best === null ? null : best.ctx;
+};
+
+//#endregion
+export { parseSessionEnvExports, recoverSessionContextFromSessionEnv };

package/tools/hypothesis.js

@@ -57,7 +57,8 @@ const formatHypothesisListMarkdown = (data) => {
 };
 const RecordVariant = Schema.Struct({
 	action: Schema.Literal("record"),
-	sessionId: Schema.optional(Schema.Number),
+	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),
@@ -95,20 +96,31 @@ const hypothesis = idempotentProcedure.input(Schema.toStandardSchemaV1(Hypothesi
 		record: (variant) => Effect.gen(function* () {
 			const store = yield* DataStore;
 			const reader = yield* DataReader;
-			const sc = ctx.sessionContext.get();
-			let 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;
+			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;
+					}
 				}
+				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"
+				}));
 			}
-			if (resolvedSessionId === void 0) return yield* Effect.fail(new DataStoreError({
-				operation: "write",
-				table: "hypotheses",
-				reason: "no recovered session context and no sessionId supplied to attribute hypothesis"
-			}));
 			return {
 				action: "record",
 				id: yield* store.writeHypothesis({

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.11"
+      "packageVersion": "7.58.12"
     }
   ]
 }