lael-labs/executor

apps/executor/src/cli/main.ts+10−12

@@ -652,18 +652,16 @@ const stopServer = (baseUrl: string) => · 651 unmodified lines
652	const pid = typeof pidRecord?.pid === "number" ? pidRecord.pid : null;	652	const pid = typeof pidRecord?.pid === "number" ? pidRecord.pid : null;
653		653
654	if (pid === null) {	654	if (pid === null) {
655	yield* Effect.tryPromise({	655	yield* Effect.tryPromise(() => rm(DEFAULT_SERVER_PID_FILE, { force: true })).pipe(
656	try: () => rm(DEFAULT_SERVER_PID_FILE, { force: true }),	656	Effect.ignore,
657	catch: () => undefined,	657	);
658	});
659	return false;	658	return false;
660	}	659	}
661		660
662	if (!isPidRunning(pid)) {	661	if (!isPidRunning(pid)) {
663	yield* Effect.tryPromise({	662	yield* Effect.tryPromise(() => rm(DEFAULT_SERVER_PID_FILE, { force: true })).pipe(
664	try: () => rm(DEFAULT_SERVER_PID_FILE, { force: true }),	663	Effect.ignore,
665	catch: () => undefined,	664	);
666	});
667	return false;	665	return false;
668	}	666	}
669		667
@@ -674,10 +672,10 @@ const stopServer = (baseUrl: string) => · 4 unmodified lines
674		672
675	yield* waitForReachability(baseUrl, false).pipe(	673	yield* waitForReachability(baseUrl, false).pipe(
676	Effect.catchAll(() =>	674	Effect.catchAll(() =>
677	Effect.tryPromise({	675	Effect.tryPromise(() => rm(DEFAULT_SERVER_PID_FILE, { force: true })).pipe(
678	try: () => rm(DEFAULT_SERVER_PID_FILE, { force: true }),	676	Effect.ignore,
679	catch: () => undefined,	677	Effect.zipRight(Effect.fail(new Error(`Timed out stopping local executor server pid ${pid}`))),
680	}).pipe(Effect.zipRight(Effect.fail(new Error(`Timed out stopping local executor server pid ${pid}`)))),	678	),
681	),	679	),
682	);	680	);
683		681

apps/executor/src/distribution/harness.ts+2−1

@@ -176,7 +176,8 @@ export const LocalDistributionHarnessLive = Layer.scoped( · 175 unmodified lines
176	}),	176	}),
177	(path) => Effect.tryPromise({	177	(path) => Effect.tryPromise({
178	try: () => rm(path, { recursive: true, force: true }),	178	try: () => rm(path, { recursive: true, force: true }),
179	catch: () => undefined,	179	catch: (cause) =>
		180	cause instanceof Error ? cause : new Error(String(cause ?? "temp dir cleanup failed")),
180	}).pipe(Effect.orDie),	181	}).pipe(Effect.orDie),
181	);	182	);
182		183

apps/executor/src/server/server.test.ts+9−8

@@ -647,12 +647,13 @@ describe("local-executor-server", () => { · 646 unmodified lines
647	});	647	});
648		648
649	const listed = yield* Effect.promise(	649	const listed = yield* Effect.promise(
650	() => mcp.client.listTools() as Promise<{ tools: Array<{ name: string }> }>,	650	() => mcp.client.listTools() as Promise<{ tools: Array<{ name: string; description?: string }> }>,
651	);	651	);
652	expect(listed.tools.map((tool) => tool.name)).toEqual(["execute"]);	652	expect(listed.tools.map((tool) => tool.name)).toEqual(["execute"]);
653	expect(mcp.client.getInstructions()).toContain(	653	expect(listed.tools[0]?.description).toContain("Workflow:");
654	`npx add-mcp \"${server.baseUrl}/mcp\" --transport http --name \"executor\"`,	654	expect(listed.tools[0]?.description).toContain("tools.discover");
655	);	655	expect(listed.tools[0]?.description).toContain("tools.executor.sources.add");
		656
