lael-labs/executor

v2/PLAN.md+10−11

 How clients talk to executor.
 - MCP server/gateway
-- OpenAPI/RPC control API
+- OpenAPI control API
 - AI SDK tool bridge
 Transport does not own core execution semantics.
 ---
-## 8) MCP, RPC, and AI SDK strategy
+## 8) MCP, OpenAPI, and AI SDK strategy
 ### MCP
 ### Control API
-Control is exposed through Executor OpenAPI/RPC contracts.
+Control is exposed through Executor OpenAPI contracts.
 - Host/app control calls should use control API directly.
 - Model control calls can use `tools.executor.*` inside `execute` code.
     schema/
     state-contracts/
     state-local-file/
-    state-convex/
     domain/
     approvals/
     source-manager/
+    control-plane/
     engine/
     mcp-gateway/
     oauth/
     secrets/
     sync/
-    rpc/
     sdk/
     ai-sdk-adapter/
 ```
 confect -> schema -> state-contracts
 state-contracts -> state-local-file
-state-contracts -> state-convex
 schema + state-contracts + oauth + secrets -> domain
 domain -> approvals/source-manager/engine
+source-manager + schema -> control-plane
 approvals/source-manager/engine -> mcp-gateway
-domain/features -> rpc -> sdk -> ai-sdk-adapter
+domain/features -> sdk -> ai-sdk-adapter
-apps/pm      -> mcp-gateway + domain + state-local-file + rpc
+apps/pm      -> mcp-gateway + domain + state-local-file + control-plane
-apps/convex  -> mcp-gateway + domain + state-convex + rpc
+apps/convex  -> mcp-gateway + domain + control-plane
 apps/cli/web -> sdk (and/or ai-sdk bridge)
 ```
 Rules:
 ### Phase 5: transport polish
 - MCP surface stabilization
-- OpenAPI/RPC control surface stabilization
+- OpenAPI control surface stabilization
 - AI SDK bridge (`toAiSdkTools`) and docs/examples
 ---
 - shared tool invocation service wired with persisted approval lifecycle in v2 path
 - cloudflare-worker-loader runtime adapter implementation in v2 runtime path
 - parity conformance tests for runtime/provider/pending-approval/cancel flows
-- full rpc/sdk/ai-sdk adapter wiring and usage examples
+- full openapi/sdk/ai-sdk adapter wiring and usage examples
 ---

v2/apps/convex/README.md+6−4

@@ -3,7 +3,9 @@ · 2 unmodified lines
3	Convex remote server app scaffold for Executor v2.	3	Convex remote server app scaffold for Executor v2.
4		4
5	Current scaffold includes:	5	Current scaffold includes:
6	Convex schema wiring at `convex/schema.ts`, sourced from `@executor-v2/persistence-convex`	6	Convex schema wiring lives directly in `convex/schema.ts`
7	MCP HTTP endpoint at `convex/http.ts` and `convex/mcp.ts`, wired through a run client	7	MCP HTTP endpoint at `GET/POST/DELETE /v1/mcp` via `convex/http.ts` and `convex/mcp.ts`
8	runtime callback endpoints at `POST /runtime/tool-call` and `POST /v1/runtime/tool-call`	8	runtime callback endpoint at `POST /v1/runtime/tool-call`
9	action-level callback handler scaffold in `convex/runtimeCallbacks.ts`	9	control-plane source endpoints at `GET/POST /v1/workspaces/:workspaceId/sources`
		10	control-plane source removal endpoint at `DELETE /v1/workspaces/:workspaceId/sources/:sourceId`
		11	generated OpenAPI spec endpoint at `GET /v1/openapi.json`

v2/apps/convex/convex/_generated/api.d.ts+10−2

  * @module
  */
+import type * as controlPlane from "../controlPlane.js";
+import type * as control_plane_errors from "../control_plane/errors.js";
+import type * as control_plane_http from "../control_plane/http.js";
+import type * as control_plane_service from "../control_plane/service.js";
+import type * as control_plane_sources from "../control_plane/sources.js";
 import type * as executor from "../executor.js";
 import type * as http from "../http.js";
 import type * as mcp from "../mcp.js";
-import type * as rpc_exit from "../rpc_exit.js";
 import type * as run_executor from "../run_executor.js";
 import type * as runtimeCallbacks from "../runtimeCallbacks.js";
 import type * as runtime_adapter from "../runtime_adapter.js";
 } from "convex/server";
 declare const fullApi: ApiFromModules<{
+  controlPlane: typeof controlPlane;
+  "control_plane/errors": typeof control_plane_errors;
+  "control_plane/http": typeof control_plane_http;
+  "control_plane/service": typeof control_plane_service;
+  "control_plane/sources": typeof control_plane_sources;
   executor: typeof executor;
   http: typeof http;
   mcp: typeof mcp;
-  rpc_exit: typeof rpc_exit;
   run_executor: typeof run_executor;
   runtimeCallbacks: typeof runtimeCallbacks;
   runtime_adapter: typeof runtime_adapter;

v2/apps/convex/convex/controlPlane.ts+12−0

@@ -0,0 +1,12 @@
	1	import {
	2	listSources as listSourcesImpl,
	3	removeSource as removeSourceImpl,
	4	upsertSource as upsertSourceImpl,
	5	} from "./control_plane/sources";
	6	import { controlPlaneHttpHandler as controlPlaneHttpHandlerImpl } from "./control_plane/http";
	7
	8	export const listSources = listSourcesImpl;
	9	export const upsertSource = upsertSourceImpl;
	10	export const removeSource = removeSourceImpl;
	11
	12	export const controlPlaneHttpHandler = controlPlaneHttpHandlerImpl;

v2/apps/convex/convex/control_plane/errors.ts+75−0

@@ -0,0 +1,75 @@
	1	import { SourceStoreError } from "@executor-v2/persistence-ports";
	2
	3	type ControlPlaneErrorCode =
	4	\| "bad_request"
	5	\| "not_found"
	6	\| "method_not_allowed"
	7	\| "internal";
	8
	9	type ControlPlaneErrorResponse = {
	10	ok: false;
	11	error: {
	12	code: ControlPlaneErrorCode;
	13	message: string;
	14	details: string \| null;
	15	};
	16	};
	17
	18	const renderCause = (cause: unknown): string => String(cause);
	19
	20	export const toSourceStoreError = (
	21	operation: string,
	22	cause: unknown,
	23	): SourceStoreError =>
	24	new SourceStoreError({
	25	operation,
	26	filePath: "convex://control-plane",
	27	message: "Convex control plane call failed",
	28	reason: null,
	29	details: renderCause(cause),
	30	});
	31
	32	const toErrorCode = (status: number): ControlPlaneErrorCode => {
	33	switch (status) {
	34	case 400:
	35	return "bad_request";
	36	case 404:
	37	return "not_found";
	38	case 405:
	39	return "method_not_allowed";
	40	default:
	41	return "internal";
	42	}
	43	};
	44
	45	export const controlPlaneErrorResponse = (
	46	status: number,
	47	message: string,
	48	details: string \| null,
	49	): Response =>
	50	Response.json(
	51	{
	52	ok: false,
	53	error: {
	54	code: toErrorCode(status),
	55	message,
	56	details,
	57	},
	58	} satisfies ControlPlaneErrorResponse,
	59	{ status },
	60	);
	61
	62	const isJsonResponse = (response: Response): boolean =>
	63	response.headers.get("content-type")?.toLowerCase().includes("application/json") ?? false;
	64
	65	export const normalizeControlPlaneErrorResponse = (response: Response): Response => {
	66	if (response.ok \|\| isJsonResponse(response)) {
	67	return response;
	68	}
	69
	70	return controlPlaneErrorResponse(
	71	response.status,
	72	"Control plane request failed",
	73	response.statusText \|\| null,
	74	);
	75	};

v2/apps/convex/convex/control_plane/http.ts+65−0

@@ -0,0 +1,65 @@
	1	import {
	2	ControlPlaneService,
	3	controlPlaneOpenApiSpec,
	4	makeControlPlaneWebHandler,
	5	} from "@executor-v2/control-plane";
	6	import * as Effect from "effect/Effect";
	7	import * as Layer from "effect/Layer";
	8
	9	import { httpAction, type ActionCtx } from "../_generated/server";
	10	import {
	11	controlPlaneErrorResponse,
	12	normalizeControlPlaneErrorResponse,
	13	toSourceStoreError,
	14	} from "./errors";
	15	import { makeConvexControlPlaneService } from "./service";
	16
	17	const isOpenApiRequest = (request: Request): boolean =>
	18	new URL(request.url).pathname === "/v1/openapi.json";
	19
	20	const handleControlPlaneRequest = (
	21	ctx: ActionCtx,
	22	request: Request,
	23	): Effect.Effect<Response, never> =>
	24	Effect.scoped(
	25	Effect.gen(function* () {
	26	if (isOpenApiRequest(request)) {
	27	return Response.json(controlPlaneOpenApiSpec, { status: 200 });
	28	}
	29
	30	const webHandler = makeControlPlaneWebHandler(
	31	Layer.succeed(ControlPlaneService, makeConvexControlPlaneService(ctx)),
	32	);
	33
	34	yield* Effect.addFinalizer(() =>
	35	Effect.tryPromise({
	36	try: () => webHandler.dispose(),
	37	catch: (cause) => toSourceStoreError("controlPlane.dispose", cause),
	38	}).pipe(
	39	Effect.asVoid,
	40	Effect.catchAll(() => Effect.void),
	41	),
	42	);
	43
	44	const response = yield* Effect.tryPromise({
	45	try: () => webHandler.handler(request),
	46	catch: (cause) => toSourceStoreError("controlPlane.http", cause),
	47	});
	48
	49	return normalizeControlPlaneErrorResponse(response);
	50	}),
	51	).pipe(
	52	Effect.catchAll((error) =>
	53	Effect.succeed(
	54	controlPlaneErrorResponse(
	55	500,
	56	"Control plane request failed",
	57	error.details,
	58	),
	59	),
	60	),
	61	);
	62
	63	export const controlPlaneHttpHandler = httpAction((ctx, request) =>
	64	Effect.runPromise(handleControlPlaneRequest(ctx, request)),
	65	);

v2/apps/convex/convex/control_plane/service.ts+41−0

@@ -0,0 +1,41 @@
	1	import {
	2	ControlPlaneService,
	3	type ControlPlaneServiceShape,
	4	} from "@executor-v2/control-plane";
	5	import * as Effect from "effect/Effect";
	6
	7	import { api } from "../_generated/api";
	8	import type { ActionCtx } from "../_generated/server";
	9	import { toSourceStoreError } from "./errors";
	10
	11	export const makeConvexControlPlaneService = (
	12	ctx: ActionCtx,
	13	): ControlPlaneServiceShape =>
	14	ControlPlaneService.of({
	15	listSources: (workspaceId) =>
	16	Effect.tryPromise({
	17	try: () =>
	18	ctx.runQuery(api.controlPlane.listSources, {
	19	workspaceId,
	20	}),
	21	catch: (cause) => toSourceStoreError("controlPlane.listSources", cause),
	22	}),
	23	upsertSource: (input) =>
	24	Effect.tryPromise({
	25	try: () =>
	26	ctx.runMutation(api.controlPlane.upsertSource, {
	27	workspaceId: input.workspaceId,
	28	payload: input.payload,
	29	}),
	30	catch: (cause) => toSourceStoreError("controlPlane.upsertSource", cause),
	31	}),
	32	removeSource: (input) =>
	33	Effect.tryPromise({
	34	try: () =>
	35	ctx.runMutation(api.controlPlane.removeSource, {
	36	workspaceId: input.workspaceId,
	37	sourceId: input.sourceId,
	38	}),
	39	catch: (cause) => toSourceStoreError("controlPlane.removeSource", cause),
	40	}),
	41	});

v2/apps/convex/convex/control_plane/sources.ts+140−0

@@ -0,0 +1,140 @@
	1	import { type UpsertSourcePayload } from "@executor-v2/control-plane";
	2	import { SourceSchema, type Source } from "@executor-v2/schema";
	3	import { v } from "convex/values";
	4	import * as Schema from "effect/Schema";
	5
	6	import { mutation, query } from "../_generated/server";
	7
	8	const decodeSource = Schema.decodeUnknownSync(SourceSchema);
	9
	10	const sourceStoreKey = (source: Source): string => `${source.workspaceId}:${source.id}`;
	11
	12	const sortSources = (sources: ReadonlyArray<Source>): Array<Source> =>
	13	[...sources].sort((left, right) => {
	14	const leftName = left.name.toLowerCase();
	15	const rightName = right.name.toLowerCase();
	16
	17	if (leftName === rightName) {
	18	return sourceStoreKey(left).localeCompare(sourceStoreKey(right));
	19	}
	20
	21	return leftName.localeCompare(rightName);
	22	});
	23
	24	const toSource = (document: Record<string, unknown>): Source => {
	25	const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...source } = document;
	26	return decodeSource(source);
	27	};
	28
	29	const sourceKindValidator = v.union(
	30	v.literal("mcp"),
	31	v.literal("openapi"),
	32	v.literal("graphql"),
	33	v.literal("internal"),
	34	);
	35
	36	const sourceStatusValidator = v.union(
	37	v.literal("draft"),
	38	v.literal("probing"),
	39	v.literal("auth_required"),
	40	v.literal("connected"),
	41	v.literal("error"),
	42	);
	43
	44	export const listSources = query({
	45	args: {
	46	workspaceId: v.string(),
	47	},
	48	handler: async (ctx, args): Promise<Array<Source>> => {
	49	const documents = await ctx.db
	50	.query("sources")
	51	.withIndex("by_workspaceId", (q) => q.eq("workspaceId", args.workspaceId))
	52	.collect();
	53
	54	return sortSources(
	55	documents.map((document) =>
	56	toSource(document as unknown as Record<string, unknown>),
	57	),
	58	);
	59	},
	60	});
	61
	62	export const upsertSource = mutation({
	63	args: {
	64	workspaceId: v.string(),
	65	payload: v.object({
	66	id: v.optional(v.string()),
	67	name: v.string(),
	68	kind: sourceKindValidator,
	69	endpoint: v.string(),
	70	status: v.optional(sourceStatusValidator),
	71	enabled: v.optional(v.boolean()),
	72	configJson: v.optional(v.string()),
	73	sourceHash: v.optional(v.union(v.string(), v.null())),
	74	lastError: v.optional(v.union(v.string(), v.null())),
	75	}),
	76	},
	77	handler: async (ctx, args): Promise<Source> => {
	78	const now = Date.now();
	79	const sourceId = args.payload.id ?? `src_${crypto.randomUUID()}`;
	80
	81	const existing = await ctx.db
	82	.query("sources")
	83	.withIndex("by_domainId", (q) => q.eq("id", sourceId))
	84	.unique();
	85
	86	const existingInWorkspace =
	87	existing && existing.workspaceId === args.workspaceId ? existing : null;
	88
	89	const payload = args.payload as UpsertSourcePayload;
	90
	91	const source = decodeSource({
	92	id: sourceId,
	93	workspaceId: args.workspaceId,
	94	name: payload.name,
	95	kind: payload.kind,
	96	endpoint: payload.endpoint,
	97	status: payload.status ?? "draft",
	98	enabled: payload.enabled ?? true,
	99	configJson: payload.configJson ?? "{}",
	100	sourceHash: payload.sourceHash ?? null,
	101	lastError: payload.lastError ?? null,
	102	createdAt: existingInWorkspace?.createdAt ?? now,
	103	updatedAt: now,
	104	});
	105
	106	if (existingInWorkspace) {
	107	await ctx.db.patch(existingInWorkspace._id, source);
	108	} else {
	109	await ctx.db.insert("sources", source);
	110	}
	111
	112	return source;
	113	},
	114	});
	115
	116	export const removeSource = mutation({
	117	args: {
	118	workspaceId: v.string(),
	119	sourceId: v.string(),
	120	},
	121	handler: async (
	122	ctx,
	123	args,
	124	): Promise<{
	125	removed: boolean;
	126	}> => {
	127	const existing = await ctx.db
	128	.query("sources")
	129	.withIndex("by_domainId", (q) => q.eq("id", args.sourceId))
	130	.unique();
	131
	132	if (!existing \|\| existing.workspaceId !== args.workspaceId) {
	133	return { removed: false };
	134	}
	135
	136	await ctx.db.delete(existing._id);
	137
	138	return { removed: true };
	139	},
	140	});

