lael-labs/executor

apps/host-selfhost/package.json+0−1

@@ -40,7 +40,6 @@ · 39 unmodified lines
40	"@executor-js/sdk": "workspace:*",	40	"@executor-js/sdk": "workspace:*",
41	"@libsql/client": "catalog:",	41	"@libsql/client": "catalog:",
42	"@libsql/kysely-libsql": "catalog:",	42	"@libsql/kysely-libsql": "catalog:",
43	"@modelcontextprotocol/sdk": "^1.29.0",
44	"@tanstack/react-router": "catalog:",	43	"@tanstack/react-router": "catalog:",
45	"better-auth": "^1.6.11",	44	"better-auth": "^1.6.11",
46	"drizzle-orm": "catalog:",	45	"drizzle-orm": "catalog:",

apps/host-selfhost/src/mcp/session-store.ts+2−2

@@ -23,8 +23,8 @@ import { SelfHostExecutionStackLayer } from "../execution"; · 22 unmodified lines
23	// ALL shared (`@executor-js/host-mcp/in-memory-session-store` + `makeMcpBuildServer`	23	// ALL shared (`@executor-js/host-mcp/in-memory-session-store` + `makeMcpBuildServer`
24	// / `makeConsoleMcpErrorReporter` in `@executor-js/api/server`). Self-host	24	// / `makeConsoleMcpErrorReporter` in `@executor-js/api/server`). Self-host
25	// supplies only its fully-provided execution-stack layer (QuickJS over the	25	// supplies only its fully-provided execution-stack layer (QuickJS over the
26	// long-lived `SelfHostDb`) and its `ErrorCapture`. The Cloudflare host wires the	26	// long-lived `SelfHostDb`) and its `ErrorCapture`; the builder creates the
27	// identical seam with its own stack layer.	27	// connection-lifetime SDK v2 assembly used by the shared store.
28	// ---------------------------------------------------------------------------	28	// ---------------------------------------------------------------------------
29		29
30	import { loadMcpAppsShellHtml } from "@executor-js/mcp-apps-shell";	30	import { loadMcpAppsShellHtml } from "@executor-js/mcp-apps-shell";

apps/local/package.json+1−1

     "@executor-js/sdk": "workspace:*",
     "@executor-js/vite-plugin": "workspace:*",
     "@libsql/client": "catalog:",
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@tanstack/react-router": "catalog:",
     "drizzle-orm": "catalog:",
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@rhyssul/portless": "^0.13.0",
     "@tailwindcss/vite": "catalog:",
     "@tanstack/router-plugin": "^1.167.12",

apps/local/src/mcp-stdio-test-server.ts+44−0

@@ -0,0 +1,44 @@
	1	import { Effect } from "effect";
	2
	3	import type { ExecutionEngine, ExecutionResult } from "@executor-js/execution";
	4	import { FormElicitation, ToolAddress } from "@executor-js/sdk";
	5
	6	import { runMcpStdioServer } from "./mcp";
	7
	8	const TOOL_ADDRESS = ToolAddress.make("tools.test.org.main.approve");
	9	const paused: Extract<ExecutionResult, { status: "paused" }> = {
	10	status: "paused",
	11	execution: {
	12	id: "stdio-execution",
	13	elicitationContext: {
	14	address: TOOL_ADDRESS,
	15	args: {},
	16	request: FormElicitation.make({
	17	message: "Approve the stdio action?",
	18	requestedSchema: {
	19	type: "object",
	20	properties: { value: { type: "string" } },
	21	required: ["value"],
	22	},
	23	}),
	24	},
	25	},
	26	};
	27
	28	const engine: ExecutionEngine = {
	29	execute: () => Effect.succeed({ result: "unused" }),
	30	executeWithPause: (code) =>
	31	code === "needs approval"
	32	? Effect.succeed(paused)
	33	: Effect.succeed({ status: "completed", result: { result: 4 } }),
	34	resume: (_executionId, response) =>
	35	Effect.succeed({ status: "completed", result: { result: response.content?.value } }),
	36	isExecutionSettled: () => Effect.succeed(false),
	37	getPausedExecution: (executionId) =>
	38	Effect.succeed(executionId === paused.execution.id ? paused.execution : null),
	39	pausedExecutionCount: () => Effect.succeed(1),
	40	hasPausedExecutions: () => Effect.succeed(true),
	41	getDescription: Effect.succeed("stdio integration test executor"),
	42	};
	43
	44	await runMcpStdioServer({ engine, elicitationMode: { mode: "native" } });

apps/local/src/mcp.ts+22−14

 import {
   createMcpHandler,
   isLegacyRequest,
+  McpServer,
+  WebStandardStreamableHTTPServerTransport,
   type McpHttpHandler,
 } from "@modelcontextprotocol/server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import {
   defaultMcpResource,
   mcpResourceKey,
   type McpResource,
 } from "@executor-js/host-mcp";
