lael-labs/executor

packages/control-plane/src/api/local-context.ts+7−1

 import type { WorkspaceId } from "#schema";
 import * as Effect from "effect/Effect";
+import {
+  RuntimeLocalWorkspaceMismatchError,
+} from "../runtime/local-errors";
 import { requireRuntimeLocalWorkspace } from "../runtime/local-runtime-context";
 import { ControlPlaneForbiddenError } from "./errors";
       new ControlPlaneForbiddenError({
         operation,
         message: "Requested workspace is not the active local workspace",
-        details: cause instanceof Error ? cause.message : String(cause),
+        details:
+          cause instanceof RuntimeLocalWorkspaceMismatchError
+            ? `requestedWorkspaceId=${cause.requestedWorkspaceId} activeWorkspaceId=${cause.activeWorkspaceId}`
+            : "Runtime local workspace is unavailable",
       })
     ),
   );

packages/control-plane/src/runtime/local-config.ts+40−13

 } from "#schema";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
+import {
+  LocalExecutorConfigDecodeError,
+  LocalFileSystemError,
+  unknownLocalErrorDetails,
+} from "./local-errors";
 const decodeLocalExecutorConfig = Schema.decodeUnknownSync(LocalExecutorConfigSchema);
     Exclude<R, FileSystem.FileSystem>
   >;