v2/apps/convex/convex/executor.test.ts+61−35

@@ -3,7 +3,7 @@ import { convexTest } from "convex-test"; · 2 unmodified lines
3	import * as Effect from "effect/Effect";	3	import * as Effect from "effect/Effect";
4		4
5	import { api } from "./_generated/api";	5	import { api } from "./_generated/api";
6	import { unwrapRpcSuccess } from "./rpc_exit";	6	import { executeRunImpl } from "./executor";
7	import schema from "./schema";	7	import schema from "./schema";
8		8
9	const setup = () =>	9	const setup = () =>
@@ -12,54 +12,80 @@ const setup = () => · 2 unmodified lines
12	"./mcp.ts": () => import("./mcp"),	12	"./mcp.ts": () => import("./mcp"),
13	"./executor.ts": () => import("./executor"),	13	"./executor.ts": () => import("./executor"),
14	"./runtimeCallbacks.ts": () => import("./runtimeCallbacks"),	14	"./runtimeCallbacks.ts": () => import("./runtimeCallbacks"),
		15	"./controlPlane.ts": () => import("./controlPlane"),
15	"./_generated/api.js": () => import("./_generated/api.js"),	16	"./_generated/api.js": () => import("./_generated/api.js"),
16	});	17	});
17		18
18	describe("Convex executor actions", () => {	19	describe("Convex executor and control-plane", () => {
19	it.effect("executes code via executeRun action", () =>	20	it.effect("executes code via executeRunImpl", () =>
20	Effect.gen(function* () {	21	Effect.gen(function* () {
21	const t = setup();	22	const result = yield* executeRunImpl({
22		23	code: "return 6 * 7;",
23	const result = unwrapRpcSuccess<{	24	});
24	status: string;
25	result?: unknown;
26	}>(
27	yield* Effect.tryPromise(() =>
28	t.action(api.executor.executeRun, {
29	code: "return 6 * 7;",
30	}),
31	),
32	"executor.executeRun",
33	);
34		25
35	expect(result.status).toBe("completed");	26	expect(result.status).toBe("completed");
36	expect(result.result).toBe(42);	27	expect(result.result).toBe(42);
37	}),	28	}),
38	);	29	);
39		30
40	it.effect("returns failed callback result from runtime callback action", () =>	31	it.effect("upserts, lists, and removes sources", () =>
41	Effect.gen(function* () {	32	Effect.gen(function* () {
42	const t = setup();	33	const t = setup();
43		34
44	const result = unwrapRpcSuccess<{	35	const added = (yield* Effect.tryPromise(() =>
45	ok: boolean;	36	t.mutation(api.controlPlane.upsertSource, {
46	kind?: string;	37	workspaceId: "ws_1",
47	error?: string;	38	payload: {
48	}>(	39	id: "src_1",
49	yield* Effect.tryPromise(() =>	40	name: "Weather",
50	t.action(api.runtimeCallbacks.handleToolCall, {	41	kind: "openapi",
51	runId: "run_1",	42	endpoint: "https://example.com/openapi.json",
52	callId: "call_1",	43	enabled: true,
53	toolPath: "tools.example.lookup",	44	configJson: "{}",
54	input: { query: "ping" },	45	status: "draft",
55	}),	46	sourceHash: null,
56	),	47	lastError: null,
57	"runtimeCallbacks.handleToolCall",	48	},
58	);	49	}),
		50	)) as {
		51	id: string;
		52	workspaceId: string;
		53	name: string;
		54	};
		55
		56	expect(added.id).toBe("src_1");
		57	expect(added.workspaceId).toBe("ws_1");
		58	expect(added.name).toBe("Weather");
		59
		60	const listed = (yield* Effect.tryPromise(() =>
		61	t.query(api.controlPlane.listSources, {
		62	workspaceId: "ws_1",
		63	}),
		64	)) as Array<{
		65	id: string;
		66	}>;
		67
		68	expect(listed).toHaveLength(1);
		69	expect(listed[0]?.id).toBe("src_1");
		70
		71	const removed = (yield* Effect.tryPromise(() =>
		72	t.mutation(api.controlPlane.removeSource, {
		73	workspaceId: "ws_1",
		74	sourceId: "src_1",
		75	}),
		76	)) as {
		77	removed: boolean;
		78	};
		79
		80	expect(removed.removed).toBe(true);
		81
		82	const listedAfterRemove = (yield* Effect.tryPromise(() =>
		83	t.query(api.controlPlane.listSources, {
		84	workspaceId: "ws_1",
		85	}),
		86	)) as Array<unknown>;
59		87
60	expect(result.ok).toBe(false);	88	expect(listedAfterRemove).toHaveLength(0);
61	expect(result.kind).toBe("failed");
62	expect(result.error).toContain("tools.example.lookup");
63	}),	89	}),
64	);	90	);
65	});	91	});

v2/apps/convex/convex/executor.ts+2−44