-import {
-  createExecutorMcpServer,
-  type ExecutorMcpServerConfig,
-} from "@executor-js/host-mcp/tool-server";
 import {
   appsEnabledForClientCapabilities,
   buildMcpServerV2,
   clientCapabilitiesFromRequest,
   requestBodyFromRequest,
+  type ExecutorMcpServerConfig,
 } from "@executor-js/host-mcp/tool-server-v2";
 import {
   approvalUrlForRequest,
         const elicitationMode = readElicitationMode(request);
         resourceConfig = await configForResource(resource);
         created = await Effect.runPromise(
-          createExecutorMcpServer({
+          buildMcpServerV2({
             ...resourceConfig.config,
             browserApprovalStore: approvals.store,
             artifactsEnabled: readArtifactsEnabled(request),
+            appsEnabled: resourceConfig.config.restoredAppsEnabled ?? false,
+            requestStateSigningKey: signingKey(),
+            requestStatePrincipal: "local",
+            sessionful: true,
             elicitationMode:
               elicitationMode === "browser"
                 ? {
 export const runMcpStdioServer = async (config: ExecutorMcpServerConfig): Promise<void> => {
   startIntegrationsRefresh();
-  // Deliberately v1-only in this release; modern stdio clients use their probe fallback policy.
+  const requestStateSigningKey = crypto.getRandomValues(new Uint8Array(32));
-  const server = await Effect.runPromise(createExecutorMcpServer(config));
+  const stdio = serveStdio(() =>
-  const transport = new StdioServerTransport();
+    Effect.runPromise(
+      buildMcpServerV2({
+        ...config,
+        appsEnabled: config.restoredAppsEnabled ?? false,
+        requestStateSigningKey,
+        requestStatePrincipal: "local",
+        sessionful: true,
+      }),
+    ),
+  );
   const waitForExit = () =>
     new Promise<void>((resolve) => {
   // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: stdio server lifetime uses Promise-based SDK/process APIs and always closes resources
   try {
-    await server.connect(transport);
     await waitForExit();
   } finally {
-    await ignoreClose(() => transport.close());
+    await ignoreClose(() => stdio.close());
-    await ignoreClose(() => server.close());
   }
 };

bun.lock+1−2

         "@executor-js/sdk": "workspace:*",
         "@libsql/client": "catalog:",
         "@libsql/kysely-libsql": "catalog:",
-        "@modelcontextprotocol/sdk": "^1.29.0",
         "@tanstack/react-router": "catalog:",
         "better-auth": "^1.6.11",
         "drizzle-orm": "catalog:",
         "@executor-js/sdk": "workspace:*",
         "@executor-js/vite-plugin": "workspace:*",
         "@libsql/client": "catalog:",
-        "@modelcontextprotocol/sdk": "^1.29.0",
         "@modelcontextprotocol/server": "2.0.0",
         "@tanstack/react-router": "catalog:",
         "drizzle-orm": "catalog:",
       },
       "devDependencies": {
         "@modelcontextprotocol/client": "2.0.0",
+        "@modelcontextprotocol/sdk": "^1.29.0",
         "@rhyssul/portless": "^0.13.0",
         "@tailwindcss/vite": "catalog:",
         "@tanstack/router-plugin": "^1.167.12",

packages/core/api/src/server/mcp-build.ts+11−16

 import {
   McpEngineBuildError,
   type McpBuildServer,
-  type McpBuildServerOptions,
 } from "@executor-js/host-mcp/in-memory-session-store";
-import { createExecutorMcpServer } from "@executor-js/host-mcp/tool-server";
 import { buildMcpServerV2 } from "@executor-js/host-mcp/tool-server-v2";
 import {
   artifactUrlFor,
 // ---------------------------------------------------------------------------
 // Shared in-process MCP host helpers.
 //
-// Every host that serves MCP from one isolate (self-host, the Cloudflare QuickJS
+// Neutral hosts build both sessionful legacy connections and stateless modern
-// host) builds its per-session McpServer the same way — assemble the scoped
+// requests from the same SDK v2 assembly over a scoped execution stack. The
-// engine via `makeExecutionStack`, wrap it with `createExecutorMcpServer` — and
+// Cloudflare Durable Object path remains a separate v1-backed composition root.
-// reports orchestration defects through the same console `ErrorCapture` seam.
-// These two factories are the single home for that logic; a host supplies ONLY
-// its fully-provided execution-stack layer and its `ErrorCapture` layer. The
-// cross-isolate variant (cloud's Durable Object store) is the exception that
-// builds its engine inside the DO.
 // ---------------------------------------------------------------------------
 /** The five execution-stack seams a host fully provides (no residual). */
 /**
  * Build the per-session MCP server factory over a host's execution stack:
- * `makeExecutionStack` → engine → `createExecutorMcpServer`. Hosts differ only
+ * `makeExecutionStack` → engine → `buildMcpServerV2`. Hosts differ only
  * in the injected stack layer (libSQL vs D1, etc.).
  */
 export const makeMcpBuildServer =
   (executionStack: McpExecutionStackLayer, hostOptions?: McpBuildHostOptions): McpBuildServer =>
-  (principal: Principal, options?: McpBuildServerOptions) =>
+  (principal: Principal, options) => {
-    Effect.gen(function* () {
+    const { resource, ...serverOptions } = options;
+    return Effect.gen(function* () {
       const { engine, executor } = yield* makeExecutionStack(
         principal.accountId,
         principal.organizationId,
         principal.organizationName,
-        { mcpResource: options?.resource },
+        { mcpResource: resource },
       ).pipe(Effect.withSpan("mcp.execution_stack.build"));
       // Read inside the provided boundary: `webBaseUrl` is a host seam, and
       // hosts that can't know their public URL at boot leave it unset — in
       Effect.provide(executionStack),
       Effect.mapError((cause) => new McpEngineBuildError({ cause })),
       Effect.flatMap(({ engine, executor, webBaseUrl }) =>
-        createExecutorMcpServer({
+        buildMcpServerV2({
           engine,
           artifacts: executor.artifacts,
           connections: executor.connections,
           ...(webBaseUrl
             ? { artifactUrl: artifactUrlFor(webBaseUrl, principal.organizationSlug) }
             : {}),
-          ...(options ?? {}),
+          ...serverOptions,
         }).pipe(
           Effect.withSpan("mcp.server.create"),
           Effect.map((mcpServer) => ({ mcpServer, engine })),
         ),
       ),
     );
+  };
 /** Build function consumed by the neutral envelope's modern-server seam. */
 export type McpBuildServerV2 = McpModernServerBuilder["Service"]["build"];

packages/hosts/mcp/src/in-memory-session-store.test.ts+159−30

@@ -1,12 +1,20 @@
1	import { expect, it } from "@effect/vitest";	1	import { describe, expect, it } from "@effect/vitest";
2	import { Effect } from "effect";	2	import { Effect } from "effect";
		3	import { Client } from "@modelcontextprotocol/sdk/client/index.js";
		4	import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
		5	import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
		6
		7	import type { ExecutionEngine, ExecutionResult, ResumeResponse } from "@executor-js/execution";
		8	import { FormElicitation, ToolAddress } from "@executor-js/sdk";
3		9
4	import {	10	import {
5	makeInMemoryMcpSessionStore,	11	makeInMemoryMcpSessionStore,
6	McpEngineBuildError,	12	McpEngineBuildError,
7	type McpBuildServerOptions,	13	type McpBuildServerOptions,
8	} from "./in-memory-session-store";	14	} from "./in-memory-session-store";
		15	import { EXTENSION_ID, RESOURCE_MIME_TYPE } from "./mcp-apps";
9	import { defaultMcpResource, type Principal } from "./seams";	16	import { defaultMcpResource, type Principal } from "./seams";
		17	import { buildMcpServerV2 } from "./tool-server-v2";
10		18
11	const TEST_PRINCIPAL: Principal = {	19	const TEST_PRINCIPAL: Principal = {
12	accountId: "acct_test",	20	accountId: "acct_test",
@@ -18,37 +26,158 @@ const TEST_PRINCIPAL: Principal = { · 5 unmodified lines
18	roles: ["user"],	26	roles: ["user"],
19	};	27	};
20		28
21	it("preserves native elicitation mode when creating an in-memory MCP session", async () => {	29	const TOOL_ADDRESS = ToolAddress.make("tools.test.org.main.approve");
22	let buildOptions: McpBuildServerOptions \| undefined;	30
23	const sessions = makeInMemoryMcpSessionStore((_principal, options) => {	31	const makeElicitingEngine = (): {
24	buildOptions = options;	32	readonly engine: ExecutionEngine;
25	return Effect.fail(new McpEngineBuildError({ cause: "stop after capturing options" }));	33	readonly resumedWith: () => ResumeResponse \| undefined;
		34	} => {
		35	const request = FormElicitation.make({
		36	message: "Which value?",
		37	requestedSchema: {
		38	type: "object",
		39	properties: { value: { type: "string" } },
		40	required: ["value"],
		41	},
26	});	42	});
		43	const paused: Extract<ExecutionResult, { status: "paused" }> = {
		44	status: "paused",
		45	execution: {
		46	id: "execution-legacy",
		47	elicitationContext: { address: TOOL_ADDRESS, args: {}, request },
		48	},
		49	};
		50	let resumedWith: ResumeResponse \| undefined;
		51	return {
		52	engine: {
		53	execute: () => Effect.succeed({ result: "unused" }),
		54	executeWithPause: () => Effect.succeed(paused),
		55	resume: (_executionId, response) => {
		56	resumedWith = response;
		57	return Effect.succeed({
		58	status: "completed",
		59	result: { result: response.content?.value },
		60	});
		61	},
		62	isExecutionSettled: () => Effect.succeed(false),
		63	getPausedExecution: (executionId) =>
		64	Effect.succeed(executionId === paused.execution.id ? paused.execution : null),
		65	pausedExecutionCount: () => Effect.succeed(1),
		66	hasPausedExecutions: () => Effect.succeed(true),
		67	getDescription: Effect.succeed("store integration test executor"),
		68	},
		69	resumedWith: () => resumedWith,
		70	};
		71	};
27		72
28	const result = await Effect.runPromise(	73	describe("in-memory MCP session store", () => {
29	sessions.store.dispatch({	74	it("preserves native elicitation mode and supplies the v2 session inputs", async () => {
30	request: new Request("https://executor.test/mcp?elicitation_mode=native", {	75	let buildOptions: McpBuildServerOptions \| undefined;
31	method: "POST",	76	const sessions = makeInMemoryMcpSessionStore((_principal, options) => {
32	headers: { "content-type": "application/json" },	77	buildOptions = options;
33	body: JSON.stringify({	78	return Effect.fail(new McpEngineBuildError({ cause: "stop after capturing options" }));
34	jsonrpc: "2.0",	79	});
35	id: 1,	80
36	method: "initialize",	81	const result = await Effect.runPromise(
37	params: {	82	sessions.store.dispatch({
38	protocolVersion: "2025-06-18",	83	request: new Request("https://executor.test/mcp?elicitation_mode=native", {
39	capabilities: { elicitation: { form: {} } },	84	method: "POST",
40	clientInfo: { name: "test-client", version: "1.0.0" },	85	headers: { "content-type": "application/json" },
41	},	86	body: JSON.stringify({
		87	jsonrpc: "2.0",
		88	id: 1,
		89	method: "initialize",
		90	params: {
		91	protocolVersion: "2025-06-18",
		92	capabilities: { elicitation: { form: {} } },
		93	clientInfo: { name: "test-client", version: "1.0.0" },
		94	},
		95	}),
42	}),	96	}),
		97	principal: TEST_PRINCIPAL,
		98	resource: defaultMcpResource,
		99	sessionId: null,
		100	method: "POST",
43	}),	101	}),
44	principal: TEST_PRINCIPAL,	102	);
45	resource: defaultMcpResource,	103
46	sessionId: null,	104	expect(result).toBeInstanceOf(Response);
47	method: "POST",	105	expect((result as Response).status).toBe(500);
48	}),	106	expect(buildOptions?.elicitationMode).toEqual({ mode: "native" });
49	);	107	expect(buildOptions).toMatchObject({
50		108	appsEnabled: false,
51	expect(result).toBeInstanceOf(Response);	109	requestStatePrincipal: `${TEST_PRINCIPAL.accountId}\u0000${TEST_PRINCIPAL.organizationId}`,
52	expect((result as Response).status).toBe(500);	110	sessionful: true,
53	expect(buildOptions?.elicitationMode).toEqual({ mode: "native" });	111	});
		112	expect(buildOptions?.requestStateSigningKey).toBeInstanceOf(Uint8Array);
		113	});
		114
		115	it("serves a legacy client through v2 with live Apps capabilities, elicitation, and reuse", async () => {
		116	const { engine, resumedWith } = makeElicitingEngine();
		117	const sessions = makeInMemoryMcpSessionStore((_principal, options) =>
		118	buildMcpServerV2({
		119	engine,
		120	...options,
		121	loadAppShellHtml: async () => "<html></html>",
		122	}).pipe(Effect.map((mcpServer) => ({ mcpServer, engine }))),
		123	);
		124	const fetch = async (input: string \| URL \| Request, init?: RequestInit): Promise<Response> => {
		125	const request =
		126	input instanceof Request ? new Request(input, init) : new Request(input.toString(), init);
		127	const result = await Effect.runPromise(
		128	sessions.store.dispatch({
		129	request,
		130	principal: TEST_PRINCIPAL,
		131	resource: defaultMcpResource,
		132	sessionId: request.headers.get("mcp-session-id"),
		133	method: request.method,
		134	}),
		135	);
		136	return result instanceof Response
		137	? result
		138	: new Response(result === "forbidden" ? "Forbidden" : "Not found", {
		139	status: result === "forbidden" ? 403 : 404,
		140	});
		141	};
		142	const transport = new StreamableHTTPClientTransport(
		143	new URL("https://executor.test/mcp?elicitation_mode=native"),
		144	{ fetch },
		145	);
		146	const client = new Client(
		147	{ name: "legacy-store-client", version: "1.0.0" },
		148	{
		149	capabilities: {
		150	elicitation: { form: {} },
		151	extensions: { [EXTENSION_ID]: { mimeTypes: [RESOURCE_MIME_TYPE] } },
		152	},
		153	},
		154	);
		155	let elicitationRequests = 0;
		156	client.setRequestHandler(ElicitRequestSchema, async (request) => {
		157	elicitationRequests += 1;
		158	expect(request.params).toMatchObject({ message: "Which value?" });
		159	return { action: "accept" as const, content: { value: "approved" } };
		160	});
		161
		162	await client.connect(transport);
		163	// oxlint-disable-next-line executor/no-try-catch-or-throw -- test boundary: always close the sessionful client and store
		164	try {
		165	const tools = await client.listTools();
		166	expect(tools.tools.map(({ name }) => name)).toContain("execute");
		167	expect(tools.tools.map(({ name }) => name)).toContain("execute-action");
		168
		169	const result = await client.callTool({
		170	name: "execute",
		171	arguments: { code: "await tools.test.approve()" },
		172	});
		173	expect(result.content).toEqual([{ type: "text", text: "approved" }]);
		174	expect(result.isError).toBeFalsy();
		175	expect(elicitationRequests).toBe(1);
		176	expect(resumedWith()).toEqual({ action: "accept", content: { value: "approved" } });
		177	expect(sessions.sessionCount()).toBe(1);
		178	} finally {
		179	await client.close();
		180	await sessions.close();
		181	}
		182	});
54	});	183	});

packages/hosts/mcp/src/in-memory-session-store.ts+32−6

 import { Cause, Data, Effect, Layer } from "effect";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+  type McpServer,
+  WebStandardStreamableHTTPServerTransport,
+} from "@modelcontextprotocol/server";
 import { formatPausedExecution, type ExecutionEngine } from "@executor-js/execution";
   type Principal,
   type McpResource,
 } from "./seams";
-import type { BrowserApprovalStore } from "./tool-server";
+import { mcpRequestStatePrincipal, type BrowserApprovalStore } from "./tool-server-v2";
 // ---------------------------------------------------------------------------
 // In-process McpSessionStore — the single-node serving store, shared by every
    *  with `?artifacts=false`; opted out, the built server registers none of
    *  the artifact tools, resource, or skills. */
   readonly artifactsEnabled?: boolean;
+  /** The sessionful v2 assembly starts disabled and replaces this from initialize. */
+  readonly appsEnabled: false;
+  /** Process-lifetime HMAC key for the v2 legacy-shim continuation state. */
+  readonly requestStateSigningKey: Uint8Array;
+  /** Stable authenticated owner bound into continuation state. */
+  readonly requestStatePrincipal: string;
+  /** Selects live negotiated capabilities instead of stateless request policy. */
+  readonly sessionful: true;
 }
 /** Build the per-session `McpServer` + engine for a principal (the host's engine + tools). */
 export type McpBuildServer = (
   principal: Principal,
-  options?: McpBuildServerOptions,
+  options: McpBuildServerOptions,
 ) => Effect.Effect<BuiltMcpServer, McpEngineBuildError>;
 export interface InMemoryMcpSessionStore {
     request: Request,
     principal?: Principal,
   ) => Promise<Response | null>;
+  /** Number of live initialized sessions currently owned by this store. */
+  readonly sessionCount: () => number;
   /** Dispose every live session — wire into the host's shutdown (not a seam). */
   readonly close: () => Promise<void>;
 }
+type McpRequestBuildOptions = Pick<
+  McpBuildServerOptions,
+  "artifactsEnabled" | "browserApprovalStore" | "elicitationMode"
+>;
 const ignoreClose = (close: (() => Promise<void>) | undefined): Promise<void> =>
   close
     ? Effect.runPromise(Effect.ignore(Effect.tryPromise({ try: close, catch: () => undefined })))
   const owners = new Map<string, SessionOwner>();
   const engines = new Map<string, ExecutionEngine<Cause.YieldableError>>();
   const approvals: InProcessBrowserApprovalStore = makeInProcessBrowserApprovalStore();
+  const requestStateSigningKey = crypto.getRandomValues(new Uint8Array(32));
   const dispose = async (id: string, opts: { transport?: boolean; server?: boolean } = {}) => {
     const transport = transports.get(id);
   const buildOptionsFor = (
     request: Request,
     sessionId: () => string | null,
-  ): McpBuildServerOptions => {
+  ): McpRequestBuildOptions => {
     const artifactsEnabled = readArtifactsEnabled(request);
     const mode = readElicitationMode(request);
     if (mode !== "browser") return { artifactsEnabled, elicitationMode: { mode } };
     return buildServer(principal, {
       ...buildOptionsFor(request, () => createdSessionId),
       resource,
+      appsEnabled: false,
+      requestStateSigningKey,
+      requestStatePrincipal: mcpRequestStatePrincipal(principal),
+      sessionful: true,
     }).pipe(
       Effect.flatMap(({ mcpServer, engine }) =>
         Effect.gen(function* () {
           const transport = new WebStandardStreamableHTTPServerTransport({
             sessionIdGenerator: () => crypto.randomUUID(),
-            enableJsonResponse: true,
+            // Native mode needs an open SSE response for the v2 legacy shim's
+            // server→client elicitation request. Other modes preserve the
+            // store's existing single-JSON response behavior.
+            enableJsonResponse: readElicitationMode(request) !== "native",
             onsessioninitialized: (sid) => {
               createdSessionId = sid;
               transports.set(sid, transport);
     store,
     handlePausedRequest,
     handleApprovalRequest,
+    sessionCount: () => transports.size,
     close: async () => {
       const ids = new Set([...transports.keys(), ...servers.keys()]);
       await Promise.all([...ids].map((id) => dispose(id, { transport: true, server: true })));

packages/hosts/mcp/src/index.ts+4−5

 // its seams (`McpAuthProvider` / `McpSessionStore` / `McpErrorReporter` /
 // `Principal`) + the canonical JSON-RPC error renderer (`jsonRpcErrorBody`).
 //
-// The executor TOOL factory (`createExecutorMcpServer` — the execute/resume
+// The executor tool assemblies (execute/resume tools, elicitation and browser
-// tools, the elicitation/browser-approval bridge, the Zod input schemas) is a
+// approval bridges, Zod input schemas) are a different center of gravity. They
-// different center of gravity: a host's session store builds an `McpServer`
+// live behind the `tool-server` and `tool-server-v2` subpaths so this serving
-// from it. It lives behind the `@executor-js/host-mcp/tool-server` subpath so
+// surface stays small and dependency-light.
-// the serving surface stays small and dependency-light.
 // ---------------------------------------------------------------------------
 export {

packages/hosts/mcp/src/stdio-integration.test.ts+83−4

@@ -1,6 +1,9 @@
1	import { describe, expect, it } from "@effect/vitest";	1	import { describe, expect, it } from "@effect/vitest";
		2	import { Client as ModernClient } from "@modelcontextprotocol/client";
		3	import { StdioClientTransport as ModernStdioClientTransport } from "@modelcontextprotocol/client/stdio";
2	import { Client } from "@modelcontextprotocol/sdk/client/index.js";	4	import { Client } from "@modelcontextprotocol/sdk/client/index.js";
3	import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";	5	import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
		6	import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
4	import { Effect } from "effect";	7	import { Effect } from "effect";
5	import { mkdtempSync } from "node:fs";	8	import { mkdtempSync } from "node:fs";
6	import { tmpdir } from "node:os";	9	import { tmpdir } from "node:os";
@@ -9,22 +12,25 @@ import { join, resolve } from "node:path"; · 2 unmodified lines
9	const repoRoot = resolve(import.meta.dirname, "../../../..");	12	const repoRoot = resolve(import.meta.dirname, "../../../..");
10	const cliEntry = resolve(repoRoot, "apps/cli/src/main.ts");	13	const cliEntry = resolve(repoRoot, "apps/cli/src/main.ts");
11	const testScope = resolve(repoRoot, "apps/local");	14	const testScope = resolve(repoRoot, "apps/local");
		15	const stdioServerEntry = resolve(repoRoot, "apps/local/src/mcp-stdio-test-server.ts");
		16	const stdioServer = {
		17	command: "bun",
		18	args: ["run", stdioServerEntry],
		19	};
12		20
13	describe("MCP stdio integration", () => {	21	describe("MCP stdio integration", () => {
14	it.effect(	22	it.effect(
15	"execute tool returns result over stdio transport",	23	"execute tool returns result over the CLI stdio bridge",
16	() =>	24	() =>
17	Effect.gen(function* () {	25	Effect.gen(function* () {
18	// Fresh temp dir so the test doesn't migrate against the developer's	26	// Fresh temp dir so the test doesn't migrate against the developer's
19	// real ~/.executor/data.db.	27	// real ~/.executor/data.db.
20	const dataDir = mkdtempSync(join(tmpdir(), "executor-mcp-test-"));	28	const dataDir = mkdtempSync(join(tmpdir(), "executor-mcp-test-"));
21
22	const transport = new StdioClientTransport({	29	const transport = new StdioClientTransport({
23	command: "bun",	30	command: "bun",
24	args: ["run", cliEntry, "mcp", "--scope", testScope],	31	args: ["run", cliEntry, "mcp", "--scope", testScope],
25	env: { ...process.env, EXECUTOR_DATA_DIR: dataDir },	32	env: { ...process.env, EXECUTOR_DATA_DIR: dataDir },
26	});	33	});
27
28	const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });	34	const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
29		35
30	yield* Effect.acquireRelease(	36	yield* Effect.acquireRelease(
@@ -33,7 +39,7 @@ describe("MCP stdio integration", () => { · 2 unmodified lines
33	);	39	);
34		40
35	const { tools } = yield* Effect.promise(() => client.listTools());	41	const { tools } = yield* Effect.promise(() => client.listTools());
36	expect(tools.map((t) => t.name)).toContain("execute");	42	expect(tools.map(({ name }) => name)).toContain("execute");
37		43
38	const result = yield* Effect.promise(() =>	44	const result = yield* Effect.promise(() =>
39	client.callTool({	45	client.callTool({
@@ -48,4 +54,77 @@ describe("MCP stdio integration", () => { · 8 unmodified lines
48	}).pipe(Effect.scoped),	54	}).pipe(Effect.scoped),
49	{ timeout: 30_000 },	55	{ timeout: 30_000 },
50	);	56	);
		57
		58	it.effect(
		59	"serves a legacy client and completes the native elicitation round-trip",
		60	() =>
		61	Effect.gen(function* () {
		62	const transport = new StdioClientTransport(stdioServer);
		63	const client = new Client(
		64	{ name: "legacy-stdio-test-client", version: "1.0.0" },
		65	{ capabilities: { elicitation: { form: {} } } },
		66	);
		67	let elicitationRequests = 0;
		68	client.setRequestHandler(ElicitRequestSchema, async (request) => {
		69	elicitationRequests += 1;
		70	expect(request.params).toMatchObject({ message: "Approve the stdio action?" });
		71	return { action: "accept" as const, content: { value: "approved" } };
		72	});
		73
		74	yield* Effect.acquireRelease(
		75	Effect.promise(() => client.connect(transport)),
		76	() => Effect.promise(() => transport.close()),
		77	);
		78
		79	const { tools } = yield* Effect.promise(() => client.listTools());
		80	expect(tools.map((t) => t.name)).toContain("execute");
		81
		82	const result = yield* Effect.promise(() =>
		83	client.callTool({
		84	name: "execute",
		85	arguments: { code: "needs approval" },
		86	}),
		87	);
		88
		89	const text = (result.content as Array<{ type: string; text: string }>)[0]?.text;
		90	expect(text).toContain("approved");
		91	expect(result.isError).toBeFalsy();
		92	expect(elicitationRequests).toBe(1);
		93	}).pipe(Effect.scoped),
		94	{ timeout: 30_000 },
		95	);
		96
		97	it.effect(
		98	"serves a modern-pinned client over the same v2 stdio entry",
		99	() =>
		100	Effect.gen(function* () {
		101	const transport = new ModernStdioClientTransport(stdioServer);
		102	const client = new ModernClient(
		103	{ name: "modern-stdio-test-client", version: "1.0.0" },
		104	{
		105	capabilities: {},
		106	versionNegotiation: { mode: { pin: "2026-07-28" } },
		107	},
		108	);
		109
		110	yield* Effect.acquireRelease(
		111	Effect.promise(() => client.connect(transport)),
		112	() => Effect.promise(() => transport.close()),
		113	);
		114
		115	const { tools } = yield* Effect.promise(() => client.listTools());
		116	expect(tools.map(({ name }) => name)).toContain("execute");
		117
		118	const result = yield* Effect.promise(() =>
		119	client.callTool({
		120	name: "execute",
		121	arguments: { code: "return 2+2" },
		122	}),
		123	);
		124
		125	expect(result.content).toEqual([{ type: "text", text: "4" }]);
		126	expect(result.isError).toBeFalsy();
		127	}).pipe(Effect.scoped),
		128	{ timeout: 30_000 },
		129	);
51	});	130	});

packages/hosts/mcp/src/tool-server-shared.ts+1−1

@@ -2152,7 +2152,7 @@ export const createExecutorMcpServerAssembly = < · 2151 unmodified lines
2152	// persisting an absent-capability reading would make a downgrade durable	2152	// persisting an absent-capability reading would make a downgrade durable
2153	// for every future restore of the session.	2153	// for every future restore of the session.
2154	const onAppsEnabledChange = config.onAppsEnabledChange;	2154	const onAppsEnabledChange = config.onAppsEnabledChange;
2155	if (assembly.era === "v1" && clientCapabilities && changed && onAppsEnabledChange) {	2155	if (clientCapabilities && changed && onAppsEnabledChange) {
2156	// oxlint-disable-next-line executor/no-effect-escape-hatch -- boundary: `oninitialized` is a sync SDK hook; persistence is fire-and-forget and its failure must not fail the session	2156	// oxlint-disable-next-line executor/no-effect-escape-hatch -- boundary: `oninitialized` is a sync SDK hook; persistence is fire-and-forget and its failure must not fail the session
2157	void Effect.runPromiseWith(context)(	2157	void Effect.runPromiseWith(context)(
2158	onAppsEnabledChange(negotiated).pipe(Effect.ignoreCause({ log: false })),	2158	onAppsEnabledChange(negotiated).pipe(Effect.ignoreCause({ log: false })),

packages/hosts/mcp/src/tool-server-v2.ts+69−29

 /**
- * Stateless MCP SDK v2 assembly for the 2026-07-28 protocol era.
+ * MCP SDK v2 assembly shared by stateless modern requests and sessionful
- *
+ * connections. Stateless callers supply request-scoped capability policy;
- * Neutral hosts call {@link buildMcpServerV2} from a `createMcpHandler`
+ * sessionful callers register the full surface once and read negotiated client
- * `McpServerFactory`, once per request. The factory's
+ * capabilities from the live server.
- * `McpRequestContext.requestInfo` exposes the original HTTP request, which
- * {@link clientCapabilitiesFromRequest} parses for the request-scoped
- * {@link appsEnabledForClientCapabilities} decision. Legacy routing remains a
- * separate host path.
  */
 import { Data, Effect, Match, Option, Schema } from "effect";
 import * as Cause from "effect/Cause";
   type NativeExecutionServices,
 } from "./tool-server-shared";
+export type { BrowserApprovalStore, ExecutorMcpServerConfig } from "./tool-server-shared";
 const NATIVE_ELICITATION_RESPONSE_KEY = "elicitation";
 const NativeRequestStateSchema = Schema.Struct({ executionId: Schema.String });
   readonly serverContext: ServerContext;
 };
-/** Additional request-scoped inputs required by the SDK v2 assembly. */
+/** Additional serving inputs required by the SDK v2 assembly. */
 export type ExecutorMcpServerV2Config<E extends Cause.YieldableError = Cause.YieldableError> =
   ExecutorMcpServerConfig<E> & {
-    /** Whether this request's client can render MCP Apps resources. */
+    /** Initial/static MCP Apps policy. Sessionful servers replace it after initialize. */
     readonly appsEnabled: boolean;
+    /**
+     * Register a connection-lifetime server whose capability-dependent behavior
+     * follows the live initialize-negotiated state. Omitted for stateless modern
+     * request factories, which keep using {@link appsEnabled} as fixed policy.
+     */
+    readonly sessionful?: boolean;
     /** HMAC key used to sign opaque native-elicitation continuation state. */
     readonly requestStateSigningKey: Uint8Array | string;
     /**
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
-/** Parse the MCP Apps capability subset from an already-decoded modern body. */
+const appsClientCapabilitiesFromUnknown = (
-export const clientCapabilitiesFromRequestBody = (
+  capabilities: unknown,
-  body: unknown,
 ): McpAppsClientCapabilities | null => {
-  if (!isRecord(body)) return null;
-  const params = body.params;
-  if (!isRecord(params)) return null;
-  const metadata = params._meta;
-  if (!isRecord(metadata)) return null;
-  const capabilities = metadata[CLIENT_CAPABILITIES_META_KEY];
   if (!isRecord(capabilities)) return null;
   const extensions = capabilities.extensions;
   if (!isRecord(extensions)) return null;
   return { extensions: { [EXTENSION_ID]: { mimeTypes } } };
 };
+const elicitationSupportFromUnknown = (
+  capabilities: unknown,
+): { readonly form: boolean; readonly url: boolean } => {
+  if (!isRecord(capabilities) || !isRecord(capabilities.elicitation)) {
+    return { form: false, url: false };
+  }
+  const elicitation = capabilities.elicitation;
+  const hasExplicitModes = "form" in elicitation || "url" in elicitation;
+  return {
+    form: hasExplicitModes ? Boolean(elicitation.form) : true,
+    url: Boolean(elicitation.url),
+  };
+};
+/** Parse the MCP Apps capability subset from an already-decoded modern body. */
+export const clientCapabilitiesFromRequestBody = (
+  body: unknown,
+): McpAppsClientCapabilities | null => {
+  if (!isRecord(body)) return null;
+  const params = body.params;
+  if (!isRecord(params)) return null;
+  const metadata = params._meta;
+  if (!isRecord(metadata)) return null;
+  const capabilities = metadata[CLIENT_CAPABILITIES_META_KEY];
+  return appsClientCapabilitiesFromUnknown(capabilities);
+};
 /** Parse a cloned HTTP request body without consuming the request itself. */
 export const requestBodyFromRequest = (request: Request): Effect.Effect<unknown> =>
   Effect.tryPromise({
 const createV2Assembly = <E extends Cause.YieldableError>(
   config: ExecutorMcpServerV2Config<E>,
 ): ExecutorMcpAssembly<McpServer, V2RequestContext> => {
+  const sessionful = config.sessionful ?? false;
+  const initialAppsEnabled = sessionful
+    ? (config.restoredAppsEnabled ?? config.appsEnabled)
+    : config.appsEnabled;
   const requestStateCodec = createRequestStateCodec<NativeRequestState>({
     key: config.requestStateSigningKey,
     ...(config.requestStateTtlSeconds === undefined
   ) => {
     const inputSchema = z.object(toolConfig.inputSchema);
     const metadata = normalizedAppMetadata(toolConfig._meta);
-    if (!config.appsEnabled && visibilityIncludes(metadata, "model")) {
+    if (!sessionful && !config.appsEnabled && visibilityIncludes(metadata, "model")) {
       const plainMetadata = withoutAppMetadata(metadata);
       return server.registerTool<z.ZodObject<z.ZodRawShape>, typeof inputSchema>(
         name,
   return {
     server,
     era: "v2",
-    initialAppsEnabled: config.appsEnabled,
+    initialAppsEnabled,
-    getClientCapabilities: () => null,
+    getClientCapabilities: () =>
-    getElicitationSupport: () => ({ form: true, url: true }),
+      sessionful ? (server.server.getClientCapabilities() ?? null) : null,
-    getUiCapability: () => (config.appsEnabled ? { mimeTypes: [RESOURCE_MIME_TYPE] } : undefined),
+    getElicitationSupport: () =>
-    onInitialized: () => undefined,
+      sessionful
+        ? elicitationSupportFromUnknown(server.server.getClientCapabilities())
+        : { form: true, url: true },
+    getUiCapability: () =>
+      sessionful
+        ? getUiCapability(appsClientCapabilitiesFromUnknown(server.server.getClientCapabilities()))
+        : config.appsEnabled
+          ? { mimeTypes: [RESOURCE_MIME_TYPE] }
+          : undefined,
+    onInitialized: (callback) => {
+      if (sessionful) server.server.oninitialized = callback;
+    },
     registerTool,
     registerAppTool: registerApp,
     registerAppResource: (name, uri, resourceConfig, callback) => {
-      if (!config.appsEnabled) return;
+      if (!sessionful && !config.appsEnabled) return;
       registerAppResource(server, name, uri, resourceConfig, async () => {
         const result = await callback();
         return { contents: [...result.contents] };
 };
 /**
- * Build one stateless SDK v2 Executor MCP server for a modern request.
+ * Build one SDK v2 Executor MCP server.
  *
- * Hosts must reuse the signing key across every request that can participate
+ * Stateless hosts must reuse the signing key across every request that can
- * in the same native-elicitation continuation flow.
+ * participate in the same native-elicitation continuation flow. Sessionful
+ * hosts keep one instance connected and may use a connection-lifetime key.
  */
 export const buildMcpServerV2 = <E extends Cause.YieldableError>(
   config: ExecutorMcpServerV2Config<E>,