-const mapFileSystemError = (path: string, action: string) => (cause: unknown): Error => {
+const mapFileSystemError = (path: string, action: string) => (cause: unknown) =>
-  const message = cause instanceof Error ? cause.message : String(cause);
+  new LocalFileSystemError({
-  return new Error(`Failed to ${action} ${path}: ${message}`);
+    message: `Failed to ${action} ${path}: ${unknownLocalErrorDetails(cause)}`,
-};
+    action,
+    path,
+    details: unknownLocalErrorDetails(cause),
+  });
 const trimOrUndefined = (value: string | undefined | null): string | undefined => {
   const trimmed = value?.trim();
   env?: NodeJS.ProcessEnv;
   platform?: NodeJS.Platform;
   homeDirectory?: string;
-} = {}): Effect.Effect<string, Error> =>
+} = {}): Effect.Effect<string, LocalFileSystemError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const candidates = resolveDefaultHomeConfigCandidates(input);
       allowTrailingComma: true,
     });
     if (errors.length > 0) {
-      throw new Error(formatJsoncParseErrors(input.content, errors));
+      throw new LocalExecutorConfigDecodeError({
+        message: `Invalid executor config at ${input.path}: ${formatJsoncParseErrors(input.content, errors)}`,
+        path: input.path,
+        details: formatJsoncParseErrors(input.content, errors),
+      });
     }
     return decodeLocalExecutorConfig(parsed);
   } catch (cause) {
-    const message = cause instanceof Error ? cause.message : String(cause);
+    if (cause instanceof LocalExecutorConfigDecodeError) {
-    throw new Error(`Invalid executor config at ${input.path}: ${message}`);
+      throw cause;
+    }
+    throw new LocalExecutorConfigDecodeError({
+      message: `Invalid executor config at ${input.path}: ${unknownLocalErrorDetails(cause)}`,
+      path: input.path,
+      details: unknownLocalErrorDetails(cause),
+    });
   }
 };
 export const resolveLocalWorkspaceContext = (input: {
   cwd?: string;
   workspaceRoot?: string;
-} = {}): Effect.Effect<ResolvedLocalWorkspaceContext, Error> =>
+} = {}): Effect.Effect<ResolvedLocalWorkspaceContext, LocalFileSystemError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const cwd = resolve(input.cwd ?? process.cwd());
     const workspaceRoot = resolve(
 export const readOptionalLocalExecutorConfig = (
   path: string,
-): Effect.Effect<LocalExecutorConfig | null, Error> =>
+): Effect.Effect<LocalExecutorConfig | null, LocalFileSystemError | LocalExecutorConfigDecodeError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const exists = yield* fs.exists(path).pipe(
     return yield* Effect.try({
       try: () => parseJsonc({ path, content }),
       catch: (cause) =>
-        cause instanceof Error ? cause : new Error(String(cause)),
+        cause instanceof LocalExecutorConfigDecodeError
+          ? cause
+          : new LocalExecutorConfigDecodeError({
+              message: `Invalid executor config at ${path}: ${unknownLocalErrorDetails(cause)}`,
+              path,
+              details: unknownLocalErrorDetails(cause),
+            }),
     });
   }));
 export const loadLocalExecutorConfig = (
   context: ResolvedLocalWorkspaceContext,
-): Effect.Effect<LoadedLocalExecutorConfig, Error> =>
+): Effect.Effect<
+  LoadedLocalExecutorConfig,
+  LocalFileSystemError | LocalExecutorConfigDecodeError
+> =>
   Effect.gen(function* () {
     const [homeConfig, projectConfig] = yield* Effect.all([
       readOptionalLocalExecutorConfig(context.homeConfigPath),
 export const writeProjectLocalExecutorConfig = (input: {
   context: ResolvedLocalWorkspaceContext;
   config: LocalExecutorConfig;
-}): Effect.Effect<void, Error> =>
+}): Effect.Effect<void, LocalFileSystemError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     yield* fs.makeDirectory(input.context.configDirectory, { recursive: true }).pipe(

packages/control-plane/src/runtime/local-errors.ts+54−0

@@ -0,0 +1,54 @@
	1	import * as Data from "effect/Data";
	2
	3	export const unknownLocalErrorDetails = (cause: unknown): string =>
	4	cause instanceof Error ? cause.message : String(cause);
	5
	6	export class LocalFileSystemError extends Data.TaggedError("LocalFileSystemError")<{
	7	readonly message: string;
	8	readonly action: string;
	9	readonly path: string;
	10	readonly details: string;
	11	}> {}
	12
	13	export class LocalExecutorConfigDecodeError extends Data.TaggedError("LocalExecutorConfigDecodeError")<{
	14	readonly message: string;
	15	readonly path: string;
	16	readonly details: string;
	17	}> {}
	18
	19	export class LocalWorkspaceStateDecodeError extends Data.TaggedError("LocalWorkspaceStateDecodeError")<{
	20	readonly message: string;
	21	readonly path: string;
	22	readonly details: string;
	23	}> {}
	24
	25	export class LocalSourceArtifactDecodeError extends Data.TaggedError("LocalSourceArtifactDecodeError")<{
	26	readonly message: string;
	27	readonly path: string;
	28	readonly details: string;
	29	}> {}
	30
	31	export class RuntimeLocalWorkspaceUnavailableError extends Data.TaggedError("RuntimeLocalWorkspaceUnavailableError")<{
	32	readonly message: string;
	33	}> {}
	34
	35	export class RuntimeLocalWorkspaceMismatchError extends Data.TaggedError("RuntimeLocalWorkspaceMismatchError")<{
	36	readonly message: string;
	37	readonly requestedWorkspaceId: string;
	38	readonly activeWorkspaceId: string;
	39	}> {}
	40
	41	export class LocalConfiguredSourceNotFoundError extends Data.TaggedError("LocalConfiguredSourceNotFoundError")<{
	42	readonly message: string;
	43	readonly sourceId: string;
	44	}> {}
	45
	46	export class LocalSourceArtifactMissingError extends Data.TaggedError("LocalSourceArtifactMissingError")<{
	47	readonly message: string;
	48	readonly sourceId: string;
	49	}> {}
	50
	51	export class LocalUnsupportedSourceKindError extends Data.TaggedError("LocalUnsupportedSourceKindError")<{
	52	readonly message: string;
	53	readonly kind: string;
	54	}> {}

packages/control-plane/src/runtime/local-runtime-context.ts+25−8

   LoadedLocalExecutorConfig,
   ResolvedLocalWorkspaceContext,
 } from "./local-config";
+import {
+  RuntimeLocalWorkspaceMismatchError,
+  RuntimeLocalWorkspaceUnavailableError,
+} from "./local-errors";
 export type RuntimeLocalWorkspaceState = {
   context: ResolvedLocalWorkspaceContext;
     Effect.map((option) => (Option.isSome(option) ? option.value : null)),
   ) as Effect.Effect<RuntimeLocalWorkspaceState | null, never, never>;
-export const requireRuntimeLocalWorkspace = (workspaceId?: WorkspaceId) =>
+export const requireRuntimeLocalWorkspace = (
-  Effect.flatMap(getRuntimeLocalWorkspaceOption(), (runtimeLocalWorkspace) => {
+  workspaceId?: WorkspaceId,
+): Effect.Effect<
+  RuntimeLocalWorkspaceState,
+  RuntimeLocalWorkspaceUnavailableError | RuntimeLocalWorkspaceMismatchError,
+  never
+> =>
+  Effect.gen(function* () {
+    const runtimeLocalWorkspace = yield* getRuntimeLocalWorkspaceOption();
     if (runtimeLocalWorkspace === null) {
-      return Effect.fail(new Error("Runtime local workspace is unavailable"));
+      return yield* Effect.fail(
+        new RuntimeLocalWorkspaceUnavailableError({
+          message: "Runtime local workspace is unavailable",
+        }),
+      );
     }
     if (
       workspaceId !== undefined
       && runtimeLocalWorkspace.installation.workspaceId !== workspaceId
     ) {
-      return Effect.fail(
+      return yield* Effect.fail(
-        new Error(
+        new RuntimeLocalWorkspaceMismatchError({
-          `Workspace ${workspaceId} is not the active local workspace ${runtimeLocalWorkspace.installation.workspaceId}`,
+          message: `Workspace ${workspaceId} is not the active local workspace ${runtimeLocalWorkspace.installation.workspaceId}`,
-        ),
+          requestedWorkspaceId: workspaceId,
+          activeWorkspaceId: runtimeLocalWorkspace.installation.workspaceId,
+        }),
       );
     }
-    return Effect.succeed(runtimeLocalWorkspace);
+    return runtimeLocalWorkspace;
   });
 export const requireRuntimeLocalAccountId = (workspaceId?: WorkspaceId) =>

packages/control-plane/src/runtime/local-source-artifacts.ts+23−9

 import * as Schema from "effect/Schema";
 import type { ResolvedLocalWorkspaceContext } from "./local-config";
+import {
+  LocalFileSystemError,
+  LocalSourceArtifactDecodeError,
+  unknownLocalErrorDetails,
+} from "./local-errors";
 import {
   createSourceRecipeRevisionRecord,
   stableSourceRecipeId,
     Exclude<R, FileSystem.FileSystem>
   >;
-const mapFileSystemError = (path: string, action: string) => (cause: unknown): Error => {
+const mapFileSystemError = (path: string, action: string) => (cause: unknown) =>
-  const message = cause instanceof Error ? cause.message : String(cause);
+  new LocalFileSystemError({
-  return new Error(`Failed to ${action} ${path}: ${message}`);
+    message: `Failed to ${action} ${path}: ${unknownLocalErrorDetails(cause)}`,
-};
+    action,
+    path,
+    details: unknownLocalErrorDetails(cause),
+  });
 const localSourceArtifactPath = (input: {
   context: ResolvedLocalWorkspaceContext;
 export const readLocalSourceArtifact = (input: {
   context: ResolvedLocalWorkspaceContext;
   sourceId: string;
-}): Effect.Effect<LocalSourceArtifact | null, Error> =>
+}): Effect.Effect<
+  LocalSourceArtifact | null,
+  LocalFileSystemError | LocalSourceArtifactDecodeError
+> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = localSourceArtifactPath(input);
     return yield* Effect.try({
       try: () => decodeLocalSourceArtifact(JSON.parse(content) as unknown),
       catch: (cause) => {
-        const message = cause instanceof Error ? cause.message : String(cause);
+        return new LocalSourceArtifactDecodeError({
-        return new Error(`Invalid local source artifact at ${path}: ${message}`);
+          message: `Invalid local source artifact at ${path}: ${unknownLocalErrorDetails(cause)}`,
+          path,
+          details: unknownLocalErrorDetails(cause),
+        });
       },
     });
   }));
   context: ResolvedLocalWorkspaceContext;
   sourceId: string;
   artifact: LocalSourceArtifact;
-}): Effect.Effect<void, Error> =>
+}): Effect.Effect<void, LocalFileSystemError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const directory = join(input.context.artifactsDirectory, "sources");
 export const removeLocalSourceArtifact = (input: {
   context: ResolvedLocalWorkspaceContext;
   sourceId: string;
-}): Effect.Effect<void, Error> =>
+}): Effect.Effect<void, LocalFileSystemError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = localSourceArtifactPath(input);