@@ -1,9 +1,6 @@
1	import { createRpcFactory, makeRpcModule } from "@executor-v2/confect/rpc";	1	import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";
2	import { executorConfectSchema } from "@executor-v2/persistence-convex";
3	import type { ExecuteRunInput } from "@executor-v2/sdk";
4	import * as Effect from "effect/Effect";	2	import * as Effect from "effect/Effect";
5	import * as Layer from "effect/Layer";	3	import * as Layer from "effect/Layer";
6	import * as Schema from "effect/Schema";
7		4
8	import {	5	import {
9	ConvexRunExecutor,	6	ConvexRunExecutor,
@@ -11,24 +8,6 @@ import { · 1 unmodified line
11	ConvexToolProviderRegistryLive,	8	ConvexToolProviderRegistryLive,
12	} from "./run_executor";	9	} from "./run_executor";
13		10
14	const executeRunResultSchema = Schema.Struct({
15	runId: Schema.String,
16	status: Schema.Union(
17	Schema.Literal("completed"),
18	Schema.Literal("failed"),
19	Schema.Literal("timed_out"),
20	Schema.Literal("denied"),
21	),
22	result: Schema.optional(Schema.Unknown),
23	error: Schema.optional(Schema.String),
24	exitCode: Schema.optional(Schema.Number),
25	durationMs: Schema.optional(Schema.Number),
26	});
27
28	const factory = createRpcFactory({
29	schema: executorConfectSchema,
30	});
31
32	const ConvexExecuteDependenciesLive = Layer.merge(	11	const ConvexExecuteDependenciesLive = Layer.merge(
33	ConvexRunExecutorLive,	12	ConvexRunExecutorLive,
34	ConvexToolProviderRegistryLive,	13	ConvexToolProviderRegistryLive,
@@ -36,29 +15,8 @@ const ConvexExecuteDependenciesLive = Layer.merge( · 1 unmodified line
36		15
37	export const executeRunImpl = (	16	export const executeRunImpl = (
38	input: ExecuteRunInput,	17	input: ExecuteRunInput,
39	): Effect.Effect<typeof executeRunResultSchema.Type> =>	18	): Effect.Effect<ExecuteRunResult> =>
40	Effect.gen(function* () {	19	Effect.gen(function* () {
41	const runExecutor = yield* ConvexRunExecutor;	20	const runExecutor = yield* ConvexRunExecutor;
42	return yield* runExecutor.executeRun(input);	21	return yield* runExecutor.executeRun(input);
43	}).pipe(Effect.provide(ConvexExecuteDependenciesLive));	22	}).pipe(Effect.provide(ConvexExecuteDependenciesLive));
44
45	const executeRunEndpoint = factory.action({
46	payload: {
47	code: Schema.String,
48	timeoutMs: Schema.optional(Schema.Number),
49	},
50	success: executeRunResultSchema,
51	});
52
53	executeRunEndpoint.implement((payload) =>
54	executeRunImpl({
55	code: payload.code,
56	timeoutMs: payload.timeoutMs,
57	}),
58	);
59
60	const executorRpc = makeRpcModule({
61	executeRun: executeRunEndpoint,
62	});
63
64	export const executeRun = executorRpc.handlers.executeRun;

v2/apps/convex/convex/http.ts+30−6

@@ -1,24 +1,48 @@
1	import { httpRouter } from "convex/server";	1	import { httpRouter } from "convex/server";
		2
		3	import { controlPlaneHttpHandler } from "./controlPlane";
2	import { mcpHandler } from "./mcp";	4	import { mcpHandler } from "./mcp";
3	import { handleToolCallHttp } from "./runtimeCallbacks";	5	import { handleToolCallHttp } from "./runtimeCallbacks";
4		6
5	const http = httpRouter();	7	const http = httpRouter();
6		8
7	http.route({ path: "/mcp", method: "POST", handler: mcpHandler });
8	http.route({ path: "/mcp", method: "GET", handler: mcpHandler });
9	http.route({ path: "/mcp", method: "DELETE", handler: mcpHandler });
10	http.route({ path: "/v1/mcp", method: "POST", handler: mcpHandler });	9	http.route({ path: "/v1/mcp", method: "POST", handler: mcpHandler });
11	http.route({ path: "/v1/mcp", method: "GET", handler: mcpHandler });	10	http.route({ path: "/v1/mcp", method: "GET", handler: mcpHandler });
12	http.route({ path: "/v1/mcp", method: "DELETE", handler: mcpHandler });	11	http.route({ path: "/v1/mcp", method: "DELETE", handler: mcpHandler });
13	http.route({	12	http.route({
14	path: "/runtime/tool-call",	13	path: "/v1/runtime/tool-call",
15	method: "POST",	14	method: "POST",
16	handler: handleToolCallHttp,	15	handler: handleToolCallHttp,
17	});	16	});
18	http.route({	17	http.route({
19	path: "/v1/runtime/tool-call",	18	pathPrefix: "/v1/",
		19	method: "GET",
		20	handler: controlPlaneHttpHandler,
		21	});
		22	http.route({
		23	pathPrefix: "/v1/",
20	method: "POST",	24	method: "POST",
21	handler: handleToolCallHttp,	25	handler: controlPlaneHttpHandler,
		26	});
		27	http.route({
		28	pathPrefix: "/v1/",
		29	method: "PUT",
		30	handler: controlPlaneHttpHandler,
		31	});
		32	http.route({
		33	pathPrefix: "/v1/",
		34	method: "PATCH",
		35	handler: controlPlaneHttpHandler,
		36	});
		37	http.route({
		38	pathPrefix: "/v1/",
		39	method: "DELETE",
		40	handler: controlPlaneHttpHandler,
		41	});
		42	http.route({
		43	pathPrefix: "/v1/",
		44	method: "OPTIONS",
		45	handler: controlPlaneHttpHandler,
22	});	46	});
23		47
24	export default http;	48	export default http;

v2/apps/convex/convex/mcp.ts+6−6

@@ -1,13 +1,13 @@
1	import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";	1	import { handleMcpHttpRequest } from "@executor-v2/mcp-gateway";
2	import { createExecutorRunClient } from "@executor-v2/sdk";	2	import { createExecutorRunClient } from "@executor-v2/sdk";
3	import { api } from "./_generated/api";	3	import * as Effect from "effect/Effect";
		4
4	import { httpAction } from "./_generated/server";	5	import { httpAction } from "./_generated/server";
5	import { unwrapRpcSuccess } from "./rpc_exit";	6	import { executeRunImpl } from "./executor";
6	export const mcpHandler = httpAction(async (ctx, request) => {	7
		8	export const mcpHandler = httpAction(async (_ctx, request) => {
7	const runClient = createExecutorRunClient((input) =>	9	const runClient = createExecutorRunClient((input) =>
8	ctx	10	Effect.runPromise(executeRunImpl(input)),
9	.runAction(api.executor.executeRun, input)
10	.then((result) => unwrapRpcSuccess(result, "executor.executeRun")),
11	);	11	);
12		12
13	return handleMcpHttpRequest(request, {	13	return handleMcpHttpRequest(request, {

v2/apps/convex/convex/rpc_exit.ts+0−50

@@ -1,50 +0,0 @@
1	type RpcExitSuccess<T> = {
2	_tag: "Success";
3	value: T;
4	};
5
6	type RpcExitFailure = {
7	_tag: "Failure";
8	cause: unknown;
9	};
10
11	const isRpcExitSuccess = <T>(value: unknown): value is RpcExitSuccess<T> =>
12	typeof value === "object" &&
13	value !== null &&
14	"_tag" in value &&
15	value._tag === "Success" &&
16	"value" in value;
17
18	const isRpcExitFailure = (value: unknown): value is RpcExitFailure =>
19	typeof value === "object" &&
20	value !== null &&
21	"_tag" in value &&
22	value._tag === "Failure";
23
24	const renderUnknown = (value: unknown): string => {
25	if (value instanceof Error) {
26	return value.message;
27	}
28
29	try {
30	return JSON.stringify(value);
31	} catch {
32	return String(value);
33	}
34	};
35
36	export const unwrapRpcSuccess = <T>(value: unknown, endpoint: string): T => {
37	if (isRpcExitSuccess<T>(value)) {
38	return value.value;
39	}
40
41	if (isRpcExitFailure(value)) {
42	throw new Error(
43	`RPC endpoint '${endpoint}' returned failure exit: ${renderUnknown(value.cause)}`,
44	);
45	}
46
47	throw new Error(
48	`RPC endpoint '${endpoint}' returned invalid exit payload: ${renderUnknown(value)}`,
49	);
50	};

v2/apps/convex/convex/run_executor.ts+27−32

@@ -1,14 +1,14 @@
1	import {	1	import {
		2	makeLocalInProcessRuntimeAdapter,
2	makeToolProviderRegistry,	3	makeToolProviderRegistry,
3	ToolProviderRegistryService,	4	ToolProviderRegistryService,
4	} from "@executor-v2/engine/tool-providers";	5	type RuntimeExecuteError,
		6	} from "@executor-v2/engine";
5	import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";	7	import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";
6	import * as Context from "effect/Context";	8	import * as Context from "effect/Context";
7	import * as Effect from "effect/Effect";	9	import * as Effect from "effect/Effect";
8	import * as Layer from "effect/Layer";	10	import * as Layer from "effect/Layer";
9		11
10	import { makeLocalInProcessRuntimeAdapter } from "./runtime_adapter";
11
12	export type ConvexRunExecutorService = {	12	export type ConvexRunExecutorService = {
13	executeRun: (	13	executeRun: (
14	input: ExecuteRunInput,	14	input: ExecuteRunInput,
@@ -21,21 +21,16 @@ export class ConvexRunExecutor extends Context.Tag( · 6 unmodified lines
21		21
22	const runtimeAdapter = makeLocalInProcessRuntimeAdapter();	22	const runtimeAdapter = makeLocalInProcessRuntimeAdapter();
23		23
24	const errorToText = (error: unknown): string => {	24	const formatRuntimeExecuteError = (error: RuntimeExecuteError): string => {
25	if (error instanceof Error) {	25	switch (error._tag) {
26	return error.message;	26	case "RuntimeAdapterError":
27	}	27	case "LocalCodeRunnerError":
28		28	case "DenoSubprocessRunnerError":
29	if (	29	case "ToolProviderError":
30	typeof error === "object" &&	30	return error.details ? `${error.message}: ${error.details}` : error.message;
31	error !== null &&	31	case "ToolProviderRegistryError":
32	"message" in error &&	32	return error.message;
33	typeof error.message === "string"
34	) {
35	return error.message;
36	}	33	}
37
38	return String(error);
39	};	34	};
40		35
41	const executeRun = Effect.fn(	36	const executeRun = Effect.fn(
@@ -59,21 +54,21 @@ const executeRun = Effect.fn( · 17 unmodified lines
59	tools: [],	54	tools: [],
60	})	55	})
61	.pipe(	56	.pipe(
62	Effect.map(	57	Effect.map(
63	(result): ExecuteRunResult => ({	58	(result): ExecuteRunResult => ({
64	runId,	59	runId,
65	status: "completed",	60	status: "completed",
66	result,	61	result,
67	}),	62	}),
68	),	63	),
69	Effect.catchAll((error) =>	64	Effect.catchAll((error) =>
70	Effect.succeed({	65	Effect.succeed({
71	runId,	66	runId,
72	status: "failed",	67	status: "failed",
73	error: errorToText(error),	68	error: formatRuntimeExecuteError(error),
74	} satisfies ExecuteRunResult),	69	} satisfies ExecuteRunResult),
75	),	70	),
76	);	71	);
77	});	72	});
78		73
79	export const ConvexRunExecutorLive = Layer.succeed(	74	export const ConvexRunExecutorLive = Layer.succeed(

v2/apps/convex/convex/runtimeCallbacks.ts+55−84

@@ -1,27 +1,13 @@
1	import { createRpcFactory, makeRpcModule } from "@executor-v2/confect/rpc";
2	import { executorConfectSchema } from "@executor-v2/persistence-convex";
3	import type {	1	import type {
4	RuntimeToolCallRequest,	2	RuntimeToolCallRequest,
5	RuntimeToolCallResult,	3	RuntimeToolCallResult,
6	} from "@executor-v2/sdk";	4	} from "@executor-v2/sdk";
		5	import * as Data from "effect/Data";
7	import * as Effect from "effect/Effect";	6	import * as Effect from "effect/Effect";
		7	import * as ParseResult from "effect/ParseResult";
8	import * as Schema from "effect/Schema";	8	import * as Schema from "effect/Schema";
9	import { api } from "./_generated/api";
10	import { httpAction } from "./_generated/server";
11	import { unwrapRpcSuccess } from "./rpc_exit";
12
13	const runtimeToolCallResultSchema = Schema.Struct({
14	ok: Schema.Boolean,
15	kind: Schema.optional(Schema.String),
16	error: Schema.optional(Schema.String),
17	value: Schema.optional(Schema.Unknown),
18	approvalId: Schema.optional(Schema.String),
19	retryAfterMs: Schema.optional(Schema.Number),
20	});
21		9
22	const factory = createRpcFactory({	10	import { httpAction } from "./_generated/server";
23	schema: executorConfectSchema,
24	});
25		11
26	export const handleToolCallImpl = (	12	export const handleToolCallImpl = (
27	input: RuntimeToolCallRequest,	13	input: RuntimeToolCallRequest,
@@ -32,35 +18,26 @@ export const handleToolCallImpl = ( · 4 unmodified lines
32	error: `Convex runtime callback received tool '${input.toolPath}', but callback invocation is not wired yet.`,	18	error: `Convex runtime callback received tool '${input.toolPath}', but callback invocation is not wired yet.`,
33	});	19	});
34		20
35	const handleToolCallEndpoint = factory.action({	21	class RuntimeToolCallBadRequestError extends Data.TaggedError(
36	payload: {	22	"RuntimeToolCallBadRequestError",
37	runId: Schema.String,	23	)<{
38	callId: Schema.String,	24	message: string;
39	toolPath: Schema.String,	25	details: string;
40	input: Schema.optional(	26	}> {}
41	Schema.Record({
42	key: Schema.String,
43	value: Schema.Unknown,
44	}),
45	),
46	},
47	success: runtimeToolCallResultSchema,
48	});
49
50	handleToolCallEndpoint.implement((payload) =>
51	handleToolCallImpl({
52	runId: payload.runId,
53	callId: payload.callId,
54	toolPath: payload.toolPath,
55	input: payload.input,
56	}),
57	);
58		27
59	const runtimeCallbacksRpc = makeRpcModule({	28	const RuntimeToolCallRequestSchema = Schema.Struct({
60	handleToolCall: handleToolCallEndpoint,	29	runId: Schema.String,
		30	callId: Schema.String,
		31	toolPath: Schema.String,
		32	input: Schema.optional(
		33	Schema.Record({
		34	key: Schema.String,
		35	value: Schema.Unknown,
		36	}),
		37	),
61	});	38	});
62		39
63	export const handleToolCall = runtimeCallbacksRpc.handlers.handleToolCall;	40	const decodeRuntimeToolCallRequest = Schema.decodeUnknown(RuntimeToolCallRequestSchema);
64		41
65	const badRequest = (message: string): Response =>	42	const badRequest = (message: string): Response =>
66	Response.json(	43	Response.json(
@@ -72,48 +49,42 @@ const badRequest = (message: string): Response => · 5 unmodified lines
72	{ status: 400 },	49	{ status: 400 },
73	);	50	);
74		51
75	export const handleToolCallHttp = httpAction(async (ctx, request) => {	52	const formatBadRequestMessage = (error: RuntimeToolCallBadRequestError): string =>
76	let body: unknown;	53	error.details.length > 0 ? `${error.message}: ${error.details}` : error.message;
77	try {
78	body = await request.json();
79	} catch (cause) {
80	return badRequest(
81	`Invalid runtime callback request body: ${
82	cause instanceof Error ? cause.message : String(cause)
83	}`,
84	);
85	}
86
87	if (typeof body !== "object" \|\| body === null) {
88	return badRequest("Runtime callback request body must be an object");
89	}
90		54
91	const payload = body as Partial<RuntimeToolCallRequest>;	55	const formatUnknownDetails = (cause: unknown): string => String(cause);
92		56
93	if (	57	const handleToolCallHttpEffect = (
94	typeof payload.runId !== "string" \|\|	58	request: Request,
95	typeof payload.callId !== "string" \|\|	59	): Effect.Effect<Response, never> =>
96	typeof payload.toolPath !== "string"	60	Effect.gen(function* () {
97	) {	61	const body = yield* Effect.tryPromise({
98	return badRequest("Runtime callback request body is missing required fields");	62	try: () => request.json(),
99	}	63	catch: (cause) =>
		64	new RuntimeToolCallBadRequestError({
		65	message: "Invalid runtime callback request body",
		66	details: formatUnknownDetails(cause),
		67	}),
		68	});
100		69
101	let result: RuntimeToolCallResult;	70	const input = yield* decodeRuntimeToolCallRequest(body).pipe(
102	try {	71	Effect.mapError(
103	result = unwrapRpcSuccess(	72	(cause) =>
104	await ctx.runAction(api.runtimeCallbacks.handleToolCall, {	73	new RuntimeToolCallBadRequestError({
105	runId: payload.runId,	74	message: "Runtime callback request body is invalid",
106	callId: payload.callId,	75	details: ParseResult.TreeFormatter.formatErrorSync(cause),
107	toolPath: payload.toolPath,	76	}),
108	input:	77	),
109	payload.input && typeof payload.input === "object"
110	? (payload.input as Record<string, unknown>)
111	: undefined,
112	}),
113	"runtimeCallbacks.handleToolCall",
114	);	78	);
115	} catch (cause) {	79
116	return badRequest(cause instanceof Error ? cause.message : String(cause));	80	const result = yield* handleToolCallImpl(input);
117	}	81	return Response.json(result, { status: 200 });
118	return Response.json(result, { status: 200 });	82	}).pipe(
119	});	83	Effect.catchTag("RuntimeToolCallBadRequestError", (error) =>
		84	Effect.succeed(badRequest(formatBadRequestMessage(error))),
		85	),
		86	);
		87
		88	export const handleToolCallHttp = httpAction((_ctx, request) =>
		89	Effect.runPromise(handleToolCallHttpEffect(request)),
		90	);

v2/apps/convex/convex/schema.ts+56−1

@@ -1,3 +1,58 @@
1	import { executorConfectSchema } from "@executor-v2/persistence-convex";	1	import { defineSchema, defineTable, type TablesFromSchemaDefinition } from "@executor-v2/confect";
		2	import {
		3	ApprovalSchema,
		4	CredentialRefSchema,
		5	EventEnvelopeSchema,
		6	OAuthTokenSchema,
		7	PolicySchema,
		8	ProfileSchema,
		9	SourceSchema,
		10	SyncStateSchema,
		11	TaskRunSchema,
		12	ToolArtifactSchema,
		13	WorkspaceSchema,
		14	} from "@executor-v2/schema";
		15
		16	export const executorConfectSchema = defineSchema({
		17	profiles: defineTable(ProfileSchema).index("by_domainId", ["id"]),
		18	workspaces: defineTable(WorkspaceSchema)
		19	.index("by_domainId", ["id"])
		20	.index("by_profileId", ["profileId"]),
		21	sources: defineTable(SourceSchema)
		22	.index("by_domainId", ["id"])
		23	.index("by_workspaceId", ["workspaceId"]),
		24	toolArtifacts: defineTable(ToolArtifactSchema)
		25	.index("by_domainId", ["id"])
		26	.index("by_workspaceId", ["workspaceId"])
		27	.index("by_sourceId", ["sourceId"]),
		28	credentialRefs: defineTable(CredentialRefSchema)
		29	.index("by_domainId", ["id"])
		30	.index("by_workspaceId", ["workspaceId"])
		31	.index("by_sourceId", ["sourceId"]),
		32	oauthTokens: defineTable(OAuthTokenSchema)
		33	.index("by_domainId", ["id"])
		34	.index("by_workspaceId", ["workspaceId"])
		35	.index("by_sourceId", ["sourceId"]),
		36	policies: defineTable(PolicySchema)
		37	.index("by_domainId", ["id"])
		38	.index("by_workspaceId", ["workspaceId"]),
		39	approvals: defineTable(ApprovalSchema)
		40	.index("by_domainId", ["id"])
		41	.index("by_workspaceId", ["workspaceId"])
		42	.index("by_taskRunId", ["taskRunId"]),
		43	taskRuns: defineTable(TaskRunSchema)
		44	.index("by_domainId", ["id"])
		45	.index("by_workspaceId", ["workspaceId"])
		46	.index("by_sessionId", ["sessionId"]),
		47	syncStates: defineTable(SyncStateSchema)
		48	.index("by_domainId", ["id"])
		49	.index("by_workspaceId", ["workspaceId"]),
		50	events: defineTable(EventEnvelopeSchema)
		51	.index("by_domainId", ["id"])
		52	.index("by_workspaceId", ["workspaceId"])
		53	.index("by_workspaceId_sequence", ["workspaceId", "sequence"]),
		54	});
		55
		56	export type ExecutorConfectTables = TablesFromSchemaDefinition<typeof executorConfectSchema>;
2		57
3	export default executorConfectSchema.convexSchemaDefinition;	58	export default executorConfectSchema.convexSchemaDefinition;

v2/apps/convex/package.json+2−1

   },
   "dependencies": {
     "@executor-v2/confect": "workspace:*",
+    "@executor-v2/control-plane": "workspace:*",
     "@executor-v2/engine": "workspace:*",
     "@executor-v2/mcp-gateway": "workspace:*",
-    "@executor-v2/persistence-convex": "workspace:*",
+    "@executor-v2/schema": "workspace:*",
     "@executor-v2/sdk": "workspace:*",
     "convex": "catalog:",
     "effect": "catalog:"

v2/apps/pm/README.md+5−2

@@ -3,11 +3,14 @@ · 2 unmodified lines
3	Local Process Manager app scaffold for Executor v2.	3	Local Process Manager app scaffold for Executor v2.
4		4
5	Current scaffold includes:	5	Current scaffold includes:
6	- local MCP endpoint at `POST /mcp`	6	- local MCP endpoint at `GET/POST/DELETE /v1/mcp`
7	- health endpoint at `GET /healthz`	7	- health endpoint at `GET /healthz`
8	- MCP tool routing via `@executor-v2/mcp-gateway`	8	- MCP tool routing via `@executor-v2/mcp-gateway`
9	- local runtime adapter injection (`makeLocalInProcessRuntimeAdapter()` in entry wiring)	9	- local runtime adapter injection (`makeLocalInProcessRuntimeAdapter()` in entry wiring)
10	runtime callback endpoint at `POST /runtime/tool-call`	10	runtime callback endpoint at `POST /v1/runtime/tool-call`
		11	- control-plane source endpoints at `GET/POST /v1/workspaces/:workspaceId/sources`
		12	- control-plane source removal endpoint at `DELETE /v1/workspaces/:workspaceId/sources/:sourceId`
		13	- generated OpenAPI spec endpoint at `GET /v1/openapi.json`
11		14
12	App wiring is now split by responsibility:	15	App wiring is now split by responsibility:
13	- `src/config.ts`: Effect config service (`PORT`)	16	- `src/config.ts`: Effect config service (`PORT`)

v2/apps/pm/package.json+2−0

   "dependencies": {
     "@effect/platform": "catalog:",
     "@effect/platform-bun": "^0.86.0",
+    "@executor-v2/control-plane": "workspace:*",
     "@executor-v2/engine": "workspace:*",
     "@executor-v2/mcp-gateway": "workspace:*",
     "@executor-v2/sdk": "workspace:*",
+    "@executor-v2/persistence-local": "workspace:*",
     "effect": "catalog:"
   },
   "devDependencies": {

v2/apps/pm/src/execute.e2e.test.ts+1−1

@@ -109,7 +109,7 @@ const withMcpClient = (port: number) => · 108 unmodified lines
109	Effect.tryPromise({	109	Effect.tryPromise({
110	try: async () => {	110	try: async () => {
111	const transport = new StreamableHTTPClientTransport(	111	const transport = new StreamableHTTPClientTransport(
112	new URL(`http://127.0.0.1:${port}/mcp`),	112	new URL(`http://127.0.0.1:${port}/v1/mcp`),
113	);	113	);
114	const client = new Client(	114	const client = new Client(
115	{ name: "executor-v2-pm-e2e", version: "0.0.0" },	115	{ name: "executor-v2-pm-e2e", version: "0.0.0" },

v2/apps/pm/src/http-server.ts+25−4

@@ -5,6 +5,11 @@ import { · 4 unmodified lines
5	HttpServerResponse,	5	HttpServerResponse,
6	} from "@effect/platform";	6	} from "@effect/platform";
7	import { BunHttpServer, BunHttpServerRequest } from "@effect/platform-bun";	7	import { BunHttpServer, BunHttpServerRequest } from "@effect/platform-bun";
		8	import {
		9	ControlPlaneService,
		10	controlPlaneOpenApiSpec,
		11	makeControlPlaneWebHandler,
		12	} from "@executor-v2/control-plane";
8	import * as Effect from "effect/Effect";	13	import * as Effect from "effect/Effect";
9	import * as Layer from "effect/Layer";	14	import * as Layer from "effect/Layer";
10		15
@@ -25,17 +30,33 @@ const fromWebHandler = (handler: (request: Request) => Promise<Response>) => · 14 unmodified lines
25	export const startPmHttpServer = Effect.fn("@executor-v2/app-pm/http.start")(function* () {	30	export const startPmHttpServer = Effect.fn("@executor-v2/app-pm/http.start")(function* () {
26	const { port } = yield* PmConfig;	31	const { port } = yield* PmConfig;
27	const { handleMcp } = yield* PmMcpHandler;	32	const { handleMcp } = yield* PmMcpHandler;
		33	const controlPlaneService = yield* ControlPlaneService;
		34	const controlPlaneWebHandler = yield* Effect.sync(() =>
		35	makeControlPlaneWebHandler(
		36	Layer.succeed(ControlPlaneService, controlPlaneService),
		37	),
		38	);
		39
		40	yield* Effect.addFinalizer(() =>
		41	Effect.promise(() => controlPlaneWebHandler.dispose()),
		42	);
28		43
29	const httpLive = HttpRouter.empty.pipe(	44	const httpLive = HttpRouter.empty.pipe(
30	HttpRouter.get("/healthz", HttpServerResponse.json({ ok: true, service: "pm" })),	45	HttpRouter.get("/healthz", HttpServerResponse.json({ ok: true, service: "pm" })),
31	HttpRouter.get("/mcp", fromWebHandler(handleMcp)),
32	HttpRouter.post("/mcp", fromWebHandler(handleMcp)),
33	HttpRouter.del("/mcp", fromWebHandler(handleMcp)),
34	HttpRouter.get("/v1/mcp", fromWebHandler(handleMcp)),	46	HttpRouter.get("/v1/mcp", fromWebHandler(handleMcp)),
35	HttpRouter.post("/v1/mcp", fromWebHandler(handleMcp)),	47	HttpRouter.post("/v1/mcp", fromWebHandler(handleMcp)),
36	HttpRouter.del("/v1/mcp", fromWebHandler(handleMcp)),	48	HttpRouter.del("/v1/mcp", fromWebHandler(handleMcp)),
37	HttpRouter.post("/runtime/tool-call", handleToolCallHttp),
38	HttpRouter.post("/v1/runtime/tool-call", handleToolCallHttp),	49	HttpRouter.post("/v1/runtime/tool-call", handleToolCallHttp),
		50	HttpRouter.get("/v1/workspaces/:workspaceId/sources", fromWebHandler(controlPlaneWebHandler.handler)),
		51	HttpRouter.post("/v1/workspaces/:workspaceId/sources", fromWebHandler(controlPlaneWebHandler.handler)),
		52	HttpRouter.del(
		53	"/v1/workspaces/:workspaceId/sources/:sourceId",
		54	fromWebHandler(controlPlaneWebHandler.handler),
		55	),
		56	HttpRouter.get(
		57	"/v1/openapi.json",
		58	HttpServerResponse.unsafeJson(controlPlaneOpenApiSpec),
		59	),
39	HttpServer.serve(),	60	HttpServer.serve(),
40	HttpServer.withLogAddress,	61	HttpServer.withLogAddress,
41	Layer.provide(BunHttpServer.layer({ port })),	62	Layer.provide(BunHttpServer.layer({ port })),

v2/apps/pm/src/main.ts+13−1

+import * as BunContext from "@effect/platform-bun/BunContext";
+import { ControlPlaneServiceLive } from "@executor-v2/control-plane";
 import { makeLocalInProcessRuntimeAdapter } from "@executor-v2/engine";
+import { LocalSourceStoreLive } from "@executor-v2/persistence-local";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
   PmToolProviderRegistryLive,
 );
+const PmControlPlaneDependenciesLive = ControlPlaneServiceLive.pipe(
+  Layer.provide(
+    LocalSourceStoreLive({
+      rootDir: process.env.PM_STATE_ROOT_DIR ?? ".executor-v2/pm-state",
+    }).pipe(Layer.provide(BunContext.layer)),
+  ),
+);
 const PmAppLive = Layer.mergeAll(
   PmConfigLive,
   PmMcpHandlerLive.pipe(Layer.provide(PmMcpDependenciesLive)),
   PmToolCallHandlerLive,
+  PmControlPlaneDependenciesLive,
 );
-const program = startPmHttpServer().pipe(Effect.provide(PmAppLive));
+const program = Effect.scoped(startPmHttpServer()).pipe(Effect.provide(PmAppLive));
 await Effect.runPromise(program);

v2/apps/pm/src/run-executor.ts+11−15

   makeToolProviderRegistry,
   ToolProviderRegistryService,
   type RuntimeAdapter,
+  type RuntimeExecuteError,
 } from "@executor-v2/engine";
 import type { ExecuteRunInput, ExecuteRunResult } from "@executor-v2/sdk";
 import * as Context from "effect/Context";
   PmRunExecutorService
 >() {}
-const errorToText = (error: unknown): string => {
+const formatRuntimeExecuteError = (error: RuntimeExecuteError): string => {
-  if (error instanceof Error) {
+  switch (error._tag) {
-    return error.message;
+    case "RuntimeAdapterError":
+    case "LocalCodeRunnerError":
+    case "DenoSubprocessRunnerError":
+    case "ToolProviderError":
+      return error.details ? `${error.message}: ${error.details}` : error.message;
+    case "ToolProviderRegistryError":
+      return error.message;
   }
-  if (
-    typeof error === "object" &&
-    error !== null &&
-    "message" in error &&
-    typeof error.message === "string"
-  ) {
-    return error.message;
-  }
-  return String(error);
 };
 const makeExecuteRun = (runtimeAdapter: RuntimeAdapter) =>
           Effect.succeed({
             runId,
             status: "failed",
-            error: errorToText(error),
+            error: formatRuntimeExecuteError(error),
           } satisfies ExecuteRunResult),
         ),
       );

v2/apps/pm/src/tool-call-handler.ts+21−22

 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as ParseResult from "effect/ParseResult";
 import * as Schema from "effect/Schema";
 export type PmToolCallHandlerService = {
 const decodeRuntimeToolCallRequest = Schema.decodeUnknown(RuntimeToolCallRequestSchema);
-const errorToText = (error: unknown): string => {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (
-    typeof error === "object" &&
-    error !== null &&
-    "message" in error &&
-    typeof error.message === "string"
-  ) {
-    return error.message;
-  }
-  return String(error);
-};
 const decodeRequestBodyError = (cause: unknown): PmToolCallHttpRequestError =>
   new PmToolCallHttpRequestError({
     message: "Invalid runtime callback request body",
-    details: cause instanceof Error ? cause.message : String(cause),
+    details: String(cause),
   });
+const decodeRequestPayloadError = (cause: unknown): PmToolCallHttpRequestError =>
+  new PmToolCallHttpRequestError({
+    message: "Runtime callback request body is invalid",
+    details: ParseResult.isParseError(cause)
+      ? ParseResult.TreeFormatter.formatErrorSync(cause)
+      : String(cause),
+  });
+const formatHttpRequestError = (error: PmToolCallHttpRequestError): string =>
+  error.details && error.details.length > 0
+    ? `${error.message}: ${error.details}`
+    : error.message;
 const handleToolCall = Effect.fn("@executor-v2/app-pm/tool-call.handle")(function* (
   input: RuntimeToolCallRequest,
 ) {
 )(function* (body: unknown) {
   const handler = yield* PmToolCallHandler;
   const input = yield* decodeRuntimeToolCallRequest(body).pipe(
-    Effect.mapError(decodeRequestBodyError),
+    Effect.mapError(decodeRequestPayloadError),
   );
   return yield* handler.handleToolCall(input);
 });
 export const handleToolCallHttp = Effect.gen(function* () {
-  const body = yield* HttpServerRequest.schemaBodyJson(Schema.Unknown);
+  const body = yield* HttpServerRequest.schemaBodyJson(Schema.Unknown).pipe(
+    Effect.mapError(decodeRequestBodyError),
+  );
   const result = yield* handleToolCallBody(body);
   return yield* HttpServerResponse.json(result, { status: 200 });
 }).pipe(
-  Effect.catchAll((error) =>
+  Effect.catchTag("PmToolCallHttpRequestError", (error) =>
     HttpServerResponse.json(
       {
         ok: false,
         kind: "failed",
-        error: errorToText(error),
+        error: formatHttpRequestError(error),
       } satisfies RuntimeToolCallResult,
       { status: 400 },
     ),

v2/bun.lock+17−17

       "name": "@executor-v2/app-convex",
       "dependencies": {
         "@executor-v2/confect": "workspace:*",
+        "@executor-v2/control-plane": "workspace:*",
         "@executor-v2/engine": "workspace:*",
         "@executor-v2/mcp-gateway": "workspace:*",
-        "@executor-v2/persistence-convex": "workspace:*",
+        "@executor-v2/schema": "workspace:*",
         "@executor-v2/sdk": "workspace:*",
         "convex": "catalog:",
         "effect": "catalog:",
       "dependencies": {
         "@effect/platform": "catalog:",
         "@effect/platform-bun": "^0.86.0",
+        "@executor-v2/control-plane": "workspace:*",
         "@executor-v2/engine": "workspace:*",
         "@executor-v2/mcp-gateway": "workspace:*",
+        "@executor-v2/persistence-local": "workspace:*",
         "@executor-v2/sdk": "workspace:*",
         "effect": "catalog:",
       },
         "vitest": "catalog:",
       },
     },
+    "packages/control-plane": {
+      "name": "@executor-v2/control-plane",
+      "dependencies": {
+        "@effect-atom/atom": "^0.4.11",
+        "@effect/platform": "catalog:",
+        "@executor-v2/persistence-ports": "workspace:*",
+        "@executor-v2/schema": "workspace:*",
+        "@executor-v2/source-manager": "workspace:*",
+        "effect": "catalog:",
+      },
+    },
     "packages/domain": {
       "name": "@executor-v2/domain",
     },
     "packages/oauth": {
       "name": "@executor-v2/oauth",
     },
-    "packages/rpc": {
-      "name": "@executor-v2/rpc",
-    },
     "packages/schema": {
       "name": "@executor-v2/schema",
       "dependencies": {
         "effect": "catalog:",
       },
     },
-    "packages/state-convex": {
-      "name": "@executor-v2/persistence-convex",
-      "dependencies": {
-        "@executor-v2/confect": "workspace:*",
-        "@executor-v2/persistence-ports": "workspace:*",
-        "@executor-v2/schema": "workspace:*",
-        "effect": "catalog:",
-      },
-    },
     "packages/state-local-file": {
       "name": "@executor-v2/persistence-local",
       "dependencies": {
     "@executor-v2/confect": ["@executor-v2/confect@workspace:packages/confect"],
+    "@executor-v2/control-plane": ["@executor-v2/control-plane@workspace:packages/control-plane"],
     "@executor-v2/domain": ["@executor-v2/domain@workspace:packages/domain"],
     "@executor-v2/engine": ["@executor-v2/engine@workspace:packages/engine"],
     "@executor-v2/oauth": ["@executor-v2/oauth@workspace:packages/oauth"],
-    "@executor-v2/persistence-convex": ["@executor-v2/persistence-convex@workspace:packages/state-convex"],
     "@executor-v2/persistence-local": ["@executor-v2/persistence-local@workspace:packages/state-local-file"],
     "@executor-v2/persistence-ports": ["@executor-v2/persistence-ports@workspace:packages/state-contracts"],
-    "@executor-v2/rpc": ["@executor-v2/rpc@workspace:packages/rpc"],
     "@executor-v2/schema": ["@executor-v2/schema@workspace:packages/schema"],
     "@executor-v2/sdk": ["@executor-v2/sdk@workspace:packages/sdk"],

v2/packages/control-plane/package.jsonrenamed from v2/packages/state-convex/package.json+6−4

 {
-  "name": "@executor-v2/persistence-convex",
+  "name": "@executor-v2/control-plane",
   "private": true,
   "type": "module",
   "exports": {
     "typecheck": "bunx tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@executor-v2/confect": "workspace:*",
+    "@effect-atom/atom": "^0.4.11",
-    "@executor-v2/schema": "workspace:*",
+    "@effect/platform": "catalog:",
     "@executor-v2/persistence-ports": "workspace:*",
+    "@executor-v2/schema": "workspace:*",
+    "@executor-v2/source-manager": "workspace:*",
     "effect": "catalog:"
   }
 }

v2/packages/control-plane/src/api.ts+26−0

@@ -0,0 +1,26 @@
	1	import { HttpApi, OpenApi } from "@effect/platform";
	2
	3	import { SourcesApi } from "./sources/api";
	4
	5	export {
	6	ControlPlaneBadRequestError,
	7	ControlPlaneStorageError,
	8	} from "./errors";
	9
	10	export {
	11	RemoveSourceResultSchema,
	12	UpsertSourcePayloadSchema,
	13	type RemoveSourceResult,
	14	type UpsertSourcePayload,
	15	} from "./sources/api";
	16
	17	export class ControlPlaneApi extends HttpApi.make("controlPlane")
	18	.add(SourcesApi)
	19	.annotateContext(
	20	OpenApi.annotations({
	21	title: "Executor v2 Control Plane API",
	22	description: "Backend-agnostic control plane API",
	23	}),
	24	) {}
	25
	26	export const controlPlaneOpenApiSpec = OpenApi.fromApi(ControlPlaneApi);

v2/packages/control-plane/src/client.ts+159−0

@@ -0,0 +1,159 @@
	1	import { Atom, Result } from "@effect-atom/atom";
	2	import {
	3	FetchHttpClient,
	4	HttpApiClient,
	5	HttpApiError,
	6	HttpClientError,
	7	} from "@effect/platform";
	8	import type {
	9	Source,
	10	SourceId,
	11	WorkspaceId,
	12	} from "@executor-v2/schema";
	13	import * as Effect from "effect/Effect";
	14	import * as ParseResult from "effect/ParseResult";
	15
	16	import {
	17	ControlPlaneApi,
	18	type ControlPlaneBadRequestError,
	19	type ControlPlaneStorageError,
	20	type RemoveSourceResult,
	21	type UpsertSourcePayload,
	22	} from "./api";
	23
	24	export type ControlPlaneClientOptions = {
	25	baseUrl: string;
	26	};
	27
	28	export type ControlPlaneClientError =
	29	\| ControlPlaneBadRequestError
	30	\| ControlPlaneStorageError
	31	\| HttpApiError.HttpApiDecodeError
	32	\| HttpClientError.HttpClientError
	33	\| ParseResult.ParseError;
	34
	35	export type ListSourcesRequest = {
	36	workspaceId: WorkspaceId;
	37	};
	38
	39	export type UpsertSourceRequest = {
	40	workspaceId: WorkspaceId;
	41	payload: UpsertSourcePayload;
	42	};
	43
	44	export type RemoveSourceRequest = {
	45	workspaceId: WorkspaceId;
	46	sourceId: SourceId;
	47	};
	48
	49	export type ControlPlaneReadOptions = {
	50	enabled?: boolean;
	51	};
	52
	53	export const makeControlPlaneClient = (options: ControlPlaneClientOptions) =>
	54	HttpApiClient.make(ControlPlaneApi, {
	55	baseUrl: options.baseUrl,
	56	});
	57
	58	const isReadEnabled = (options?: ControlPlaneReadOptions): boolean =>
	59	options?.enabled ?? true;
	60
	61	const makeDisabledResultAtom = <Success, Error>() =>
	62	Atom.make(Result.initial<Success, Error>());
	63
	64	export const createControlPlaneAtomClient = (
	65	options: ControlPlaneClientOptions,
	66	) => {
	67	const baseLayer = FetchHttpClient.layer;
	68	const runtime = Atom.runtime(baseLayer);
	69
	70	const listSourcesEffect = (
	71	input: ListSourcesRequest,
	72	): Effect.Effect<ReadonlyArray<Source>, ControlPlaneClientError, never> =>
	73	Effect.gen(function* () {
	74	const client = yield* makeControlPlaneClient(options);
	75	return yield* client.sources.list({
	76	path: {
	77	workspaceId: input.workspaceId,
	78	},
	79	});
	80	}).pipe(Effect.provide(baseLayer));
	81
	82	const upsertSourceEffect = (
	83	input: UpsertSourceRequest,
	84	): Effect.Effect<Source, ControlPlaneClientError, never> =>
	85	Effect.gen(function* () {
	86	const client = yield* makeControlPlaneClient(options);
	87	return yield* client.sources.upsert({
	88	path: {
	89	workspaceId: input.workspaceId,
	90	},
	91	payload: input.payload,
	92	});
	93	}).pipe(Effect.provide(baseLayer));
	94
	95	const removeSourceEffect = (
	96	input: RemoveSourceRequest,
	97	): Effect.Effect<RemoveSourceResult, ControlPlaneClientError, never> =>
	98	Effect.gen(function* () {
	99	const client = yield* makeControlPlaneClient(options);
	100	return yield* client.sources.remove({
	101	path: {
	102	workspaceId: input.workspaceId,
	103	sourceId: input.sourceId,
	104	},
	105	});
	106	}).pipe(Effect.provide(baseLayer));
	107
	108	const listSourcesFamily = Atom.family((workspaceId: WorkspaceId) =>
	109	runtime.atom(
	110	listSourcesEffect({
	111	workspaceId,
	112	}),
	113	),
	114	);
	115
	116	const listDisabledAtom = makeDisabledResultAtom<
	117	ReadonlyArray<Source>,
	118	ControlPlaneClientError
	119	>();
	120
	121	const upsertSourceMutate = runtime.fn<UpsertSourceRequest>()(
	122	Effect.fnUntraced(function* (input) {
	123	return yield* upsertSourceEffect(input);
	124	}),
	125	);
	126
	127	const removeSourceMutate = runtime.fn<RemoveSourceRequest>()(
	128	Effect.fnUntraced(function* (input) {
	129	return yield* removeSourceEffect(input);
	130	}),
	131	);
	132
	133	return {
	134	runtime,
	135	sources: {
	136	list: {
	137	query: (input: ListSourcesRequest, readOptions?: ControlPlaneReadOptions) =>
	138	isReadEnabled(readOptions)
	139	? listSourcesFamily(input.workspaceId)
	140	: listDisabledAtom,
	141	queryEffect: listSourcesEffect,
	142	queryPromise: (input: ListSourcesRequest) =>
	143	Effect.runPromise(listSourcesEffect(input)),
	144	},
	145	upsert: {
	146	mutate: upsertSourceMutate,
	147	mutateEffect: upsertSourceEffect,
	148	mutatePromise: (input: UpsertSourceRequest) =>
	149	Effect.runPromise(upsertSourceEffect(input)),
	150	},
	151	remove: {
	152	mutate: removeSourceMutate,
	153	mutateEffect: removeSourceEffect,
	154	mutatePromise: (input: RemoveSourceRequest) =>
	155	Effect.runPromise(removeSourceEffect(input)),
	156	},
	157	},
	158	};
	159	};

v2/packages/control-plane/src/errors.ts+22−0

@@ -0,0 +1,22 @@
	1	import { HttpApiSchema } from "@effect/platform";
	2	import * as Schema from "effect/Schema";
	3
	4	export class ControlPlaneBadRequestError extends Schema.TaggedError<ControlPlaneBadRequestError>()(
	5	"ControlPlaneBadRequestError",
	6	{
	7	operation: Schema.String,
	8	message: Schema.String,
	9	details: Schema.String,
	10	},
	11	HttpApiSchema.annotations({ status: 400 }),
	12	) {}
	13
	14	export class ControlPlaneStorageError extends Schema.TaggedError<ControlPlaneStorageError>()(
	15	"ControlPlaneStorageError",
	16	{
	17	operation: Schema.String,
	18	message: Schema.String,
	19	details: Schema.String,
	20	},
	21	HttpApiSchema.annotations({ status: 500 }),
	22	) {}

v2/packages/control-plane/src/http.ts+20−0

@@ -0,0 +1,20 @@
	1	import { HttpApiBuilder, HttpServer } from "@effect/platform";
	2	import * as Layer from "effect/Layer";
	3
	4	import { ControlPlaneApi } from "./api";
	5	import { ControlPlaneService } from "./service";
	6	import { ControlPlaneSourcesLive } from "./sources/http";
	7
	8	export const ControlPlaneApiLive = HttpApiBuilder.api(ControlPlaneApi).pipe(
	9	Layer.provide(ControlPlaneSourcesLive),
	10	);
	11
	12	export const makeControlPlaneWebHandler = <E>(
	13	serviceLayer: Layer.Layer<ControlPlaneService, E, never>,
	14	) =>
	15	HttpApiBuilder.toWebHandler(
	16	Layer.mergeAll(
	17	ControlPlaneApiLive.pipe(Layer.provide(serviceLayer)),
	18	HttpServer.layerContext,
	19	),
	20	);

v2/packages/control-plane/src/index.ts+44−0

@@ -0,0 +1,44 @@
	1	export {
	2	ControlPlaneApi,
	3	RemoveSourceResultSchema,
	4	UpsertSourcePayloadSchema,
	5	controlPlaneOpenApiSpec,
	6	type RemoveSourceResult,
	7	type UpsertSourcePayload,
	8	} from "./api";
	9
	10	export {
	11	ControlPlaneBadRequestError,
	12	ControlPlaneStorageError,
	13	} from "./errors";
	14
	15	export {
	16	ControlPlaneService,
	17	ControlPlaneServiceLive,
	18	makeControlPlaneService,
	19	type ControlPlaneServiceShape,
	20	} from "./service";
	21
	22	export {
	23	ControlPlaneApiLive,
	24	makeControlPlaneWebHandler,
	25	} from "./http";
	26
	27	export {
	28	ControlPlaneSourcesLive,
	29	makeControlPlaneSourcesService,
	30	type ControlPlaneSourcesServiceShape,
	31	type RemoveSourceInput,
	32	type UpsertSourceInput,
	33	} from "./sources";
	34
	35	export {
	36	createControlPlaneAtomClient,
	37	makeControlPlaneClient,
	38	type ControlPlaneClientError,
	39	type ControlPlaneClientOptions,
	40	type ControlPlaneReadOptions,
	41	type ListSourcesRequest,
	42	type RemoveSourceRequest,
	43	type UpsertSourceRequest,
	44	} from "./client";

v2/packages/control-plane/src/service.ts+37−0

@@ -0,0 +1,37 @@
	1	import { SourceCatalog, SourceCatalogLive } from "@executor-v2/source-manager/source-catalog";
	2	import * as Context from "effect/Context";
	3	import * as Effect from "effect/Effect";
	4	import * as Layer from "effect/Layer";
	5
	6	import {
	7	makeControlPlaneSourcesService,
	8	type ControlPlaneSourcesServiceShape,
	9	} from "./sources/service";
	10
	11	export type ControlPlaneServiceShape = ControlPlaneSourcesServiceShape;
	12
	13	export class ControlPlaneService extends Context.Tag("@executor-v2/control-plane/ControlPlaneService")<
	14	ControlPlaneService,
	15	ControlPlaneServiceShape
	16	>() {}
	17
	18	export const makeControlPlaneService = (
	19	services: {
	20	sources: ControlPlaneSourcesServiceShape;
	21	},
	22	): ControlPlaneServiceShape => ({
	23	...services.sources,
	24	});
	25
	26	export const ControlPlaneServiceLive = Layer.effect(
	27	ControlPlaneService,
	28	Effect.gen(function* () {
	29	const sourceCatalog = yield* SourceCatalog;
	30
	31	return ControlPlaneService.of(
	32	makeControlPlaneService({
	33	sources: makeControlPlaneSourcesService(sourceCatalog),
	34	}),
	35	);
	36	}),
	37	).pipe(Layer.provide(SourceCatalogLive));

v2/packages/control-plane/src/sources/api.ts+51−0

@@ -0,0 +1,51 @@
	1	import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "@effect/platform";
	2	import { SourceIdSchema, SourceSchema, WorkspaceIdSchema } from "@executor-v2/schema";
	3	import * as Schema from "effect/Schema";
	4
	5	import { ControlPlaneBadRequestError, ControlPlaneStorageError } from "../errors";
	6
	7	const RequiredUpsertSourcePayloadSchema = SourceSchema.pipe(
	8	Schema.pick("name", "kind", "endpoint"),
	9	);
	10
	11	const OptionalUpsertSourcePayloadSchema = SourceSchema.pipe(
	12	Schema.pick("id", "status", "enabled", "configJson", "sourceHash", "lastError"),
	13	Schema.partialWith({ exact: true }),
	14	);
	15
	16	export const UpsertSourcePayloadSchema = RequiredUpsertSourcePayloadSchema.pipe(
	17	Schema.extend(OptionalUpsertSourcePayloadSchema),
	18	);
	19
	20	export type UpsertSourcePayload = typeof UpsertSourcePayloadSchema.Type;
	21
	22	export const RemoveSourceResultSchema = Schema.Struct({
	23	removed: Schema.Boolean,
	24	});
	25
	26	export type RemoveSourceResult = typeof RemoveSourceResultSchema.Type;
	27
	28	const workspaceIdParam = HttpApiSchema.param("workspaceId", WorkspaceIdSchema);
	29	const sourceIdParam = HttpApiSchema.param("sourceId", SourceIdSchema);
	30
	31	export class SourcesApi extends HttpApiGroup.make("sources")
	32	.add(
	33	HttpApiEndpoint.get("list")`/workspaces/${workspaceIdParam}/sources`
	34	.addSuccess(Schema.Array(SourceSchema))
	35	.addError(ControlPlaneBadRequestError)
	36	.addError(ControlPlaneStorageError),
	37	)
	38	.add(
	39	HttpApiEndpoint.post("upsert")`/workspaces/${workspaceIdParam}/sources`
	40	.setPayload(UpsertSourcePayloadSchema)
	41	.addSuccess(SourceSchema)
	42	.addError(ControlPlaneBadRequestError)
	43	.addError(ControlPlaneStorageError),
	44	)
	45	.add(
	46	HttpApiEndpoint.del("remove")`/workspaces/${workspaceIdParam}/sources/${sourceIdParam}`
	47	.addSuccess(RemoveSourceResultSchema)
	48	.addError(ControlPlaneBadRequestError)
	49	.addError(ControlPlaneStorageError),
	50	)
	51	.prefix("/v1") {}

v2/packages/control-plane/src/sources/http.ts+67−0

@@ -0,0 +1,67 @@
	1	import { HttpApiBuilder } from "@effect/platform";
	2	import { type SourceStoreError } from "@executor-v2/persistence-ports";
	3	import * as Effect from "effect/Effect";
	4
	5	import { ControlPlaneBadRequestError, ControlPlaneStorageError } from "../errors";
	6	import { ControlPlaneService } from "../service";
	7	import { ControlPlaneApi } from "../api";
	8
	9	const toStorageError = (
	10	operation: string,
	11	cause: SourceStoreError,
	12	): ControlPlaneStorageError =>
	13	new ControlPlaneStorageError({
	14	operation,
	15	message: "Control plane operation failed",
	16	details: cause.details ?? cause.message,
	17	});
	18
	19	export const ControlPlaneSourcesLive = HttpApiBuilder.group(
	20	ControlPlaneApi,
	21	"sources",
	22	(handlers) =>
	23	handlers
	24	.handle("list", ({ path }) =>
	25	Effect.gen(function* () {
	26	const service = yield* ControlPlaneService;
	27	return yield* service.listSources(path.workspaceId);
	28	}).pipe(
	29	Effect.catchTag("SourceStoreError", (cause) =>
	30	toStorageError("sources.list", cause),
	31	),
	32	),
	33	)
	34	.handle("upsert", ({ path, payload }) =>
	35	Effect.gen(function* () {
	36	const service = yield* ControlPlaneService;
	37	return yield* service.upsertSource({
	38	workspaceId: path.workspaceId,
	39	payload,
	40	});
	41	}).pipe(
	42	Effect.catchTag("SourceCatalogValidationError", (error) =>
	43	new ControlPlaneBadRequestError({
	44	operation: error.operation,
	45	message: error.message,
	46	details: error.details,
	47	}),
	48	),
	49	Effect.catchTag("SourceStoreError", (cause) =>
	50	toStorageError("sources.upsert", cause),
	51	),
	52	),
	53	)
	54	.handle("remove", ({ path }) =>
	55	Effect.gen(function* () {
	56	const service = yield* ControlPlaneService;
	57	return yield* service.removeSource({
	58	workspaceId: path.workspaceId,
	59	sourceId: path.sourceId,
	60	});
	61	}).pipe(
	62	Effect.catchTag("SourceStoreError", (cause) =>
	63	toStorageError("sources.remove", cause),
	64	),
	65	),
	66	),
	67	);

v2/packages/control-plane/src/sources/index.ts+16−0

@@ -0,0 +1,16 @@
	1	export {
	2	RemoveSourceResultSchema,
	3	SourcesApi,
	4	UpsertSourcePayloadSchema,
	5	type RemoveSourceResult,
	6	type UpsertSourcePayload,
	7	} from "./api";
	8
	9	export {
	10	makeControlPlaneSourcesService,
	11	type ControlPlaneSourcesServiceShape,
	12	type RemoveSourceInput,
	13	type UpsertSourceInput,
	14	} from "./service";
	15
	16	export { ControlPlaneSourcesLive } from "./http";

v2/packages/control-plane/src/sources/service.ts+45−0

@@ -0,0 +1,45 @@
	1	import { type SourceStoreError } from "@executor-v2/persistence-ports";
	2	import {
	3	SourceCatalogValidationError,
	4	type SourceCatalogService,
	5	} from "@executor-v2/source-manager/source-catalog";
	6	import { type Source, type SourceId, type WorkspaceId } from "@executor-v2/schema";
	7	import * as Effect from "effect/Effect";
	8
	9	import type { RemoveSourceResult, UpsertSourcePayload } from "./api";
	10
	11	export type UpsertSourceInput = {
	12	workspaceId: WorkspaceId;
	13	payload: UpsertSourcePayload;
	14	};
	15
	16	export type RemoveSourceInput = {
	17	workspaceId: WorkspaceId;
	18	sourceId: SourceId;
	19	};
	20
	21	export type ControlPlaneSourcesServiceShape = {
	22	listSources: (
	23	workspaceId: WorkspaceId,
	24	) => Effect.Effect<ReadonlyArray<Source>, SourceStoreError>;
	25	upsertSource: (
	26	input: UpsertSourceInput,
	27	) => Effect.Effect<Source, SourceStoreError \| SourceCatalogValidationError>;
	28	removeSource: (input: RemoveSourceInput) => Effect.Effect<RemoveSourceResult, SourceStoreError>;
	29	};
	30
	31	export const makeControlPlaneSourcesService = (
	32	sourceCatalog: SourceCatalogService,
	33	): ControlPlaneSourcesServiceShape => ({
	34	listSources: (workspaceId) => sourceCatalog.listSources(workspaceId),
	35	upsertSource: (input) =>
	36	sourceCatalog.upsertSource({
	37	workspaceId: input.workspaceId,
	38	payload: input.payload,
	39	}),
	40	removeSource: (input) =>
	41	sourceCatalog.removeSource({
	42	workspaceId: input.workspaceId,
	43	sourceId: input.sourceId,
	44	}),
	45	});

v2/packages/control-plane/tsconfig.jsonrenamed from v2/packages/rpc/tsconfig.json+4−1

@@ -1,4 +1,7 @@
1	{	1	{
2	"extends": "../../tsconfig.json",	2	"extends": "../../tsconfig.json",
		3	"compilerOptions": {
		4	"types": ["node", "bun"]
		5	},
3	"include": ["src"]	6	"include": ["src"]
4	}	7	}

v2/packages/engine/src/run-client.ts+17−18

   type ToolProvider,
   type ToolProviderRegistry,
 } from "./tool-providers";
-import type { RuntimeAdapter, RuntimeRunnableTool } from "./runtime-adapters";
+import type {
+  RuntimeAdapter,
+  RuntimeExecuteError,
+  RuntimeRunnableTool,
+} from "./runtime-adapters";
 export type RuntimeRunClientExecuteInput = {
   code: string;
   makeRunId?: () => string;
 };
-const errorToText = (error: unknown): string => {
+const formatRuntimeExecuteError = (error: RuntimeExecuteError): string => {
-  if (error instanceof Error) {
+  switch (error._tag) {
-    return error.message;
+    case "RuntimeAdapterError":
+    case "LocalCodeRunnerError":
+    case "DenoSubprocessRunnerError":
+    case "ToolProviderError":
+      return error.details ? `${error.message}: ${error.details}` : error.message;
+    case "ToolProviderRegistryError":
+      return error.message;
   }
-  if (
-    typeof error === "object" &&
-    error !== null &&
-    "message" in error &&
-    typeof error.message === "string"
-  ) {
-    return error.message;
-  }
-  return String(error);
 };
 const toInMemoryDescriptor = (
           operation: "invoke",
           providerKind: "in_memory",
           message: `In-memory tool invocation failed: ${input.tool.toolId}`,
-          details: cause instanceof Error ? cause.message : String(cause),
+          details: String(cause),
         }),
     });
   },
         return {
           runId,
           status: "failed",
-          error: errorToText(availabilityResult.left),
+          error: "Runtime availability check failed",
         };
       }
         return {
           runId,
           status: "failed",
-          error: errorToText(executionResult.left),
+          error: formatRuntimeExecuteError(executionResult.left),
         };
       }

v2/packages/rpc/README.md+0−3

@@ -1,3 +0,0 @@
1	# rpc
2
3	Effect RPC contract scaffold for Executor v2.

v2/packages/rpc/package.json+0−8

@@ -1,8 +0,0 @@
1	{
2	"name": "@executor-v2/rpc",
3	"private": true,
4	"type": "module",
5	"scripts": {
6	"typecheck": "bunx tsc --noEmit -p tsconfig.json"
7	}
8	}

v2/packages/rpc/src/index.ts+0−1

@@ -1 +0,0 @@
1	export {};

v2/packages/source-manager/package.json+2−1

   "private": true,
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./source-catalog": "./src/source-catalog.ts"
   },
   "scripts": {
     "test": "bunx vitest run --no-watch src/*.test.ts",

v2/packages/source-manager/src/index.ts+12−0

@@ -5,3 +5,15 @@ export { · 4 unmodified lines
5	type RefreshOpenApiArtifactRequest,	5	type RefreshOpenApiArtifactRequest,
6	type SourceManagerService,	6	type SourceManagerService,
7	} from "./service";	7	} from "./service";
		8
		9	export {
		10	SourceCatalog,
		11	SourceCatalogLive,
		12	SourceCatalogValidationError,
		13	makeSourceCatalogService,
		14	type RemoveSourceRequest,
		15	type RemoveSourceResult,
		16	type SourceCatalogService,
		17	type UpsertSourcePayload,
		18	type UpsertSourceRequest,
		19	} from "./source-catalog";

v2/packages/source-manager/src/source-catalog.ts+158−0

@@ -0,0 +1,158 @@
	1	import {
	2	SourceStoreError,
	3	SourceStoreService,
	4	type SourceStore,
	5	} from "@executor-v2/persistence-ports";
	6	import {
	7	SourceIdSchema,
	8	SourceSchema,
	9	type Source,
	10	type SourceId,
	11	type SourceKind,
	12	type SourceStatus,
	13	type WorkspaceId,
	14	} from "@executor-v2/schema";
	15	import * as Context from "effect/Context";
	16	import * as Data from "effect/Data";
	17	import * as Effect from "effect/Effect";
	18	import * as Layer from "effect/Layer";
	19	import * as Option from "effect/Option";
	20	import * as ParseResult from "effect/ParseResult";
	21	import * as Schema from "effect/Schema";
	22
	23	export class SourceCatalogValidationError extends Data.TaggedError(
	24	"SourceCatalogValidationError",
	25	)<{
	26	operation: string;
	27	message: string;
	28	details: string;
	29	}> {}
	30
	31	export type UpsertSourcePayload = {
	32	id?: SourceId;
	33	name: string;
	34	kind: SourceKind;
	35	endpoint: string;
	36	status?: SourceStatus;
	37	enabled?: boolean;
	38	configJson?: string;
	39	sourceHash?: string \| null;
	40	lastError?: string \| null;
	41	};
	42
	43	export type UpsertSourceRequest = {
	44	workspaceId: WorkspaceId;
	45	payload: UpsertSourcePayload;
	46	now?: () => number;
	47	};
	48
	49	export type RemoveSourceRequest = {
	50	workspaceId: WorkspaceId;
	51	sourceId: SourceId;
	52	};
	53
	54	export type RemoveSourceResult = {
	55	removed: boolean;
	56	};
	57
	58	export type SourceCatalogService = {
	59	listSources: (
	60	workspaceId: WorkspaceId,
	61	) => Effect.Effect<ReadonlyArray<Source>, SourceStoreError>;
	62	upsertSource: (
	63	input: UpsertSourceRequest,
	64	) => Effect.Effect<Source, SourceStoreError \| SourceCatalogValidationError>;
	65	removeSource: (
	66	input: RemoveSourceRequest,
	67	) => Effect.Effect<RemoveSourceResult, SourceStoreError>;
	68	};
	69
	70	export class SourceCatalog extends Context.Tag("@executor-v2/source-manager/SourceCatalog")<
	71	SourceCatalog,
	72	SourceCatalogService
	73	>() {}
	74
	75	const decodeSourceId = Schema.decodeUnknown(SourceIdSchema);
	76	const decodeSource = Schema.decodeUnknown(SourceSchema);
	77
	78	const sourceStoreKey = (source: Source): string => `${source.workspaceId}:${source.id}`;
	79
	80	const sortSources = (sources: ReadonlyArray<Source>): Array<Source> =>
	81	[...sources].sort((left, right) => {
	82	const leftName = left.name.toLowerCase();
	83	const rightName = right.name.toLowerCase();
	84
	85	if (leftName === rightName) {
	86	return sourceStoreKey(left).localeCompare(sourceStoreKey(right));
	87	}
	88
	89	return leftName.localeCompare(rightName);
	90	});
	91
	92	const toSourceCatalogValidationError = (
	93	operation: string,
	94	cause: unknown,
	95	): SourceCatalogValidationError =>
	96	new SourceCatalogValidationError({
	97	operation,
	98	message: "Invalid source payload",
	99	details: ParseResult.isParseError(cause)
	100	? ParseResult.TreeFormatter.formatErrorSync(cause)
	101	: String(cause),
	102	});
	103
	104	const createSourceId = (): Effect.Effect<SourceId, SourceCatalogValidationError> =>
	105	decodeSourceId(`src_${crypto.randomUUID()}`).pipe(
	106	Effect.mapError((cause) => toSourceCatalogValidationError("sources.upsert.id", cause)),
	107	);
	108
	109	const timestamp = (clock?: () => number): number => clock?.() ?? Date.now();
	110
	111	export const makeSourceCatalogService = (
	112	sourceStore: SourceStore,
	113	): SourceCatalogService => ({
	114	listSources: (workspaceId) =>
	115	sourceStore.listByWorkspace(workspaceId).pipe(Effect.map(sortSources)),
	116	upsertSource: (input) =>
	117	Effect.gen(function* () {
	118	const sourceId = input.payload.id ?? (yield* createSourceId());
	119	const now = timestamp(input.now);
	120	const existingOption = yield* sourceStore.getById(input.workspaceId, sourceId);
	121	const existing = Option.getOrUndefined(existingOption);
	122
	123	const source = yield* decodeSource({
	124	id: sourceId,
	125	workspaceId: input.workspaceId,
	126	name: input.payload.name,
	127	kind: input.payload.kind,
	128	endpoint: input.payload.endpoint,
	129	status: input.payload.status ?? "draft",
	130	enabled: input.payload.enabled ?? true,
	131	configJson: input.payload.configJson ?? "{}",
	132	sourceHash: input.payload.sourceHash ?? null,
	133	lastError: input.payload.lastError ?? null,
	134	createdAt: existing?.createdAt ?? now,
	135	updatedAt: now,
	136	}).pipe(
	137	Effect.mapError((cause) =>
	138	toSourceCatalogValidationError("sources.upsert.payload", cause),
	139	),
	140	);
	141
	142	yield* sourceStore.upsert(source);
	143	return source;
	144	}),
	145	removeSource: (input) =>
	146	sourceStore.removeById(input.workspaceId, input.sourceId).pipe(
	147	Effect.map((removed): RemoveSourceResult => ({ removed })),
	148	),
	149	});
	150
	151	export const SourceCatalogLive = Layer.effect(
	152	SourceCatalog,
	153	Effect.gen(function* () {
	154	const sourceStore = yield* SourceStoreService;
	155
	156	return SourceCatalog.of(makeSourceCatalogService(sourceStore));
	157	}),
	158	);

v2/packages/state-convex/README.md+0−8

@@ -1,8 +0,0 @@
1	# persistence-convex
2
3	Convex-backed persistence adapter scaffold for Executor v2.
4
5	Current scaffold includes:
6	- Convex table-typed ID schemas in `src/convex-ids.ts`
7	- shared Convex schema projection in `src/schema.ts`
8	- first adapter implementation for `ProfileStore` in `src/profiles.ts`

v2/packages/state-convex/src/convex-ids.ts+0−25

@@ -1,25 +0,0 @@
1	import { Id } from "@executor-v2/confect";
2
3	export const ProfileDocIdSchema = Id("profiles");
4	export const WorkspaceDocIdSchema = Id("workspaces");
5	export const SourceDocIdSchema = Id("sources");
6	export const ToolArtifactDocIdSchema = Id("toolArtifacts");
7	export const CredentialRefDocIdSchema = Id("credentialRefs");
8	export const OAuthTokenDocIdSchema = Id("oauthTokens");
9	export const PolicyDocIdSchema = Id("policies");
10	export const ApprovalDocIdSchema = Id("approvals");
11	export const TaskRunDocIdSchema = Id("taskRuns");
12	export const SyncStateDocIdSchema = Id("syncStates");
13	export const EventDocIdSchema = Id("events");
14
15	export type ProfileDocId = typeof ProfileDocIdSchema.Type;
16	export type WorkspaceDocId = typeof WorkspaceDocIdSchema.Type;
17	export type SourceDocId = typeof SourceDocIdSchema.Type;
18	export type ToolArtifactDocId = typeof ToolArtifactDocIdSchema.Type;
19	export type CredentialRefDocId = typeof CredentialRefDocIdSchema.Type;
20	export type OAuthTokenDocId = typeof OAuthTokenDocIdSchema.Type;
21	export type PolicyDocId = typeof PolicyDocIdSchema.Type;
22	export type ApprovalDocId = typeof ApprovalDocIdSchema.Type;
23	export type TaskRunDocId = typeof TaskRunDocIdSchema.Type;
24	export type SyncStateDocId = typeof SyncStateDocIdSchema.Type;
25	export type EventDocId = typeof EventDocIdSchema.Type;

v2/packages/state-convex/src/index.ts+0−26

@@ -1,26 +0,0 @@
1	export {
2	ApprovalDocIdSchema,
3	CredentialRefDocIdSchema,
4	EventDocIdSchema,
5	OAuthTokenDocIdSchema,
6	PolicyDocIdSchema,
7	ProfileDocIdSchema,
8	SourceDocIdSchema,
9	SyncStateDocIdSchema,
10	TaskRunDocIdSchema,
11	ToolArtifactDocIdSchema,
12	WorkspaceDocIdSchema,
13	type ApprovalDocId,
14	type CredentialRefDocId,
15	type EventDocId,
16	type OAuthTokenDocId,
17	type PolicyDocId,
18	type ProfileDocId,
19	type SourceDocId,
20	type SyncStateDocId,
21	type TaskRunDocId,
22	type ToolArtifactDocId,
23	type WorkspaceDocId,
24	} from "./convex-ids";
25	export { makeConvexProfileStore } from "./profiles";
26	export { executorConfectSchema, type ExecutorConfectTables } from "./schema";

v2/packages/state-convex/src/profiles.ts+0−33

@@ -1,33 +0,0 @@
1	import type {
2	ConfectQueryCtx,
3	DocumentFromTable,
4	} from "@executor-v2/confect";
5	import { ProfileSchema, type Profile, type ProfileId } from "@executor-v2/schema";
6	import type { ProfileStore } from "@executor-v2/persistence-ports";
7	import * as Effect from "effect/Effect";
8	import { pipe } from "effect/Function";
9	import * as Option from "effect/Option";
10	import * as Schema from "effect/Schema";
11
12	import type { ExecutorConfectTables } from "./schema";
13
14	type ProfileDocument = DocumentFromTable<ExecutorConfectTables, "profiles">;
15
16	const toProfile = (document: ProfileDocument): Profile => {
17	const { _id: _ignoredId, _creationTime: _ignoredCreationTime, ...profile } = document;
18	return Schema.decodeUnknownSync(ProfileSchema)(profile);
19	};
20
21	export const makeConvexProfileStore = (
22	ctx: ConfectQueryCtx<ExecutorConfectTables>,
23	): ProfileStore => ({
24	getById: (id: ProfileId) =>
25	pipe(
26	ctx.db
27	.query("profiles")
28	.withIndex("by_domainId", (q) => q.eq("id", id))
29	.unique(),
30	Effect.orDie,
31	Effect.map(Option.map(toProfile)),
32	),
33	});

v2/packages/state-convex/src/schema.ts+0−56

@@ -1,56 +0,0 @@
1	import { defineSchema, defineTable, type TablesFromSchemaDefinition } from "@executor-v2/confect";
2	import {
3	ApprovalSchema,
4	CredentialRefSchema,
5	EventEnvelopeSchema,
6	OAuthTokenSchema,
7	PolicySchema,
8	ProfileSchema,
9	SourceSchema,
10	SyncStateSchema,
11	TaskRunSchema,
12	ToolArtifactSchema,
13	WorkspaceSchema,
14	} from "@executor-v2/schema";
15
16	export const executorConfectSchema = defineSchema({
17	profiles: defineTable(ProfileSchema).index("by_domainId", ["id"]),
18	workspaces: defineTable(WorkspaceSchema)
19	.index("by_domainId", ["id"])
20	.index("by_profileId", ["profileId"]),
21	sources: defineTable(SourceSchema)
22	.index("by_domainId", ["id"])
23	.index("by_workspaceId", ["workspaceId"]),
24	toolArtifacts: defineTable(ToolArtifactSchema)
25	.index("by_domainId", ["id"])
26	.index("by_workspaceId", ["workspaceId"])
27	.index("by_sourceId", ["sourceId"]),
28	credentialRefs: defineTable(CredentialRefSchema)
29	.index("by_domainId", ["id"])
30	.index("by_workspaceId", ["workspaceId"])
31	.index("by_sourceId", ["sourceId"]),
32	oauthTokens: defineTable(OAuthTokenSchema)
33	.index("by_domainId", ["id"])
34	.index("by_workspaceId", ["workspaceId"])
35	.index("by_sourceId", ["sourceId"]),
36	policies: defineTable(PolicySchema)
37	.index("by_domainId", ["id"])
38	.index("by_workspaceId", ["workspaceId"]),
39	approvals: defineTable(ApprovalSchema)
40	.index("by_domainId", ["id"])
41	.index("by_workspaceId", ["workspaceId"])
42	.index("by_taskRunId", ["taskRunId"]),
43	taskRuns: defineTable(TaskRunSchema)
44	.index("by_domainId", ["id"])
45	.index("by_workspaceId", ["workspaceId"])
46	.index("by_sessionId", ["sessionId"]),
47	syncStates: defineTable(SyncStateSchema)
48	.index("by_domainId", ["id"])
49	.index("by_workspaceId", ["workspaceId"]),
50	events: defineTable(EventEnvelopeSchema)
51	.index("by_domainId", ["id"])
52	.index("by_workspaceId", ["workspaceId"])
53	.index("by_workspaceId_sequence", ["workspaceId", "sequence"]),
54	});
55
56	export type ExecutorConfectTables = TablesFromSchemaDefinition<typeof executorConfectSchema>;

v2/packages/state-convex/tsconfig.json+0−4

@@ -1,4 +0,0 @@
1	{
2	"extends": "../../tsconfig.json",
3	"include": ["src"]
4	}