656		657
657	const executed = yield* Effect.promise(	658	const executed = yield* Effect.promise(
658	() =>	659	() =>
@@ -686,12 +687,12 @@ describe("local-executor-server", () => { · 27 unmodified lines
686	});	687	});
687		688
688	const listed = yield* Effect.promise(	689	const listed = yield* Effect.promise(
689	() => mcp.client.listTools() as Promise<{ tools: Array<{ name: string }> }>,	690	() => mcp.client.listTools() as Promise<{ tools: Array<{ name: string; description?: string }> }>,
690	);	691	);
691	expect(listed.tools.map((tool) => tool.name).sort()).toEqual(["execute", "resume"]);	692	expect(listed.tools.map((tool) => tool.name).sort()).toEqual(["execute", "resume"]);
692	expect(mcp.client.getInstructions()).toContain(	693	expect(listed.tools.find((tool) => tool.name === "execute")?.description).toContain("Workflow:");
693	`npx add-mcp \"${server.baseUrl}/mcp\" --transport http --name \"executor\"`,	694	expect(listed.tools.find((tool) => tool.name === "execute")?.description).toContain("tools.discover");
694	);	695
695		696
696	const executed = yield* Effect.promise(	697	const executed = yield* Effect.promise(
697	() =>	698	() =>

apps/web/src/components/local-mcp-install-card.tsx+37−0

@@ -0,0 +1,37 @@
	1	import { useEffect, useMemo, useState } from "react";
	2	import { CodeBlock } from "./code-block";
	3
	4	export function LocalMcpInstallCard(props: {
	5	title?: string;
	6	description?: string;
	7	className?: string;
	8	}) {
	9	const [origin, setOrigin] = useState<string \| null>(null);
	10
	11	useEffect(() => {
	12	setOrigin(window.location.origin);
	13	}, []);
	14
	15	const command = useMemo(
	16	() =>
	17	origin
	18	? `npx add-mcp "${origin}/mcp" --transport http --name "executor"`
	19	: 'npx add-mcp "<this-server>/mcp" --transport http --name "executor"',
	20	[origin],
	21	);
	22
	23	return (
	24	<section className={props.className ?? "rounded-2xl border border-border bg-card/80 p-5"}>
	25	<div className="mb-3 space-y-1">
	26	<h2 className="text-sm font-semibold text-foreground">
	27	{props.title ?? "Install local MCP"}
	28	</h2>
	29	<p className="text-[13px] text-muted-foreground">
	30	{props.description
	31	?? "Add this local executor server to an MCP client with one command. The URL uses the same origin as this web app."}
	32	</p>
	33	</div>
	34	<CodeBlock code={command} lang="bash" className="rounded-xl border border-border bg-background/70" />
	35	</section>
	36	);
	37	}

apps/web/src/dev.ts+48−20

@@ -5,7 +5,10 @@ · 4 unmodified lines
5	* control-plane handler. Everything else (frontend assets, HMR) is	5	* control-plane handler. Everything else (frontend assets, HMR) is
6	* handled by Vite itself.	6	* handled by Vite itself.
7	*/	7	*/
		8	import * as Cause from "effect/Cause";
8	import * as Effect from "effect/Effect";	9	import * as Effect from "effect/Effect";
		10	import * as Exit from "effect/Exit";
		11	import * as Runtime from "effect/Runtime";
9	import * as Scope from "effect/Scope";	12	import * as Scope from "effect/Scope";
10	import { createLocalExecutorRequestHandler } from "@executor-v3/server";	13	import { createLocalExecutorRequestHandler } from "@executor-v3/server";
11		14
@@ -16,28 +19,53 @@ const truncateForLog = (value: string): string => · 4 unmodified lines
16	? `${value.slice(0, MAX_LOGGED_ERROR_BODY_LENGTH)}... [truncated]`	19	? `${value.slice(0, MAX_LOGGED_ERROR_BODY_LENGTH)}... [truncated]`
17	: value;	20	: value;
18		21
19	const formatErrorForLog = (error: unknown) =>	22	/**
20	error instanceof Error	23	* Extract a detailed, human-readable description from an error.
21	? {	24	*
22	name: error.name,	25	* When Effect rejects via `runPromise`, the thrown value is a
23	message: error.message,	26	* `FiberFailure` wrapping a `Cause`. `Cause.pretty` renders the full
24	stack: error.stack,	27	* failure tree (defects, interrupts, tagged errors, etc.) rather than the
25	}	28	* opaque fallback message ("An error has occurred").
26	: error;	29	*/
		30	const formatErrorForLog = (error: unknown): string => {
		31	if (Runtime.isFiberFailure(error)) {
		32	const cause = error[Runtime.FiberFailureCauseId];
		33	return Cause.pretty(cause);
		34	}
		35
		36	if (error instanceof Error) {
		37	return error.stack ?? error.message;
		38	}
		39
		40	return String(error);
		41	};
27		42
28	// Create a long-lived scope that stays open for the lifetime of the process.	43	// Create a long-lived scope that stays open for the lifetime of the process.
29	const handlerPromise = Effect.runPromise(	44	const handlerPromise = (async () => {
30	Effect.gen(function* () {	45	const exit = await Effect.runPromiseExit(
31	const scope = yield* Scope.make();	46	Effect.gen(function* () {
32	const handler = yield* createLocalExecutorRequestHandler().pipe(	47	const scope = yield* Scope.make();
33	Effect.provideService(Scope.Scope, scope),	48	const handler = yield* createLocalExecutorRequestHandler().pipe(
34	);	49	Effect.provideService(Scope.Scope, scope),
35	return handler;	50	);
36	}),	51	return handler;
37	).catch((error) => {	52	}),
38	console.error("[executor dev api] failed to initialize request handler", formatErrorForLog(error));	53	);
39	throw error;	54
40	});	55	if (Exit.isSuccess(exit)) {
		56	return exit.value;
		57	}
		58
		59	// Log the full Cause tree — this captures typed errors, defects (uncaught
		60	// throws), and interrupts with their original stack traces.
		61	console.error(
		62	"[executor dev api] failed to initialize request handler\n\n" +
		63	Cause.pretty(exit.cause),
		64	);
		65
		66	// Re-throw so every subsequent request sees the init failure.
		67	throw Cause.squash(exit.cause);
		68	})();
41		69
42	export default {	70	export default {
43	async fetch(request: Request) {	71	async fetch(request: Request) {

apps/web/src/views/add-source.tsx+9−0

 } from "@executor-v3/react";
 import { Badge } from "../components/ui/badge";
 import { Button } from "../components/ui/button";
+import { LocalMcpInstallCard } from "../components/local-mcp-install-card";
 import { SourceFavicon } from "../components/source-favicon";
 import {
   IconArrowLeft,
         {statusBanner && <StatusBanner state={statusBanner} className="mb-6" />}
+        {(phase === "idle" || phase === "discovering") && (
+          <LocalMcpInstallCard
+            className="mb-6 rounded-xl border border-border bg-card/80 p-5"
+            title="Install this executor as MCP"
+            description="Prefer a one-command setup? Install this local executor server into your MCP client, or add an external MCP source below."
+          />
+        )}
         {/* Step 1: Discovery */}
         {(phase === "idle" || phase === "discovering") && (
           <div className="space-y-6">

apps/web/src/views/home.tsx+3−0

 import { Link } from "@tanstack/react-router";
 import { useSources, type Source } from "@executor-v3/react";
 import { LoadableBlock } from "../components/loadable";
+import { LocalMcpInstallCard } from "../components/local-mcp-install-card";
 import { SourceFavicon } from "../components/source-favicon";
 import { Badge } from "../components/ui/badge";
 import { Button } from "../components/ui/button";
           </Link>
         </div>
+        <LocalMcpInstallCard className="mb-8" />
         {/* Source list */}
         <LoadableBlock loadable={sources} loading="Loading sources...">
           {(items) =>

apps/web/vite.config.ts+2−2

@@ -11,8 +11,8 @@ export default defineConfig({ · 10 unmodified lines
11	devServer({	11	devServer({
12	entry: "src/dev.ts",	12	entry: "src/dev.ts",
13	exclude: [	13	exclude: [
14	// Only let /v1 requests reach the API handler	14	// Only let /v1 and /mcp requests reach the API handler
15	/^\/(?!v1(\/\|$))/,	15	/^\/(?!(v1\|mcp)(\/\|$))/,
16	/^\/(src\|node_modules\|@vite\|@id\|@react-refresh)/,	16	/^\/(src\|node_modules\|@vite\|@id\|@react-refresh)/,
17	/\.(css\|ts\|tsx\|js\|jsx\|svg\|png\|jpg\|gif\|ico\|woff2?\|json\|map)(\?.*)?$/,	17	/\.(css\|ts\|tsx\|js\|jsx\|svg\|png\|jpg\|gif\|ico\|woff2?\|json\|map)(\?.*)?$/,
18	],	18	],

packages/codemode-mcp/src/mcp-tools.ts+18−6

 import * as Data from "effect/Data";
 import * as Either from "effect/Either";
 import * as Effect from "effect/Effect";
+import * as Cause from "effect/Cause";
+import * as Exit from "effect/Exit";
 import * as PartitionedSemaphore from "effect/PartitionedSemaphore";
 import {
 const closeConnection = (connection: McpConnection): Effect.Effect<void> =>
   Effect.tryPromise({
     try: () => connection.close?.() ?? Promise.resolve(),
-    catch: () => undefined,
+    catch: (cause) =>
+      cause instanceof Error ? cause : new Error(String(cause ?? "mcp connection close failed")),
   }).pipe(
     Effect.asVoid,
-    Effect.catchAll(() => Effect.succeed(undefined)),
+    Effect.catchAll(() => Effect.void),
   );
 const withConnectionEffect = <A, E>(input: {
               }),
             ),
             Effect.map(toMcpElicitationResponse),
-            Effect.catchAll(() => Effect.succeed({ action: "cancel" as const })),
+            Effect.catchAll((error) => {
+              console.error(
+                `[mcp-tools] elicitation failed for ${input.toolName}, treating as cancel:`,
+                error instanceof Error ? error.message : String(error),
+              );
+              return Effect.succeed({ action: "cancel" as const });
+            }),
           ),
         );
       });
           tool: {
             description: entry.description ?? `MCP tool: ${entry.toolName}`,
             inputSchema: inputSchemaFromManifest(entry.inputSchemaJson),
-            execute: (args: unknown, executionContext?: ToolExecutionContext) =>
+            execute: async (args: unknown, executionContext?: ToolExecutionContext) => {
-              Effect.runPromise(
+              const exit = await Effect.runPromiseExit(
                 withConnectionEffect({
                   connect: input.connect,
                   onConnectError: (cause) =>
                       : callEffect;
                   },
                 }),
-              ),
+              );
+              if (Exit.isSuccess(exit)) return exit.value;
+              throw Cause.squash(exit.cause);
+            },
           },
           metadata: {
             sourceKey,

packages/control-plane/src/persistence/index.ts+4−2

 const closeRuntimeEffect = (runtime: SqlRuntime) =>
   Effect.tryPromise({
     try: () => runtime.close(),
-    catch: () => undefined,
+    catch: (cause) =>
+      cause instanceof Error ? cause : new Error(String(cause ?? "unknown close error")),
   }).pipe(Effect.orDie);
 export const createSqlControlPlanePersistence = (
       (persistence) =>
         Effect.tryPromise({
           try: () => persistence.close(),
-          catch: () => undefined,
+          catch: (cause) =>
+            cause instanceof Error ? cause : new Error(String(cause ?? "unknown close error")),
         }).pipe(Effect.orDie),
     ),
   );

packages/control-plane/src/persistence/sql-runtime.ts+43−2

@@ -3,8 +3,8 @@ import { drizzle as drizzlePGlite } from "drizzle-orm/pglite"; · 2 unmodified lines
3	import { migrate as migratePGlite } from "drizzle-orm/pglite/migrator";	3	import { migrate as migratePGlite } from "drizzle-orm/pglite/migrator";
4	import { drizzle as drizzlePostgres } from "drizzle-orm/postgres-js";	4	import { drizzle as drizzlePostgres } from "drizzle-orm/postgres-js";
5	import { migrate as migratePostgres } from "drizzle-orm/postgres-js/migrator";	5	import { migrate as migratePostgres } from "drizzle-orm/postgres-js/migrator";
6	import { existsSync, readdirSync } from "node:fs";	6	import { existsSync, readdirSync, readFileSync } from "node:fs";
7	import { mkdir } from "node:fs/promises";	7	import { mkdir, unlink } from "node:fs/promises";
8	import * as path from "node:path";	8	import * as path from "node:path";
9	import { fileURLToPath } from "node:url";	9	import { fileURLToPath } from "node:url";
10	import postgres from "postgres";	10	import postgres from "postgres";
@@ -44,6 +44,46 @@ const trim = (value: string \| undefined): string \| undefined => { · 33 unmodified lines
44	const isPostgresUrl = (value: string): boolean =>	44	const isPostgresUrl = (value: string): boolean =>
45	value.startsWith("postgres://") \|\| value.startsWith("postgresql://");	45	value.startsWith("postgres://") \|\| value.startsWith("postgresql://");
46		46
		47	/**
		48	* Remove a stale PGlite `postmaster.pid` lock file if present.
		49	*
		50	* PGlite writes this file on open and removes it on close. When a process
		51	* exits without calling `PGlite.close()` (e.g. the Vite dev server is
		52	* killed with SIGKILL, or the terminal is closed), the lock file is left
		53	* behind and prevents subsequent PGlite instances from opening the
		54	* database. PGlite uses a synthetic PID (e.g. `-42`) that is never a real
		55	* OS process, so we cannot use it to detect a live owner. Instead we rely
		56	* on the fact that in the local single-user context only one process
		57	* should ever own this database at a time.
		58	*/
		59	const cleanupStalePGliteLock = async (dataDir: string): Promise<void> => {
		60	const lockPath = path.join(dataDir, "postmaster.pid");
		61	if (!existsSync(lockPath)) {
		62	return;
		63	}
		64
		65	// PGlite's synthetic PID is always negative (e.g. -42). A real Postgres
		66	// postmaster would write a positive PID. If we ever see a positive PID
		67	// we leave the file alone.
		68	try {
		69	const content = readFileSync(lockPath, "utf-8");
		70	const firstLine = content.split("\n")[0]?.trim();
		71	const pid = Number(firstLine);
		72	if (!Number.isNaN(pid) && pid > 0) {
		73	// Looks like a real Postgres PID — don't touch it.
		74	return;
		75	}
		76	} catch {
		77	// If we can't read the file, try to remove it anyway.
		78	}
		79
		80	try {
		81	await unlink(lockPath);
		82	} catch {
		83	// Best-effort cleanup; PGlite will report the real error if this fails.
		84	}
		85	};
		86
47	const createPGliteRuntime = async (localDataDir: string): Promise<SqlRuntime> => {	87	const createPGliteRuntime = async (localDataDir: string): Promise<SqlRuntime> => {
48	const normalized = trim(localDataDir) ?? ".executor-v3/control-plane-pgdata";	88	const normalized = trim(localDataDir) ?? ".executor-v3/control-plane-pgdata";
49		89
@@ -55,6 +95,7 @@ const createPGliteRuntime = async (localDataDir: string): Promise<SqlRuntime> => · 5 unmodified lines
55	if (!existsSync(resolvedDataDir)) {	95	if (!existsSync(resolvedDataDir)) {
56	await mkdir(resolvedDataDir, { recursive: true });	96	await mkdir(resolvedDataDir, { recursive: true });
57	}	97	}
		98	await cleanupStalePGliteLock(resolvedDataDir);
58	client = new PGlite(resolvedDataDir);	99	client = new PGlite(resolvedDataDir);
59	}	100	}
60		101

packages/control-plane/src/runtime/executor-tools.ts+14−5

   type WorkspaceId,
 } from "#schema";
 import * as Effect from "effect/Effect";
+import * as Cause from "effect/Cause";
+import * as Exit from "effect/Exit";
 import * as Schema from "effect/Schema";
+/** Run an Effect as a Promise, preserving the original error (not FiberFailure). */
+const runEffect = async <A>(effect: Effect.Effect<A, unknown, never>): Promise<A> => {
+  const exit = await Effect.runPromiseExit(effect);
+  if (Exit.isSuccess(exit)) return exit.value;
+  throw Cause.squash(exit.cause);
+};
 import {
   type ExecutorAddSourceInput,
   type ExecutorHttpSourceAuthInput,
               executionId,
               interactionId,
             };
-        const result = await Effect.runPromise(
+        const result = await runEffect(
           input.sourceAuthService.addExecutorSource(
             preparedArgs,
             context?.onElicitation
             ExecutorAddSourceInput,
             { kind: "openapi" | "graphql" }
           >;
-          const selectedAuth = await Effect.runPromise(
+          const selectedAuth = await runEffect(
             promptForSourceCredentialSelection({
               args: {
                 ...preparedHttpArgs,
             }),
           );
-          const completed = await Effect.runPromise(
+          const completed = await runEffect(
             input.sourceAuthService.addExecutorSource(
               {
                 ...preparedHttpArgs,
           throw new Error("executor.sources.add requires an elicitation-capable host");
         }
-        const response: ElicitationResponse = await Effect.runPromise(
+        const response: ElicitationResponse = await runEffect(
           context.onElicitation({
             interactionId,
             path: context.path ?? asToolPath("executor.sources.add"),
           throw new Error(`Source add was not completed for ${result.source.id}`);
         }
-        return await Effect.runPromise(
+        return await runEffect(
           input.sourceAuthService.getSourceById({
             workspaceId: input.workspaceId,
             sourceId: result.source.id,

packages/control-plane/src/runtime/index.ts+1−1

@@ -192,6 +192,6 @@ export const createSqlControlPlaneRuntime = ( · 191 unmodified lines
192	persistence,	192	persistence,
193	localInstallation,	193	localInstallation,
194	runtimeLayer: concreteRuntimeLayer,	194	runtimeLayer: concreteRuntimeLayer,
195	close: () => Effect.runPromise(Scope.close(scope, Exit.void)),	195	close: () => Effect.runPromise(Scope.close(scope, Exit.void)).catch(() => {}),
196	};	196	};
197	});	197	});

packages/executor-mcp/src/index.ts+83−23

   SqlControlPlaneRuntime,
 } from "@executor-v3/control-plane";
 import {
+  EXECUTOR_SOURCES_ADD_HELP_LINES,
+  ExecutionIdSchema,
+  RuntimeExecutionResolverService,
   createExecution,
   getExecution,
   resumeExecution,
 } from "@executor-v3/control-plane";
 import * as Effect from "effect/Effect";
+import * as Cause from "effect/Cause";
+import * as Exit from "effect/Exit";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod/v4";
   }
 };
-const runControlPlane = <A, E, R>(
+const runControlPlane = async <A, E, R>(
   runtime: SqlControlPlaneRuntime,
   effect: Effect.Effect<A, E, R>,
-): Promise<A> =>
+): Promise<A> => {
-  Effect.runPromise(
+  const exit = await Effect.runPromiseExit(
     effect.pipe(Effect.provide(runtime.runtimeLayer)) as Effect.Effect<A, E, never>,
   );
+  if (Exit.isSuccess(exit)) {
+    return exit.value;
+  }
+  const error = Cause.squash(exit.cause);
+  if (error instanceof Error) {
+    // Preserve the original error with its stack trace and message rather
+    // than wrapping it in an opaque FiberFailure.
+    throw error;
+  }
+  throw error;
+};
 const sleep = (ms: number) =>
   new Promise<void>((resolve) => {
     setTimeout(resolve, ms);
   return Boolean(capabilities?.elicitation?.form) && Boolean(capabilities?.elicitation?.url);
 };
+type CatalogLike = {
+  listNamespaces: (input: { limit: number }) => Effect.Effect<
+    ReadonlyArray<{ namespace: string; displayName?: string }>,
+    unknown
+  >;
+};
+const buildExecuteWorkflowText = (namespaces: readonly string[] = []): string =>
+  [
+    "Execute TypeScript in sandbox; call tools via discovery workflow.",
+    ...(namespaces.length > 0
+      ? [
+          "Available namespaces:",
+          ...namespaces.map((namespace) => `- ${namespace}`),
+        ]
+      : []),
+    "Workflow:",
+    '1) const matches = await tools.discover({ query: "<intent>", limit: 12 });',
+    "2) const details = await tools.describe.tool({ path, includeSchemas: true });",
+    "3) Call selected tools.<path>(input).",
+    '4) To connect a source, call tools.executor.sources.add(...) for MCP, OpenAPI, or GraphQL APIs.',
+    ...EXECUTOR_SOURCES_ADD_HELP_LINES,
+    "5) If execution pauses for interaction, resume it with the returned resumePayload or the available resume flow.",
+    "Do not use fetch; use tools.* only.",
+  ].join("\n");
+const defaultExecuteDescription = buildExecuteWorkflowText();
+const loadExecuteDescription = (runtime: SqlControlPlaneRuntime): Promise<string> =>
+  runControlPlane(
+    runtime,
+    Effect.gen(function* () {
+      const resolveExecutionEnvironment = yield* RuntimeExecutionResolverService;
+      const environment = yield* resolveExecutionEnvironment({
+        workspaceId: runtime.localInstallation.workspaceId,
+        accountId: runtime.localInstallation.accountId,
+        executionId: ExecutionIdSchema.make("exec_mcp_help"),
+      });
+      const catalog = environment.catalog as CatalogLike | undefined;
+      if (!catalog) {
+        return defaultExecuteDescription;
+      }
+      const namespaces = yield* catalog.listNamespaces({ limit: 200 }).pipe(
+        Effect.map((items) =>
+          items.length > 0
+            ? items.map((item) => item.displayName ?? item.namespace)
+            : ["none discovered yet"],
+        ),
+        Effect.catchAll(() => Effect.succeed(["none discovered yet"])),
+      );
+      return buildExecuteWorkflowText(namespaces);
+    }).pipe(Effect.catchAll(() => Effect.succeed(defaultExecuteDescription))),
+  );
 const summarizeExecution = (execution: ExecutionEnvelope["execution"]): string => {
   switch (execution.status) {
     case "completed":
   return current;
 };
-const buildInstallInstructions = (baseUrl: string): string => {
+const createExecutorMcpServer = async (config: {
-  const mcpUrl = new URL("/mcp", baseUrl).toString();
-  return [
-    "Run once to install for supported MCP clients (via add-mcp):",
-    `npx add-mcp \"${mcpUrl}\" --transport http --name \"executor\"`,
-  ].join("\n");
-};
-const createExecutorMcpServer = (config: {
   runtime: SqlControlPlaneRuntime;
-  baseUrl: string;
+}): Promise<McpServer> => {
-}): McpServer => {
+  const executeDescription = await loadExecuteDescription(config.runtime);
   const server = new McpServer(
     { name: "executor", version: "1.0.0" },
     {
       capabilities: {
         tools: {},
       },
-      instructions: buildInstallInstructions(config.baseUrl),
     },
   );
   const executeTool = server.registerTool(
     "execute",
     {
-      description: [
+      description: executeDescription,
-        "Execute TypeScript against the local executor runtime.",
-        "Use the in-sandbox tool catalog via tools.* rather than direct fetch calls.",
-      ].join("\n"),
       inputSchema: executeInputSchema,
     },
     async ({ code }: { code: string }) => {
     },
   );
   const syncToolAvailability = () => {
     if (supportsManagedElicitation(server)) {
       executeTool.enable();
       };
       try {
-        createdServer = createExecutorMcpServer({
+        createdServer = await createExecutorMcpServer({
           runtime,
-          baseUrl: new URL(request.url).origin,
         });
         await createdServer.connect(transport);
         const response = await transport.handleRequest(request);

packages/react/src/index.ts+26−10

@@ -28,6 +28,8 @@ import type { · 27 unmodified lines
28	} from "@executor-v3/control-plane";	28	} from "@executor-v3/control-plane";
29	import * as Cause from "effect/Cause";	29	import * as Cause from "effect/Cause";
30	import * as Effect from "effect/Effect";	30	import * as Effect from "effect/Effect";
		31	import * as Exit from "effect/Exit";
		32	import * as Runtime from "effect/Runtime";
31	import * as React from "react";	33	import * as React from "react";
32		34
33	const DEFAULT_EXECUTOR_API_BASE_URL = "http://127.0.0.1:8788";	35	const DEFAULT_EXECUTOR_API_BASE_URL = "http://127.0.0.1:8788";
@@ -177,6 +179,15 @@ const shouldLogExecutorDevErrors = (): boolean => { · 143 unmodified lines
177	};	179	};
178		180
179	const describeExecutorDevError = (cause: unknown): Record<string, unknown> => {	181	const describeExecutorDevError = (cause: unknown): Record<string, unknown> => {
		182	if (Runtime.isFiberFailure(cause)) {
		183	const inner = cause[Runtime.FiberFailureCauseId];
		184	return {
		185	name: cause.name,
		186	message: cause.message,
		187	cause: Cause.pretty(inner),
		188	};
		189	}
		190
180	if (cause instanceof Error) {	191	if (cause instanceof Error) {
181	return {	192	return {
182	name: cause.name,	193	name: cause.name,
@@ -198,26 +209,31 @@ const logExecutorDevError = (label: string, details: Record<string, unknown>): v · 15 unmodified lines
198	console.error(`[executor react] ${label}`, details);	209	console.error(`[executor react] ${label}`, details);
199	};	210	};
200		211
201	const runControlPlane = <A>(input: {	212	const runControlPlane = async <A>(input: {
202	accountId?: string;	213	accountId?: string;
203	execute: (client: ControlPlaneClient) => Effect.Effect<A, unknown, never>;	214	execute: (client: ControlPlaneClient) => Effect.Effect<A, unknown, never>;
204	}): Promise<A> => {	215	}): Promise<A> => {
205	const accountId = input.accountId;	216	const accountId = input.accountId;
206		217
207	return Effect.runPromise(	218	const exit = await Effect.runPromiseExit(
208	createControlPlaneClient({	219	createControlPlaneClient({
209	baseUrl: apiBaseUrl,	220	baseUrl: apiBaseUrl,
210	...(accountId !== undefined ? { accountId } : {}),	221	...(accountId !== undefined ? { accountId } : {}),
211	}).pipe(Effect.flatMap(input.execute)),	222	}).pipe(Effect.flatMap(input.execute)),
212	).catch((cause) => {	223	);
213	logExecutorDevError("control-plane request failed", {	224
214	baseUrl: apiBaseUrl,	225	if (Exit.isSuccess(exit)) {
215	accountId,	226	return exit.value;
216	error: describeExecutorDevError(cause),	227	}
217	cause,	228
218	});	229	const error = Cause.squash(exit.cause);
219	throw cause;	230	logExecutorDevError("control-plane request failed", {
		231	baseUrl: apiBaseUrl,
		232	accountId,
		233	error: describeExecutorDevError(error),
		234	cause: Cause.pretty(exit.cause),
220	});	235	});
		236	throw error;
221	};	237	};
222		238
223	const controlPlaneRequest = <A>(input: {	239	const controlPlaneRequest = <A>(input: {

packages/server/src/index.ts+9−4

 };
 const disposeRuntime = (runtime: SqlControlPlaneRuntime) =>
-  Effect.promise(() => runtime.close()).pipe(Effect.orDie);
+  Effect.tryPromise({
+    try: () => runtime.close(),
+    catch: (cause) =>
+      cause instanceof Error ? cause : new Error(String(cause ?? "runtime close failed")),
+  }).pipe(Effect.orDie);
 const createControlPlaneWebHandler = (runtime: SqlControlPlaneRuntime) =>
   Effect.acquireRelease(
         ),
       ),
     ),
-    (handler) => Effect.promise(() => handler.dispose()).pipe(Effect.orDie),
+    (handler) => Effect.tryPromise({ try: () => handler.dispose(), catch: (cause) => cause instanceof Error ? cause : new Error(String(cause ?? "web handler dispose failed")) }).pipe(Effect.orDie),
   );
 const safeFilePath = (assetsDir: string, pathname: string): string | null => {
     const apiHandler = yield* createControlPlaneWebHandler(runtime);
     const mcpHandler = yield* Effect.acquireRelease(
       Effect.sync(() => createExecutorMcpRequestHandler(runtime)),
-      (handler) => Effect.promise(() => handler.close()).pipe(Effect.orDie),
+      (handler) => Effect.tryPromise({ try: () => handler.close(), catch: (cause) => cause instanceof Error ? cause : new Error(String(cause ?? "mcp handler close failed")) }).pipe(Effect.orDie),
     );
     return {
         }),
         () => Effect.tryPromise({
           try: () => rm(pidFile, { force: true }),
-          catch: () => undefined,
+          catch: (cause) =>
+            cause instanceof Error ? cause : new Error(String(cause ?? "pid file cleanup failed")),
         }).pipe(Effect.orDie),
       );