packages/control-plane/src/runtime/local-workspace-state.ts+19−8

 import * as Schema from "effect/Schema";
 import type { ResolvedLocalWorkspaceContext } from "./local-config";
+import {
+  LocalFileSystemError,
+  LocalWorkspaceStateDecodeError,
+  unknownLocalErrorDetails,
+} from "./local-errors";
 const WORKSPACE_STATE_BASENAME = "workspace-state.json";
     Exclude<R, FileSystem.FileSystem>
   >;
-const mapFileSystemError = (path: string, action: string) => (cause: unknown): Error => {
+const mapFileSystemError = (path: string, action: string) => (cause: unknown) =>
-  const message = cause instanceof Error ? cause.message : String(cause);
+  new LocalFileSystemError({
-  return new Error(`Failed to ${action} ${path}: ${message}`);
+    message: `Failed to ${action} ${path}: ${unknownLocalErrorDetails(cause)}`,
-};
+    action,
+    path,
+    details: unknownLocalErrorDetails(cause),
+  });
 const defaultLocalWorkspaceState = (): LocalWorkspaceState => ({
   version: 1,
 export const loadLocalWorkspaceState = (
   context: ResolvedLocalWorkspaceContext,
-): Effect.Effect<LocalWorkspaceState, Error> =>
+): Effect.Effect<LocalWorkspaceState, LocalFileSystemError | LocalWorkspaceStateDecodeError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = localWorkspaceStatePath(context);
     return yield* Effect.try({
       try: () => decodeLocalWorkspaceState(JSON.parse(content) as unknown),
       catch: (cause) => {
-        const message = cause instanceof Error ? cause.message : String(cause);
+        return new LocalWorkspaceStateDecodeError({
-        return new Error(`Invalid local workspace state at ${path}: ${message}`);
+          message: `Invalid local workspace state at ${path}: ${unknownLocalErrorDetails(cause)}`,
+          path,
+          details: unknownLocalErrorDetails(cause),
+        });
       },
     });
   }));
 export const writeLocalWorkspaceState = (input: {
   context: ResolvedLocalWorkspaceContext;
   state: LocalWorkspaceState;
-}): Effect.Effect<void, Error> =>
+}): Effect.Effect<void, LocalFileSystemError> =>
   provideNodeFileSystem(Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     yield* fs.makeDirectory(input.context.stateDirectory, { recursive: true }).pipe(

packages/control-plane/src/runtime/source-recipes-runtime.ts+6−2

 import {
   readLocalSourceArtifact,
 } from "./local-source-artifacts";
+import { LocalSourceArtifactMissingError } from "./local-errors";
 import {
   requireRuntimeLocalWorkspace,
 } from "./local-runtime-context";
   workspaceId: WorkspaceId;
   sourceId: Source["id"];
   actorAccountId?: AccountId | null;
-}): Effect.Effect<LoadedSourceRecipe, Error, never> =>
+}): Effect.Effect<LoadedSourceRecipe, Error | LocalSourceArtifactMissingError, never> =>
   Effect.gen(function* () {
     const runtimeLocalWorkspace = yield* requireRuntimeLocalWorkspace(input.workspaceId);
     const source = yield* loadSourceById(input.rows, {
     });
     if (artifact === null) {
       return yield* Effect.fail(
-        new Error(`Recipe artifact missing for source ${input.sourceId}`),
+        new LocalSourceArtifactMissingError({
+          message: `Recipe artifact missing for source ${input.sourceId}`,
+          sourceId: input.sourceId,
+        }),
       );
     }

packages/control-plane/src/runtime/source-store.ts+61−7

@@ -30,6 +30,15 @@ import { · 29 unmodified lines
30	readLocalSourceArtifact,	30	readLocalSourceArtifact,
31	removeLocalSourceArtifact,	31	removeLocalSourceArtifact,
32	} from "./local-source-artifacts";	32	} from "./local-source-artifacts";
		33	import {
		34	LocalConfiguredSourceNotFoundError,
		35	LocalExecutorConfigDecodeError,
		36	LocalFileSystemError,
		37	LocalUnsupportedSourceKindError,
		38	LocalWorkspaceStateDecodeError,
		39	RuntimeLocalWorkspaceMismatchError,
		40	RuntimeLocalWorkspaceUnavailableError,
		41	} from "./local-errors";
33	import {	42	import {
34	requireRuntimeLocalWorkspace,	43	requireRuntimeLocalWorkspace,
35	} from "./local-runtime-context";	44	} from "./local-runtime-context";
@@ -231,7 +240,21 @@ const configAuthFromSource = (input: { · 195 unmodified lines
231	return input.existingConfigAuth;	240	return input.existingConfigAuth;
232	};	241	};
233		242
234	const resolveRuntimeLocalWorkspace = (workspaceId: WorkspaceId) =>	243	const resolveRuntimeLocalWorkspace = (workspaceId: WorkspaceId): Effect.Effect<{
		244	context: ResolvedLocalWorkspaceContext;
		245	installation: {
		246	workspaceId: WorkspaceId;
		247	accountId: AccountId;
		248	};
		249	loadedConfig: LoadedLocalExecutorConfig;
		250	workspaceState: LocalWorkspaceState;
		251	},
		252	\| RuntimeLocalWorkspaceUnavailableError
		253	\| RuntimeLocalWorkspaceMismatchError
		254	\| LocalFileSystemError
		255	\| LocalExecutorConfigDecodeError
		256	\| LocalWorkspaceStateDecodeError,
		257	never> =>
235	Effect.gen(function* () {	258	Effect.gen(function* () {
236	const runtimeLocalWorkspace = yield* requireRuntimeLocalWorkspace(workspaceId);	259	const runtimeLocalWorkspace = yield* requireRuntimeLocalWorkspace(workspaceId);
237	const loadedConfig = yield* loadLocalExecutorConfig(runtimeLocalWorkspace.context);	260	const loadedConfig = yield* loadLocalExecutorConfig(runtimeLocalWorkspace.context);
@@ -256,11 +279,16 @@ const buildLocalSourceRecord = (input: { · 18 unmodified lines
256	}): Effect.Effect<{	279	}): Effect.Effect<{
257	source: Source;	280	source: Source;
258	sourceId: SourceId;	281	sourceId: SourceId;
259	}, Error, never> =>	282	}, LocalConfiguredSourceNotFoundError \| Error, never> =>
260	Effect.gen(function* () {	283	Effect.gen(function* () {
261	const sourceConfig = input.loadedConfig.config?.sources?.[input.sourceId];	284	const sourceConfig = input.loadedConfig.config?.sources?.[input.sourceId];
262	if (!sourceConfig) {	285	if (!sourceConfig) {
263	return yield* Effect.fail(new Error(`Configured source not found for id ${input.sourceId}`));	286	return yield* Effect.fail(
		287	new LocalConfiguredSourceNotFoundError({
		288	message: `Configured source not found for id ${input.sourceId}`,
		289	sourceId: input.sourceId,
		290	}),
		291	);
264	}	292	}
265		293
266	const existingState = input.workspaceState.sources[input.sourceId];	294	const existingState = input.workspaceState.sources[input.sourceId];
@@ -356,7 +384,17 @@ export const loadSourcesInWorkspace = ( · 89 unmodified lines
356	options: {	384	options: {
357	actorAccountId?: AccountId \| null;	385	actorAccountId?: AccountId \| null;
358	} = {},	386	} = {},
359	) =>	387	): Effect.Effect<
		388	readonly Source[],
		389	\| RuntimeLocalWorkspaceUnavailableError
		390	\| RuntimeLocalWorkspaceMismatchError
		391	\| LocalFileSystemError
		392	\| LocalExecutorConfigDecodeError
		393	\| LocalWorkspaceStateDecodeError
		394	\| LocalConfiguredSourceNotFoundError
		395	\| Error,
		396	never
		397	> =>
360	Effect.gen(function* () {	398	Effect.gen(function* () {
361	const localWorkspace = yield* resolveRuntimeLocalWorkspace(workspaceId);	399	const localWorkspace = yield* resolveRuntimeLocalWorkspace(workspaceId);
362	const authArtifacts = yield* rows.authArtifacts.listByWorkspaceId(workspaceId);	400	const authArtifacts = yield* rows.authArtifacts.listByWorkspaceId(workspaceId);
@@ -382,13 +420,26 @@ export const loadSourceById = (rows: SqlControlPlaneRows, input: { · 19 unmodified lines
382	workspaceId: WorkspaceId;	420	workspaceId: WorkspaceId;
383	sourceId: Source["id"];	421	sourceId: Source["id"];
384	actorAccountId?: AccountId \| null;	422	actorAccountId?: AccountId \| null;
385	}) =>	423	}): Effect.Effect<
		424	Source,
		425	\| RuntimeLocalWorkspaceUnavailableError
		426	\| RuntimeLocalWorkspaceMismatchError
		427	\| LocalFileSystemError
		428	\| LocalExecutorConfigDecodeError
		429	\| LocalWorkspaceStateDecodeError
		430	\| LocalConfiguredSourceNotFoundError
		431	\| Error,
		432	never
		433	> =>
386	Effect.gen(function* () {	434	Effect.gen(function* () {
387	const localWorkspace = yield* resolveRuntimeLocalWorkspace(input.workspaceId);	435	const localWorkspace = yield* resolveRuntimeLocalWorkspace(input.workspaceId);
388	const authArtifacts = yield* rows.authArtifacts.listByWorkspaceId(input.workspaceId);	436	const authArtifacts = yield* rows.authArtifacts.listByWorkspaceId(input.workspaceId);
389	if (!localWorkspace.loadedConfig.config?.sources?.[input.sourceId]) {	437	if (!localWorkspace.loadedConfig.config?.sources?.[input.sourceId]) {
390	return yield* Effect.fail(	438	return yield* Effect.fail(
391	new Error(`Source not found: workspaceId=${input.workspaceId} sourceId=${input.sourceId}`),	439	new LocalConfiguredSourceNotFoundError({
		440	message: `Source not found: workspaceId=${input.workspaceId} sourceId=${input.sourceId}`,
		441	sourceId: input.sourceId,
		442	}),
392	);	443	);
393	}	444	}
394		445
@@ -456,7 +507,10 @@ const configSourceFromLocalSource = (input: { · 61 unmodified lines
456	binding: cloneJson(input.source.binding) as Extract<LocalConfigSource, { kind: "mcp" }>["binding"],	507	binding: cloneJson(input.source.binding) as Extract<LocalConfigSource, { kind: "mcp" }>["binding"],
457	};	508	};
458	default:	509	default:
459	throw new Error(`Unsupported source kind for local config: ${input.source.kind}`);	510	throw new LocalUnsupportedSourceKindError({
		511	message: `Unsupported source kind for local config: ${input.source.kind}`,
		512	kind: input.source.kind,
		513	});
460	}	514	}
461	};	515	};
462		516